1.\" @(#)rpc_svc_calls.3n 1.28 93/05/10 SMI; from SVr4 2.\" Copyright 1989 AT&T 3.\" @(#)rpc_svc_calls 1.5 89/07/25 SMI; 4.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. 5.\" $NetBSD: rpc_svc_calls.3,v 1.4 2002/02/07 07:00:23 ross Exp $ 6.Dd May 3, 1993 7.Dt RPC_SVC_CALLS 3 8.Os 9.Sh NAME 10.Nm svc_dg_enablecache , 11.Nm svc_exit , 12.Nm svc_fdset , 13.Nm svc_freeargs , 14.Nm svc_getargs , 15.Nm svc_getreq_common , 16.Nm svc_getreq_poll , 17.Nm svc_getreqset , 18.Nm svc_getrpccaller , 19.Nm svc_pollset , 20.Nm svc_run , 21.Nm svc_sendreply 22.Nd library routines for RPC servers 23.Sh LIBRARY 24.Lb libc 25.Sh SYNOPSIS 26.Fd #include \*[Lt]rpc/rpc.h\*[Gt] 27.Ft int 28.Fn svc_dg_enablecache "SVCXPRT *xprt" "const unsigned cache_size" 29.Ft void 30.Fn svc_exit "void" 31.Ft bool_t 32.Fn svc_freeargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in" 33.Ft bool_t 34.Fn svc_getargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in" 35.Ft void 36.Fn svc_getreq_common "const int fd" 37.Ft void 38.Fn svc_getreq_poll "struct pollfd *pfdp" "const int pollretval" 39.Ft void 40.Fn svc_getreqset "fd_set * rdfds" 41.Ft "struct netbuf *" 42.Fn svc_getrpccaller "const SVCXPRT *xprt" 43.Ft "struct sockcred *" 44.Fn __svc_getcallercreds "const SVCXPRT *xprt" 45.Vt struct pollfd svc_pollset[FD_SETSIZE]; 46.Ft void 47.Fn svc_run "void" 48.Ft bool_t 49.Fn svc_sendreply "const SVCXPRT *xprt" "const xdrproc_t outproc" "const caddr_t *out" 50.Sh DESCRIPTION 51These routines are part of the 52RPC 53library which allows C language programs to make procedure 54calls on other machines across the network. 55.Pp 56These routines are associated with the server side of the 57RPC mechanism. 58Some of them are called by the server side dispatch function, 59while others 60(such as 61.Fn svc_run ) 62are called when the server is initiated. 63.\" .Pp 64.\" In the current implementation, the service transport handle, 65.\" .Dv SVCXPRT , 66.\" contains a single data area for decoding arguments and encoding results. 67.\" Therefore, this structure cannot be freely shared between threads that call 68.\" functions that do this. Routines on this page that are affected by this 69.\" restriction are marked as unsafe for MT applications. 70.Sh ROUTINES 71See 72.Xr rpc 3 73for the definition of the 74.Dv SVCXPRT 75data structure. 76.Pp 77.Bl -tag -width __svc_getcallercreds() 78.It Fn svc_dg_enablecache 79This function allocates a duplicate request cache for the 80service endpoint 81.Fa xprt , 82large enough to hold 83.Fa cache_size 84entries. 85Once enabled, there is no way to disable caching. 86This routine returns 0 if space necessary for a cache of the given size 87was successfully allocated, and 1 otherwise. 88.It Fn svc_exit 89This function when called by any of the RPC server procedure or 90otherwise, causes 91.Fn svc_run 92to return. 93.Pp 94As currently implemented, 95.Fn svc_exit 96zeroes the 97.Dv svc_fdset 98global variable. If RPC server activity is to be resumed, 99services must be reregistered with the RPC library 100either through one of the 101.Fn rpc_svc_create 102functions, or using 103.Fn xprt_register . 104.Fn svc_exit 105has global scope and ends all RPC server activity. 106.Ft "fd_set svc_fdset" 107A global variable reflecting the 108RPC server's read file descriptor bit mask; it is suitable as a parameter 109to the 110.Xr select 2 111system call. 112This is only of interest 113if service implementors do not call 114.Fn svc_run , 115but rather do their own asynchronous event processing. 116This variable is read-only (do not pass its address to 117.Xr select 2 ! ) , 118yet it may change after calls to 119.Fn svc_getreqset 120or any creation routines. 121.Pp 122.It Fn svc_freeargs 123A function macro that frees any data allocated by the 124RPC/XDR system when it decoded the arguments to a service procedure 125using 126.Fn svc_getargs . 127This routine returns 128.Dv TRUE 129if the results were successfully 130freed, and 131.Dv FALSE 132otherwise. 133.Pp 134.It Fn svc_getargs 135A function macro that decodes the arguments of an 136RPC request associated with the RPC 137service transport handle 138.Fa xprt . 139The parameter 140.Fa in 141is the address where the arguments will be placed; 142.Fa inproc 143is the XDR 144routine used to decode the arguments. 145This routine returns 146.Dv TRUE 147if decoding succeeds, and 148.Dv FALSE 149otherwise. 150.It Fn svc_getreq_common 151This routine is called to handle a request on the given 152file descriptor. 153.Pp 154.It Fn svc_getreq_poll 155This routine is only of interest if a service implementor 156does not call 157.Fn svc_run , 158but instead implements custom asynchronous event processing. 159It is called when 160.Xr poll 2 161has determined that an RPC request has arrived on some RPC 162file descriptors; 163.Fn pollretval 164is the return value from 165.Xr poll 2 166and 167.Fa pfdp 168is the array of 169.Fa pollfd 170structures on which the 171.Xr poll 2 172was done. 173It is assumed to be an array large enough to 174contain the maximal number of descriptors allowed. 175.Pp 176.Fn svc_getreqset 177This routine is only of interest if a service implementor 178does not call 179.Fn svc_run , 180but instead implements custom asynchronous event processing. 181It is called when 182.Xr poll 2 183has determined that an RPC 184request has arrived on some RPC file descriptors; 185.Fa rdfds 186is the resultant read file descriptor bit mask. 187The routine returns when all file descriptors 188associated with the value of 189.Fa rdfds 190have been serviced. 191.Pp 192.It Fn svc_getrpccaller 193The approved way of getting the network address of the caller 194of a procedure associated with the 195RPC service transport handle 196.Fa xprt . 197.Pp 198.It Fn __svc_getcallercreds 199.Bf Warning: this macro is specific to 200.Nx 201and thus not portable. 202This macro returns a pointer to a sockcred structure, defined in 203.Fd \*[Lt]sys/socket.h\*[Gt] , 204identifying the calling client. This only works if the client is 205calling the server over an 206.Dv AF_LOCAL 207socket. 208.It Fa struct pollfd svc_pollset[FD_SETSIZE]; 209.Va svc_pollset 210is an array of 211.Vt pollfd 212structures derived from 213.Va svc_fdset[] . 214It is suitable as a parameter to the 215.Xr poll 2 216system call. 217The derivation of 218.Va svc_pollset 219from 220.Va svc_fdset 221is made in the current implementation in 222.Fn svc_run . 223Service implementors who do not call 224.Fn svc_run 225and who wish to use this array must perform this derivation themselves. 226.Pp 227.It Fn svc_run 228.IP 229This routine never returns. 230It waits for RPC 231requests to arrive, and calls the appropriate service 232procedure using 233.Fn svc_getreq_poll 234when one arrives. 235This procedure is usually waiting for the 236.Xr poll 2 237system call to return. 238.Pp 239.It Fn svc_sendreply 240Called by an RPC service's dispatch routine to send the results of a 241remote procedure call. The parameter 242.Fa xprt 243is the request's associated transport handle; 244.Fa outproc 245is the XDR 246routine which is used to encode the results; and 247.Fa out 248is the address of the results. 249This routine returns 250.Dv TRUE 251if it succeeds, 252.Dv FALSE 253otherwise. 254.El 255.Sh SEE ALSO 256.Xr poll 2 , 257.Xr rpc 3 , 258.Xr rpc_svc_create 3 , 259.Xr rpc_svc_err 3 , 260.Xr rpc_svc_reg 3 261