diff options
Diffstat (limited to 'man/rpc_soc.3t')
| -rw-r--r-- | man/rpc_soc.3t | 1726 |
1 files changed, 1726 insertions, 0 deletions
diff --git a/man/rpc_soc.3t b/man/rpc_soc.3t new file mode 100644 index 0000000..f26c0af --- /dev/null +++ b/man/rpc_soc.3t @@ -0,0 +1,1726 @@ +.\" @(#)rpc.3n 2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI +.\" $NetBSD: rpc_soc.3,v 1.2 2000/06/07 13:39:43 simonb Exp $ +.\" $FreeBSD: src/lib/libc/rpc/rpc_soc.3,v 1.12 2003/02/06 11:04:47 charnier Exp $ +.\" +.Dd February 16, 1988 +.Dt RPC_SOC 3 +.Os +.Sh NAME +.Nm rpc_soc , +.Nm auth_destroy , +.Nm authnone_create , +.Nm authunix_create , +.Nm authunix_create_default , +.Nm callrpc , +.Nm clnt_broadcast , +.Nm clnt_call , +.Nm clnt_control , +.Nm clnt_create , +.Nm clnt_destroy , +.Nm clnt_freeres , +.Nm clnt_geterr , +.Nm clnt_pcreateerror , +.Nm clnt_perrno , +.Nm clnt_perror , +.Nm clnt_spcreateerror , +.Nm clnt_sperrno , +.Nm clnt_sperror , +.Nm clntraw_create , +.Nm clnttcp_create , +.Nm clntudp_bufcreate , +.Nm clntudp_create , +.Nm clntunix_create , +.Nm get_myaddress , +.Nm pmap_getmaps , +.Nm pmap_getport , +.Nm pmap_rmtcall , +.Nm pmap_set , +.Nm pmap_unset , +.Nm registerrpc , +.Nm rpc_createerr , +.Nm svc_destroy , +.Nm svc_fds , +.Nm svc_fdset , +.Nm svc_getargs , +.Nm svc_getcaller , +.Nm svc_getreq , +.Nm svc_getreqset , +.Nm svc_register , +.Nm svc_run , +.Nm svc_sendreply , +.Nm svc_unregister , +.Nm svcerr_auth , +.Nm svcerr_decode , +.Nm svcerr_noproc , +.Nm svcerr_noprog , +.Nm svcerr_progvers , +.Nm svcerr_systemerr , +.Nm svcerr_weakauth , +.Nm svcfd_create , +.Nm svcunixfd_create , +.Nm svcraw_create , +.Nm svcunix_create , +.Nm xdr_accepted_reply , +.Nm xdr_authunix_parms , +.Nm xdr_callhdr , +.Nm xdr_callmsg , +.Nm xdr_opaque_auth , +.Nm xdr_pmap , +.Nm xdr_pmaplist , +.Nm xdr_rejected_reply , +.Nm xdr_replymsg , +.Nm xprt_register , +.Nm xprt_unregister +.Nd "library routines for remote procedure calls" +.Sh SYNOPSIS +.In rpc/rpc.h +.Pp +See +.Sx DESCRIPTION +for function declarations. +.Sh DESCRIPTION +.Bf -symbolic +The +.Fn svc_* +and +.Fn clnt_* +functions described in this page are the old, TS-RPC +interface to the XDR and RPC library, and exist for backward compatibility. +The new interface is described in the pages +referenced from +.Xr rpc 3 . +.Ef +.Pp +These routines allow C programs to make procedure +calls on other machines across the network. +First, the client calls a procedure to send a +data packet to the server. +Upon receipt of the packet, the server calls a dispatch routine +to perform the requested service, and then sends back a +reply. +Finally, the procedure call returns to the client. +.Pp +Routines that are used for Secure +.Tn RPC ( DES +authentication) are described in +.Xr rpc_secure 3 . +Secure +.Tn RPC +can be used only if +.Tn DES +encryption is available. +.Bl -tag -width indent -compact +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn auth_destroy "AUTH *auth" +.Xc +.Pp +A macro that destroys the authentication information associated with +.Fa auth . +Destruction usually involves deallocation of private data +structures. +The use of +.Fa auth +is undefined after calling +.Fn auth_destroy . +.Pp +.It Xo +.Ft "AUTH *" +.Xc +.It Xo +.Fn authnone_create +.Xc +.Pp +Create and return an +.Tn RPC +authentication handle that passes nonusable authentication +information with each remote procedure call. +This is the +default authentication used by +.Tn RPC . +.Pp +.It Xo +.Ft "AUTH *" +.Xc +.It Xo +.Fn authunix_create "char *host" "int uid" "int gid" "int len" "int *aup_gids" +.Xc +.Pp +Create and return an +.Tn RPC +authentication handle that contains +.Ux +authentication information. +The +.Fa host +argument +is the name of the machine on which the information was +created; +.Fa uid +is the user's user ID; +.Fa gid +is the user's current group ID; +.Fa len +and +.Fa aup_gids +refer to a counted array of groups to which the user belongs. +It is easy to impersonate a user. +.Pp +.It Xo +.Ft "AUTH *" +.Xc +.It Xo +.Fn authunix_create_default +.Xc +.Pp +Calls +.Fn authunix_create +with the appropriate arguments. +.Pp +.It Xo +.Ft int +.Fo callrpc +.Fa "char *host" +.Fa "u_long prognum" +.Fa "u_long versnum" +.Fa "u_long procnum" +.Fa "xdrproc_t inproc" +.Fa "void *in" +.Fa "xdrproc_t outproc" +.Fa "void *out" +.Fc +.Xc +.Pp +Call the remote procedure associated with +.Fa prognum , +.Fa versnum , +and +.Fa procnum +on the machine +.Fa host . +The +.Fa in +argument +is the address of the procedure's argument(s), and +.Fa out +is the address of where to place the result(s); +.Fa inproc +is used to encode the procedure's arguments, and +.Fa outproc +is used to decode the procedure's results. +This routine returns zero if it succeeds, or the value of +.Vt "enum clnt_stat" +cast to an integer if it fails. +The routine +.Fn clnt_perrno +is handy for translating failure statuses into messages. +.Pp +Warning: calling remote procedures with this routine +uses +.Tn UDP/IP +as a transport; see +.Fn clntudp_create +for restrictions. +You do not have control of timeouts or authentication using +this routine. +.Pp +.It Xo +.Ft "enum clnt_stat" +.Xc +.It Xo +.Fo clnt_broadcast +.Fa "u_long prognum" +.Fa "u_long versnum" +.Fa "u_long procnum" +.Fa "xdrproc_t inproc" +.Fa "char *in" +.Fa "xdrproc_t outproc" +.Fa "char *out" +.Fa "bool_t (*eachresult)(caddr_t, struct sockaddr_in *)" +.Fc +.Xc +.Pp +Like +.Fn callrpc , +except the call message is broadcast to all locally +connected broadcast nets. +Each time it receives a +response, this routine calls +.Fn eachresult , +whose form is: +.Bd -ragged -offset indent +.Ft bool_t +.Fn eachresult "caddr_t out" "struct sockaddr_in *addr" +.Ed +.Pp +where +.Fa out +is the same as +.Fa out +passed to +.Fn clnt_broadcast , +except that the remote procedure's output is decoded there; +.Fa addr +points to the address of the machine that sent the results. +If +.Fn eachresult +returns zero, +.Fn clnt_broadcast +waits for more replies; otherwise it returns with appropriate +status. +.Pp +Warning: broadcast sockets are limited in size to the +maximum transfer unit of the data link. +For ethernet, +this value is 1500 bytes. +.Pp +.It Xo +.Ft "enum clnt_stat" +.Xc +.It Xo +.Fo clnt_call +.Fa "CLIENT *clnt" +.Fa "u_long procnum" +.Fa "xdrproc_t inproc" +.Fa "char *in" +.Fa "xdrproc_t outproc" +.Fa "char *out" +.Fa "struct timeval tout" +.Fc +.Xc +.Pp +A macro that calls the remote procedure +.Fa procnum +associated with the client handle, +.Fa clnt , +which is obtained with an +.Tn RPC +client creation routine such as +.Fn clnt_create . +The +.Fa in +argument +is the address of the procedure's argument(s), and +.Fa out +is the address of where to place the result(s); +.Fa inproc +is used to encode the procedure's arguments, and +.Fa outproc +is used to decode the procedure's results; +.Fa tout +is the time allowed for results to come back. +.Pp +.It Xo +.Ft void +.Fn clnt_destroy "CLIENT *clnt" +.Xc +.Pp +A macro that destroys the client's +.Tn RPC +handle. +Destruction usually involves deallocation +of private data structures, including +.Fa clnt +itself. +Use of +.Fa clnt +is undefined after calling +.Fn clnt_destroy . +If the +.Tn RPC +library opened the associated socket, it will close it also. +Otherwise, the socket remains open. +.Pp +.It Xo +.Ft CLIENT * +.Xc +.It Xo +.Fn clnt_create "char *host" "u_long prog" "u_long vers" "char *proto" +.Xc +.Pp +Generic client creation routine. +The +.Fa host +argument +identifies the name of the remote host where the server +is located. +The +.Fa proto +argument +indicates which kind of transport protocol to use. +The +currently supported values for this field are +.Qq Li udp +and +.Qq Li tcp . +Default timeouts are set, but can be modified using +.Fn clnt_control . +.Pp +Warning: Using +.Tn UDP +has its shortcomings. +Since +.Tn UDP Ns \-based +.Tn RPC +messages can only hold up to 8 Kbytes of encoded data, +this transport cannot be used for procedures that take +large arguments or return huge results. +.Pp +.It Xo +.Ft bool_t +.Xc +.It Xo +.Fn clnt_control "CLIENT *cl" "u_int req" "char *info" +.Xc +.Pp +A macro used to change or retrieve various information +about a client object. +The +.Fa req +argument +indicates the type of operation, and +.Fa info +is a pointer to the information. +For both +.Tn UDP +and +.Tn TCP , +the supported values of +.Fa req +and their argument types and what they do are: +.Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in" +.It Dv CLSET_TIMEOUT Ta Xo +.Vt "struct timeval" Ta "set total timeout" +.Xc +.It Dv CLGET_TIMEOUT Ta Xo +.Vt "struct timeval" Ta "get total timeout" +.Xc +.El +.Pp +Note: if you set the timeout using +.Fn clnt_control , +the timeout argument passed to +.Fn clnt_call +will be ignored in all future calls. +.Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in" +.It Dv CLGET_SERVER_ADDR Ta Xo +.Vt "struct sockaddr_in" Ta "get server's address" +.Xc +.El +.Pp +The following operations are valid for +.Tn UDP +only: +.Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in" +.It Dv CLSET_RETRY_TIMEOUT Ta Xo +.Vt "struct timeval" Ta "set the retry timeout" +.Xc +.It Dv CLGET_RETRY_TIMEOUT Ta Xo +.Vt "struct timeval" Ta "get the retry timeout" +.Xc +.El +.Pp +The retry timeout is the time that +.Tn "UDP RPC" +waits for the server to reply before +retransmitting the request. +.Pp +.It Xo +.Ft bool_t +.Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out" +.Xc +.Pp +A macro that frees any data allocated by the +.Tn RPC/XDR +system when it decoded the results of an +.Tn RPC +call. +The +.Fa out +argument +is the address of the results, and +.Fa outproc +is the +.Tn XDR +routine describing the results. +This routine returns one if the results were successfully +freed, +and zero otherwise. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn clnt_geterr "CLIENT *clnt" "struct rpc_err *errp" +.Xc +.Pp +A macro that copies the error structure out of the client +handle +to the structure at address +.Fa errp . +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn clnt_pcreateerror "char *s" +.Xc +.Pp +prints a message to standard error indicating +why a client +.Tn RPC +handle could not be created. +The message is prepended with string +.Fa s +and a colon. +A newline is appended at the end of the message. +Used when a +.Fn clnt_create , +.Fn clntraw_create , +.Fn clnttcp_create , +or +.Fn clntudp_create +call fails. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn clnt_perrno "enum clnt_stat stat" +.Xc +.Pp +Print a message to standard error corresponding +to the condition indicated by +.Fa stat . +A newline is appended at the end of the message. +Used after +.Fn callrpc . +.Pp +.It Xo +.Ft void +.Fn clnt_perror "CLIENT *clnt" "char *s" +.Xc +.Pp +Print a message to standard error indicating why an +.Tn RPC +call failed; +.Fa clnt +is the handle used to do the call. +The message is prepended with string +.Fa s +and a colon. +A newline is appended at the end of the message. +Used after +.Fn clnt_call . +.Pp +.It Xo +.Ft "char *" +.Xc +.It Xo +.Fn clnt_spcreateerror "char *s" +.Xc +.Pp +Like +.Fn clnt_pcreateerror , +except that it returns a string +instead of printing to the standard error. +.Pp +Bugs: returns pointer to static data that is overwritten +on each call. +.Pp +.It Xo +.Ft "char *" +.Xc +.It Xo +.Fn clnt_sperrno "enum clnt_stat stat" +.Xc +.Pp +Take the same arguments as +.Fn clnt_perrno , +but instead of sending a message to the standard error +indicating why an +.Tn RPC +call failed, return a pointer to a string which contains +the message. +.Pp +The +.Fn clnt_sperrno +function +is used instead of +.Fn clnt_perrno +if the program does not have a standard error (as a program +running as a server quite likely does not), or if the +programmer +does not want the message to be output with +.Fn printf , +or if a message format different from that supported by +.Fn clnt_perrno +is to be used. +.Pp +Note: unlike +.Fn clnt_sperror +and +.Fn clnt_spcreateerror , +.Fn clnt_sperrno +returns pointer to static data, but the +result will not get overwritten on each call. +.Pp +.It Xo +.Ft "char *" +.Xc +.It Xo +.Fn clnt_sperror "CLIENT *rpch" "char *s" +.Xc +.Pp +Like +.Fn clnt_perror , +except that (like +.Fn clnt_sperrno ) +it returns a string instead of printing to standard error. +.Pp +Bugs: returns pointer to static data that is overwritten +on each call. +.Pp +.It Xo +.Ft "CLIENT *" +.Xc +.It Xo +.Fn clntraw_create "u_long prognum" "u_long versnum" +.Xc +.Pp +This routine creates a toy +.Tn RPC +client for the remote program +.Fa prognum , +version +.Fa versnum . +The transport used to pass messages to the service is +actually a buffer within the process's address space, so the +corresponding +.Tn RPC +server should live in the same address space; see +.Fn svcraw_create . +This allows simulation of +.Tn RPC +and acquisition of +.Tn RPC +overheads, such as round trip times, without any +kernel interference. +This routine returns +.Dv NULL +if it fails. +.Pp +.It Xo +.Ft "CLIENT *" +.Xc +.It Xo +.Fo clnttcp_create +.Fa "struct sockaddr_in *addr" +.Fa "u_long prognum" +.Fa "u_long versnum" +.Fa "int *sockp" +.Fa "u_int sendsz" +.Fa "u_int recvsz" +.Fc +.Xc +.Pp +This routine creates an +.Tn RPC +client for the remote program +.Fa prognum , +version +.Fa versnum ; +the client uses +.Tn TCP/IP +as a transport. +The remote program is located at Internet +address +.Fa addr . +If +.Fa addr\->sin_port +is zero, then it is set to the actual port that the remote +program is listening on (the remote +.Xr rpcbind 8 +service is consulted for this information). +The +.Fa sockp +argument +is a socket; if it is +.Dv RPC_ANYSOCK , +then this routine opens a new one and sets +.Fa sockp . +Since +.Tn TCP Ns \-based +.Tn RPC +uses buffered +.Tn I/O , +the user may specify the size of the send and receive buffers +with the +.Fa sendsz +and +.Fa recvsz +arguments; +values of zero choose suitable defaults. +This routine returns +.Dv NULL +if it fails. +.Pp +.It Xo +.Ft "CLIENT *" +.Xc +.It Xo +.Fo clntudp_create +.Fa "struct sockaddr_in *addr" +.Fa "u_long prognum" +.Fa "u_long versnum" +.Fa "struct timeval wait" +.Fa "int *sockp" +.Fc +.Xc +.Pp +This routine creates an +.Tn RPC +client for the remote program +.Fa prognum , +version +.Fa versnum ; +the client uses +.Tn UDP/IP +as a transport. +The remote program is located at Internet +address +.Fa addr . +If +.Fa addr\->sin_port +is zero, then it is set to actual port that the remote +program is listening on (the remote +.Xr rpcbind 8 +service is consulted for this information). +The +.Fa sockp +argument +is a socket; if it is +.Dv RPC_ANYSOCK , +then this routine opens a new one and sets +.Fa sockp . +The +.Tn UDP +transport resends the call message in intervals of +.Fa wait +time until a response is received or until the call times +out. +The total time for the call to time out is specified by +.Fn clnt_call . +.Pp +Warning: since +.Tn UDP Ns \-based +.Tn RPC +messages can only hold up to 8 Kbytes +of encoded data, this transport cannot be used for procedures +that take large arguments or return huge results. +.Pp +.It Xo +.Ft "CLIENT *" +.Xc +.It Xo +.Fo clntudp_bufcreate +.Fa "struct sockaddr_in *addr" +.Fa "u_long prognum" +.Fa "u_long versnum" +.Fa "struct timeval wait" +.Fa "int *sockp" +.Fa "unsigned int sendsize" +.Fa "unsigned int recosize" +.Fc +.Xc +.Pp +This routine creates an +.Tn RPC +client for the remote program +.Fa prognum , +on +.Fa versnum ; +the client uses +.Tn UDP/IP +as a transport. +The remote program is located at Internet +address +.Fa addr . +If +.Fa addr\->sin_port +is zero, then it is set to actual port that the remote +program is listening on (the remote +.Xr rpcbind 8 +service is consulted for this information). +The +.Fa sockp +argument +is a socket; if it is +.Dv RPC_ANYSOCK , +then this routine opens a new one and sets +.Fa sockp . +The +.Tn UDP +transport resends the call message in intervals of +.Fa wait +time until a response is received or until the call times +out. +The total time for the call to time out is specified by +.Fn clnt_call . +.Pp +This allows the user to specify the maximum packet size +for sending and receiving +.Tn UDP Ns \-based +.Tn RPC +messages. +.Pp +.It Xo +.Ft "CLIENT *" +.Xc +.It Xo +.Fo clntunix_create +.Fa "struct sockaddr_un *raddr" +.Fa "u_long prognum" +.Fa "u_long versnum" +.Fa "int *sockp" +.Fa "u_int sendsz" +.Fa "u_int recvsz" +.Fc +.Xc +.Pp +This routine creates an +.Tn RPC +client for the local +program +.Fa prognum , +version +.Fa versnum ; +the client uses +.Ux Ns -domain +sockets as a transport. +The local program is located at the +.Fa *raddr . +The +.Fa sockp +argument +is a socket; if it is +.Dv RPC_ANYSOCK , +then this routine opens a new one and sets +.Fa sockp . +Since +.Ux Ns -based +.Tn RPC +uses buffered +.Tn I/O , +the user may specify the size of the send and receive buffers +with the +.Fa sendsz +and +.Fa recvsz +arguments; +values of zero choose suitable defaults. +This routine returns +.Dv NULL +if it fails. +.Pp +.It Xo +.Ft int +.Xc +.It Xo +.Fn get_myaddress "struct sockaddr_in *addr" +.Xc +.Pp +Stuff the machine's +.Tn IP +address into +.Fa addr , +without consulting the library routines that deal with +.Pa /etc/hosts . +The port number is always set to +.Fn htons PMAPPORT . +Returns zero on success, non-zero on failure. +.Pp +.It Xo +.Ft "struct pmaplist *" +.Xc +.It Xo +.Fn pmap_getmaps "struct sockaddr_in *addr" +.Xc +.Pp +A user interface to the +.Xr rpcbind 8 +service, which returns a list of the current +.Tn RPC +program\-to\-port mappings +on the host located at +.Tn IP +address +.Fa addr . +This routine can return +.Dv NULL . +The command +.Dq Nm rpcinfo Fl p +uses this routine. +.Pp +.It Xo +.Ft u_short +.Xc +.It Xo +.Fo pmap_getport +.Fa "struct sockaddr_in *addr" +.Fa "u_long prognum" +.Fa "u_long versnum" +.Fa "u_long protocol" +.Fc +.Xc +.Pp +A user interface to the +.Xr rpcbind 8 +service, which returns the port number +on which waits a service that supports program number +.Fa prognum , +version +.Fa versnum , +and speaks the transport protocol associated with +.Fa protocol . +The value of +.Fa protocol +is most likely +.Dv IPPROTO_UDP +or +.Dv IPPROTO_TCP . +A return value of zero means that the mapping does not exist +or that +the +.Tn RPC +system failed to contact the remote +.Xr rpcbind 8 +service. +In the latter case, the global variable +.Va rpc_createerr +contains the +.Tn RPC +status. +.Pp +.It Xo +.Ft "enum clnt_stat" +.Xc +.It Xo +.Fo pmap_rmtcall +.Fa "struct sockaddr_in *addr" +.Fa "u_long prognum" +.Fa "u_long versnum" +.Fa "u_long procnum" +.Fa "xdrproc_t inproc" +.Fa "char *in" +.Fa "xdrproc_t outproc" +.Fa "char *out" +.Fa "struct timeval tout" +.Fa "u_long *portp" +.Fc +.Xc +.Pp +A user interface to the +.Xr rpcbind 8 +service, which instructs +.Xr rpcbind 8 +on the host at +.Tn IP +address +.Fa addr +to make an +.Tn RPC +call on your behalf to a procedure on that host. +The +.Fa portp +argument +will be modified to the program's port number if the +procedure +succeeds. +The definitions of other arguments are discussed +in +.Fn callrpc +and +.Fn clnt_call . +This procedure should be used for a +.Dq ping +and nothing +else. +See also +.Fn clnt_broadcast . +.Pp +.It Xo +.Ft bool_t +.Fn pmap_set "u_long prognum" "u_long versnum" "u_long protocol" "u_short port" +.Xc +.Pp +A user interface to the +.Xr rpcbind 8 +service, which establishes a mapping between the triple +.Pq Fa prognum , versnum , protocol +and +.Fa port +on the machine's +.Xr rpcbind 8 +service. +The value of +.Fa protocol +is most likely +.Dv IPPROTO_UDP +or +.Dv IPPROTO_TCP . +This routine returns one if it succeeds, zero otherwise. +Automatically done by +.Fn svc_register . +.Pp +.It Xo +.Ft bool_t +.Fn pmap_unset "u_long prognum" "u_long versnum" +.Xc +.Pp +A user interface to the +.Xr rpcbind 8 +service, which destroys all mapping between the triple +.Pq Fa prognum , versnum , * +and +.Fa ports +on the machine's +.Xr rpcbind 8 +service. +This routine returns one if it succeeds, zero +otherwise. +.Pp +.It Xo +.Ft bool_t +.Fo registerrpc +.Fa "u_long prognum" +.Fa "u_long versnum" +.Fa "u_long procnum" +.Fa "char *(*procname)(void)" +.Fa "xdrproc_t inproc" +.Fa "xdrproc_t outproc" +.Fc +.Xc +.Pp +Register procedure +.Fa procname +with the +.Tn RPC +service package. +If a request arrives for program +.Fa prognum , +version +.Fa versnum , +and procedure +.Fa procnum , +.Fa procname +is called with a pointer to its argument(s); +.Fa progname +should return a pointer to its static result(s); +.Fa inproc +is used to decode the arguments while +.Fa outproc +is used to encode the results. +This routine returns zero if the registration succeeded, \-1 +otherwise. +.Pp +Warning: remote procedures registered in this form +are accessed using the +.Tn UDP/IP +transport; see +.Fn svcudp_create +for restrictions. +.Pp +.It Xo +.Vt "struct rpc_createerr" rpc_createerr ; +.Xc +.Pp +A global variable whose value is set by any +.Tn RPC +client creation routine +that does not succeed. +Use the routine +.Fn clnt_pcreateerror +to print the reason why. +.Pp +.It Xo +.Ft bool_t +.Fn svc_destroy "SVCXPRT * xprt" +.Xc +.Pp +A macro that destroys the +.Tn RPC +service transport 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. +.Pp +.It Xo +.Vt fd_set svc_fdset ; +.Xc +.Pp +A global variable reflecting the +.Tn RPC +service side's +read file descriptor bit mask; it is suitable as a template argument +to the +.Xr select 2 +system call. +This is only of interest +if a service implementor does not call +.Fn svc_run , +but rather does his own asynchronous event processing. +This variable is read\-only (do not pass its address to +.Xr select 2 ! ) , +yet it may change after calls to +.Fn svc_getreqset +or any creation routines. +As well, note that if the process has descriptor limits +which are extended beyond +.Dv FD_SETSIZE , +this variable will only be usable for the first +.Dv FD_SETSIZE +descriptors. +.Pp +.It Xo +.Vt int svc_fds ; +.Xc +.Pp +Similar to +.Va svc_fdset , +but limited to 32 descriptors. +This +interface is obsoleted by +.Va svc_fdset . +.Pp +.It Xo +.Ft bool_t +.Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in" +.Xc +.Pp +A macro that frees any data allocated by the +.Tn RPC/XDR +system when it decoded the arguments to a service procedure +using +.Fn svc_getargs . +This routine returns 1 if the results were successfully +freed, +and zero otherwise. +.Pp +.It Xo +.Ft bool_t +.Fn svc_getargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in" +.Xc +.Pp +A macro that decodes the arguments of an +.Tn RPC +request +associated with the +.Tn RPC +service transport handle, +.Fa xprt . +The +.Fa in +argument +is the address where the arguments will be placed; +.Fa inproc +is the +.Tn XDR +routine used to decode the arguments. +This routine returns one if decoding succeeds, and zero +otherwise. +.Pp +.It Xo +.Ft "struct sockaddr_in *" +.Xc +.It Xo +.Fn svc_getcaller "SVCXPRT *xprt" +.Xc +.Pp +The approved way of getting the network address of the caller +of a procedure associated with the +.Tn RPC +service transport handle, +.Fa xprt . +.Pp +.It Xo +.Ft void +.Fn svc_getreqset "fd_set *rdfds" +.Xc +.Pp +This routine is only of interest if a service implementor +does not call +.Fn svc_run , +but instead implements custom asynchronous event processing. +It is called when the +.Xr select 2 +system call has determined that an +.Tn RPC +request has arrived on some +.Tn RPC +socket(s); +.Fa rdfds +is the resultant read file descriptor bit mask. +The routine returns when all sockets associated with the +value of +.Fa rdfds +have been serviced. +.Pp +.It Xo +.Ft void +.Fn svc_getreq "int rdfds" +.Xc +.Pp +Similar to +.Fn svc_getreqset , +but limited to 32 descriptors. +This interface is obsoleted by +.Fn svc_getreqset . +.Pp +.It Xo +.Ft bool_t +.Fo svc_register +.Fa "SVCXPRT *xprt" +.Fa "u_long prognum" +.Fa "u_long versnum" +.Fa "void (*dispatch)(struct svc_req *, SVCXPRT *)" +.Fa "int protocol" +.Fc +.Xc +.Pp +Associates +.Fa prognum +and +.Fa versnum +with the service dispatch procedure, +.Fn dispatch . +If +.Fa protocol +is zero, the service is not registered with the +.Xr rpcbind 8 +service. +If +.Fa protocol +is non-zero, then a mapping of the triple +.Pq Fa prognum , versnum , protocol +to +.Fa xprt\->xp_port +is established with the local +.Xr rpcbind 8 +service (generally +.Fa protocol +is zero, +.Dv IPPROTO_UDP +or +.Dv IPPROTO_TCP ) . +The procedure +.Fn dispatch +has the following form: +.Bd -ragged -offset indent +.Ft bool_t +.Fn dispatch "struct svc_req *request" "SVCXPRT *xprt" +.Ed +.Pp +The +.Fn svc_register +routine returns one if it succeeds, and zero otherwise. +.Pp +.It Xo +.Fn svc_run +.Xc +.Pp +This routine never returns. +It waits for +.Tn RPC +requests to arrive, and calls the appropriate service +procedure using +.Fn svc_getreq +when one arrives. +This procedure is usually waiting for a +.Xr select 2 +system call to return. +.Pp +.It Xo +.Ft bool_t +.Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "char *out" +.Xc +.Pp +Called by an +.Tn RPC +service's dispatch routine to send the results of a +remote procedure call. +The +.Fa xprt +argument +is the request's associated transport handle; +.Fa outproc +is the +.Tn XDR +routine which is used to encode the results; and +.Fa out +is the address of the results. +This routine returns one if it succeeds, zero otherwise. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn svc_unregister "u_long prognum" "u_long versnum" +.Xc +.Pp +Remove all mapping of the double +.Pq Fa prognum , versnum +to dispatch routines, and of the triple +.Pq Fa prognum , versnum , * +to port number. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why" +.Xc +.Pp +Called by a service dispatch routine that refuses to perform +a remote procedure call due to an authentication error. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn svcerr_decode "SVCXPRT *xprt" +.Xc +.Pp +Called by a service dispatch routine that cannot successfully +decode its arguments. +See also +.Fn svc_getargs . +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn svcerr_noproc "SVCXPRT *xprt" +.Xc +.Pp +Called by a service dispatch routine that does not implement +the procedure number that the caller requests. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn svcerr_noprog "SVCXPRT *xprt" +.Xc +.Pp +Called when the desired program is not registered with the +.Tn RPC +package. +Service implementors usually do not need this routine. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn svcerr_progvers "SVCXPRT *xprt" "u_long low_vers" "u_long high_vers" +.Xc +.Pp +Called when the desired version of a program is not registered +with the +.Tn RPC +package. +Service implementors usually do not need this routine. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn svcerr_systemerr "SVCXPRT *xprt" +.Xc +.Pp +Called by a service dispatch routine when it detects a system +error +not covered by any particular protocol. +For example, if a service can no longer allocate storage, +it may call this routine. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn svcerr_weakauth "SVCXPRT *xprt" +.Xc +.Pp +Called by a service dispatch routine that refuses to perform +a remote procedure call due to insufficient +authentication arguments. +The routine calls +.Fn svcerr_auth xprt AUTH_TOOWEAK . +.Pp +.It Xo +.Ft "SVCXPRT *" +.Xc +.It Xo +.Fn svcraw_create void +.Xc +.Pp +This routine creates a toy +.Tn RPC +service transport, to which it returns a pointer. +The transport +is really a buffer within the process's address space, +so the corresponding +.Tn RPC +client should live in the same +address space; +see +.Fn clntraw_create . +This routine allows simulation of +.Tn RPC +and acquisition of +.Tn RPC +overheads (such as round trip times), without any kernel +interference. +This routine returns +.Dv NULL +if it fails. +.Pp +.It Xo +.Ft "SVCXPRT *" +.Xc +.It Xo +.Fn svctcp_create "int sock" "u_int send_buf_size" "u_int recv_buf_size" +.Xc +.Pp +This routine creates a +.Tn TCP/IP Ns \-based +.Tn RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.Fa sock , +which may be +.Dv RPC_ANYSOCK , +in which case a new socket is created. +If the socket is not bound to a local +.Tn TCP +port, then this routine binds it to an arbitrary port. +Upon completion, +.Fa xprt\->xp_fd +is the transport's socket descriptor, and +.Fa xprt\->xp_port +is the transport's port number. +This routine returns +.Dv NULL +if it fails. +Since +.Tn TCP Ns \-based +.Tn RPC +uses buffered +.Tn I/O , +users may specify the size of buffers; values of zero +choose suitable defaults. +.Pp +.It Xo +.Ft "SVCXPRT *" +.Xc +.It Xo +.Fn svcunix_create "int sock" "u_int send_buf_size" "u_int recv_buf_size" "char *path" +.Xc +.Pp +This routine creates a +.Ux Ns -based +.Tn RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.Fa sock , +which may be +.Dv RPC_ANYSOCK , +in which case a new socket is created. +The +.Fa *path +argument +is a variable-length file system pathname of +at most 104 characters. +This file is +.Em not +removed when the socket is closed. +The +.Xr unlink 2 +system call must be used to remove the file. +Upon completion, +.Fa xprt\->xp_fd +is the transport's socket descriptor. +This routine returns +.Dv NULL +if it fails. +Since +.Ux Ns -based +.Tn RPC +uses buffered +.Tn I/O , +users may specify the size of buffers; values of zero +choose suitable defaults. +.Pp +.It Xo +.Ft "SVCXPRT *" +.Xc +.It Xo +.Fn svcunixfd_create "int fd" "u_int sendsize" "u_int recvsize" +.Xc +.Pp +Create a service on top of any open descriptor. +The +.Fa sendsize +and +.Fa recvsize +arguments +indicate sizes for the send and receive buffers. +If they are +zero, a reasonable default is chosen. +.Pp +.It Xo +.Ft "SVCXPRT *" +.Xc +.It Xo +.Fn svcfd_create "int fd" "u_int sendsize" "u_int recvsize" +.Xc +.Pp +Create a service on top of any open descriptor. +Typically, +this +descriptor is a connected socket for a stream protocol such +as +.Tn TCP . +The +.Fa sendsize +and +.Fa recvsize +arguments +indicate sizes for the send and receive buffers. +If they are +zero, a reasonable default is chosen. +.Pp +.It Xo +.Ft "SVCXPRT *" +.Xc +.It Xo +.Fn svcudp_bufcreate "int sock" "u_int sendsize" "u_int recvsize" +.Xc +.Pp +This routine creates a +.Tn UDP/IP Ns \-based +.Tn RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.Fa sock , +which may be +.Dv RPC_ANYSOCK , +in which case a new socket is created. +If the socket is not bound to a local +.Tn UDP +port, then this routine binds it to an arbitrary port. +Upon +completion, +.Fa xprt\->xp_fd +is the transport's socket descriptor, and +.Fa xprt\->xp_port +is the transport's port number. +This routine returns +.Dv NULL +if it fails. +.Pp +This allows the user to specify the maximum packet size for sending and +receiving +.Tn UDP Ns \-based +.Tn RPC +messages. +.Pp +.It Xo +.Ft bool_t +.Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar" +.Xc +.Pp +Used for encoding +.Tn RPC +reply messages. +This routine is useful for users who +wish to generate +.Tn RPC Ns \-style +messages without using the +.Tn RPC +package. +.Pp +.It Xo +.Ft bool_t +.Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp" +.Xc +.Pp +Used for describing +.Ux +credentials. +This routine is useful for users +who wish to generate these credentials without using the +.Tn RPC +authentication package. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Ft bool_t +.Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr" +.Xc +.Pp +Used for describing +.Tn RPC +call header messages. +This routine is useful for users who wish to generate +.Tn RPC Ns \-style +messages without using the +.Tn RPC +package. +.Pp +.It Xo +.Ft bool_t +.Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg" +.Xc +.Pp +Used for describing +.Tn RPC +call messages. +This routine is useful for users who wish to generate +.Tn RPC Ns \-style +messages without using the +.Tn RPC +package. +.Pp +.It Xo +.Ft bool_t +.Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap" +.Xc +.Pp +Used for describing +.Tn RPC +authentication information messages. +This routine is useful for users who wish to generate +.Tn RPC Ns \-style +messages without using the +.Tn RPC +package. +.Pp +.It Xo +.Vt struct pmap ; +.Xc +.It Xo +.Ft bool_t +.Fn xdr_pmap "XDR *xdrs" "struct pmap *regs" +.Xc +.Pp +Used for describing arguments to various +.Xr rpcbind 8 +procedures, externally. +This routine is useful for users who wish to generate +these arguments without using the +.Fn pmap_* +interface. +.Pp +.It Xo +.Ft bool_t +.Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp" +.Xc +.Pp +Used for describing a list of port mappings, externally. +This routine is useful for users who wish to generate +these arguments without using the +.Fn pmap_* +interface. +.Pp +.It Xo +.Ft bool_t +.Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr" +.Xc +.Pp +Used for describing +.Tn RPC +reply messages. +This routine is useful for users who wish to generate +.Tn RPC Ns \-style +messages without using the +.Tn RPC +package. +.Pp +.It Xo +.Ft bool_t +.Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg" +.Xc +.Pp +Used for describing +.Tn RPC +reply messages. +This routine is useful for users who wish to generate +.Tn RPC +style messages without using the +.Tn RPC +package. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn xprt_register "SVCXPRT *xprt" +.Xc +.Pp +After +.Tn RPC +service transport handles are created, +they should register themselves with the +.Tn RPC +service package. +This routine modifies the global variable +.Va svc_fds . +Service implementors usually do not need this routine. +.Pp +.It Xo +.Ft void +.Xc +.It Xo +.Fn xprt_unregister "SVCXPRT *xprt" +.Xc +.Pp +Before an +.Tn RPC +service transport handle is destroyed, +it should unregister itself with the +.Tn RPC +service package. +This routine modifies the global variable +.Va svc_fds . +Service implementors usually do not need this routine. +.El +.Sh AVAILABILITY +These functions are part of libtirpc. +.Sh SEE ALSO +.Xr rpc_secure 3 , +.Xr xdr 3 +.Rs +.%T "Remote Procedure Calls: Protocol Specification" +.Re +.Rs +.%T "Remote Procedure Call Programming Guide" +.Re +.Rs +.%T "rpcgen Programming Guide" +.Re +.Rs +.%T "RPC: Remote Procedure Call Protocol Specification" +.%O RFC1050 +.%Q "Sun Microsystems, Inc., USC-ISI" +.Re |