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