| .\" @(#)rpc_svc_create.3n 1.26 93/08/26 SMI; from SVr4 |
| .\" Copyright 1989 AT&T |
| .\" @(#)rpc_svc_create 1.3 89/06/28 SMI; |
| .\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. |
| .\" $FreeBSD: src/lib/libc/rpc/rpc_svc_create.3,v 1.7 2003/09/08 19:57:15 ru Exp $ |
| .Dd May 3, 1993 |
| .Dt RPC_SVC_CREATE 3 |
| .Os |
| .Sh NAME |
| .Nm rpc_svc_create , |
| .Nm svc_control , |
| .Nm svc_create , |
| .Nm svc_destroy , |
| .Nm svc_dg_create , |
| .Nm svc_fd_create , |
| .Nm svc_raw_create , |
| .Nm svc_tli_create , |
| .Nm svc_tp_create , |
| .Nm svc_vc_create |
| .Nd library routines for the creation of server handles |
| .Sh LIBRARY |
| .Lb libc |
| .Sh SYNOPSIS |
| .In rpc/rpc.h |
| .Ft bool_t |
| .Fn svc_control "SVCXPRT *svc" "const u_int req" "void *info" |
| .Ft int |
| .Fn svc_create "void (*dispatch)(struct svc_req *, SVCXPRT *)" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype" |
| .Ft SVCXPRT * |
| .Fn svc_dg_create "const int fildes" "const u_int sendsz" "const u_int recvsz" |
| .Ft void |
| .Fn svc_destroy "SVCXPRT *xprt" |
| .Ft "SVCXPRT *" |
| .Fn svc_fd_create "const int fildes" "const u_int sendsz" "const u_int recvsz" |
| .Ft "SVCXPRT *" |
| .Fn svc_raw_create "void" |
| .Ft "SVCXPRT *" |
| .Fn svc_tli_create "const int fildes" "const struct netconfig *netconf" "const struct t_bind *bindaddr" "const u_int sendsz" "const u_int recvsz" |
| .Ft "SVCXPRT *" |
| .Fn svc_tp_create "void (*dispatch)(struct svc_req *, SVCXPRT *)" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" |
| .Ft "SVCXPRT *" |
| .Fn svc_vc_create "const int fildes" "const u_int sendsz" "const u_int recvsz" |
| .Sh DESCRIPTION |
| These routines are part of the RPC |
| library which allows C language programs to make procedure |
| calls on servers across the network. |
| These routines deal with the creation of service handles. |
| Once the handle is created, the server can be invoked by calling |
| .Fn svc_run . |
| .Sh Routines |
| See |
| .Xr rpc 3 |
| for the definition of the |
| .Vt SVCXPRT |
| data structure. |
| .Bl -tag -width XXXXX |
| .It Fn svc_control |
| A function to change or retrieve various information |
| about a service object. |
| The |
| .Fa req |
| argument |
| indicates the type of operation and |
| .Fa info |
| is a pointer to the information. |
| The supported values of |
| .Fa req , |
| their argument types, and what they do are: |
| .Bl -tag -width SVCGET_XID |
| .It Dv SVCGET_VERSQUIET |
| If a request is received for a program number |
| served by this server but the version number |
| is outside the range registered with the server, |
| an |
| .Dv RPC_PROGVERSMISMATCH |
| error will normally |
| be returned. |
| The |
| .Fa info |
| argument |
| should be a pointer to an |
| integer. |
| Upon successful completion of the |
| .Dv SVCGET_VERSQUIET |
| request, |
| .Fa *info |
| contains an |
| integer which describes the server's current |
| behavior: 0 indicates normal server behavior |
| (that is, an |
| .Dv RPC_PROGVERSMISMATCH |
| error |
| will be returned); 1 indicates that the out of |
| range request will be silently ignored. |
| .It Dv SVCSET_VERSQUIET |
| If a request is received for a program number |
| served by this server but the version number |
| is outside the range registered with the server, |
| an |
| .Dv RPC_PROGVERSMISMATCH |
| error will normally |
| be returned. |
| It is sometimes desirable to |
| change this behavior. |
| The |
| .Fa info |
| argument |
| should be a |
| pointer to an integer which is either 0 |
| (indicating normal server behavior - an |
| .Dv RPC_PROGVERSMISMATCH |
| error will be returned), |
| or 1 (indicating that the out of range request |
| should be silently ignored). |
| .El |
| .It Fn svc_create |
| The |
| .Fn svc_create |
| function |
| creates server handles for all the transports |
| belonging to the class |
| .Fa nettype . |
| The |
| .Fa nettype |
| argument |
| defines a class of transports which can be used |
| for a particular application. |
| The transports are tried in left to right order in |
| .Ev NETPATH |
| variable or in top to bottom order in the netconfig database. |
| If |
| .Fa nettype |
| is |
| .Dv NULL , |
| it defaults to |
| .Qq netpath . |
| .Pp |
| The |
| .Fn svc_create |
| function |
| registers itself with the rpcbind |
| service (see |
| .Xr rpcbind 8 ) . |
| The |
| .Fa dispatch |
| function |
| is called when there is a remote procedure call for the given |
| .Fa prognum |
| and |
| .Fa versnum ; |
| this requires calling |
| .Fn svc_run |
| (see |
| .Fn svc_run |
| in |
| .Xr rpc_svc_reg 3 ) . |
| If |
| .Fn svc_create |
| succeeds, it returns the number of server |
| handles it created, |
| otherwise it returns 0 and an error message is logged. |
| .It Fn svc_destroy |
| A function macro that destroys the RPC |
| service handle |
| .Fa xprt . |
| Destruction usually involves deallocation |
| of private data structures, |
| including |
| .Fa xprt |
| itself. |
| Use of |
| .Fa xprt |
| is undefined after calling this routine. |
| .It Fn svc_dg_create |
| This routine creates a connectionless RPC |
| service handle, and returns a pointer to it. |
| This routine returns |
| .Dv NULL |
| if it fails, and an error message is logged. |
| The |
| .Fa sendsz |
| and |
| .Fa recvsz |
| arguments |
| are arguments used to specify the size of the buffers. |
| If they are 0, suitable defaults are chosen. |
| The file descriptor |
| .Fa fildes |
| should be open and bound. |
| The server is not registered with |
| .Xr rpcbind 8 . |
| .Pp |
| Warning: |
| since connectionless-based RPC |
| messages can only hold limited amount of encoded data, |
| this transport cannot be used for procedures |
| that take large arguments or return huge results. |
| .It Fn svc_fd_create |
| This routine creates a service on top of an open and bound file descriptor, |
| and returns the handle to it. |
| Typically, this descriptor is a connected file descriptor for a |
| connection-oriented transport. |
| The |
| .Fa sendsz |
| and |
| .Fa recvsz |
| arguments |
| indicate sizes for the send and receive buffers. |
| If they are 0, reasonable defaults are chosen. |
| This routine returns |
| .Dv NULL |
| if it fails, and an error message is logged. |
| .It Fn svc_raw_create |
| This routine creates an RPC |
| service handle and returns a pointer to it. |
| The transport is really a buffer within the process's |
| address space, so the corresponding RPC |
| client should live in the same address space; |
| (see |
| .Fn clnt_raw_create |
| in |
| .Xr rpc_clnt_create 3 ) . |
| This routine allows simulation of RPC and acquisition of |
| RPC overheads (such as round trip times), |
| without any kernel and networking interference. |
| This routine returns |
| .Dv NULL |
| if it fails, and an error message is logged. |
| .Pp |
| Note: |
| .Fn svc_run |
| should not be called when the raw interface is being used. |
| .It Fn svc_tli_create |
| This routine creates an RPC |
| server handle, and returns a pointer to it. |
| The |
| .Fa fildes |
| argument |
| is the file descriptor on which the service is listening. |
| If |
| .Fa fildes |
| is |
| .Dv RPC_ANYFD , |
| it opens a file descriptor on the transport specified by |
| .Fa netconf . |
| If the file descriptor is unbound and |
| .Fa bindaddr |
| is not |
| .Dv NULL , |
| .Fa fildes |
| is bound to the address specified by |
| .Fa bindaddr , |
| otherwise |
| .Fa fildes |
| is bound to a default address chosen by the transport. |
| .Pp |
| Note: the |
| .Vt t_bind |
| structure comes from the TLI/XTI SysV interface, which |
| .Nx |
| does not use. |
| The structure is defined in |
| .In rpc/types.h |
| for compatibility as: |
| .Bd -literal |
| struct t_bind { |
| struct netbuf addr; /* network address, see rpc(3) */ |
| unsigned int qlen; /* queue length (for listen(2)) */ |
| }; |
| .Ed |
| .Pp |
| In the case where the default address is chosen, |
| the number of outstanding connect requests is set to 8 |
| for connection-oriented transports. |
| The user may specify the size of the send and receive buffers |
| with the arguments |
| .Fa sendsz |
| and |
| .Fa recvsz ; |
| values of 0 choose suitable defaults. |
| This routine returns |
| .Dv NULL |
| if it fails, |
| and an error message is logged. |
| The server is not registered with the |
| .Xr rpcbind 8 |
| service. |
| .It Fn svc_tp_create |
| The |
| .Fn svc_tp_create |
| function |
| creates a server handle for the network |
| specified by |
| .Fa netconf , |
| and registers itself with the rpcbind service. |
| The |
| .Fa dispatch |
| function |
| is called when there is a remote procedure call |
| for the given |
| .Fa prognum |
| and |
| .Fa versnum ; |
| this requires calling |
| .Fn svc_run . |
| The |
| .Fn svc_tp_create |
| function |
| returns the service handle if it succeeds, |
| otherwise a |
| .Dv NULL |
| is returned and an error message is logged. |
| .It Fn svc_vc_create |
| This routine creates a connection-oriented RPC |
| service and returns a pointer to it. |
| This routine returns |
| .Dv NULL |
| if it fails, and an error message is logged. |
| The users may specify the size of the send and receive buffers |
| with the arguments |
| .Fa sendsz |
| and |
| .Fa recvsz ; |
| values of 0 choose suitable defaults. |
| The file descriptor |
| .Fa fildes |
| should be open and bound. |
| The server is not registered with the |
| .Xr rpcbind 8 |
| service. |
| .El |
| .Sh SEE ALSO |
| .Xr rpc 3 , |
| .Xr rpc_svc_calls 3 , |
| .Xr rpc_svc_err 3 , |
| .Xr rpc_svc_reg 3 , |
| .Xr rpcbind 8 |