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" "void *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 . 106The 107.Fn svc_exit 108function 109has global scope and ends all RPC server activity. 110.It Xo 111.Vt fd_set Va svc_fdset 112.Xc 113A global variable reflecting the 114RPC server's read file descriptor bit mask; it is suitable as an argument 115to the 116.Xr select 2 117system call. 118This is only of interest 119if service implementors do not call 120.Fn svc_run , 121but rather do their own asynchronous event processing. 122This variable is read-only (do not pass its address to 123.Xr select 2 ! ) , 124yet it may change after calls to 125.Fn svc_getreqset 126or any creation routines. 127.It Fn svc_freeargs 128A function macro that frees any data allocated by the 129RPC/XDR system when it decoded the arguments to a service procedure 130using 131.Fn svc_getargs . 132This routine returns 133.Dv TRUE 134if the results were successfully 135freed, and 136.Dv FALSE 137otherwise. 138.It Fn svc_getargs 139A function macro that decodes the arguments of an 140RPC request associated with the RPC 141service transport handle 142.Fa xprt . 143The 144.Fa in 145argument 146is the address where the arguments will be placed; 147.Fa inproc 148is the XDR 149routine used to decode the arguments. 150This routine returns 151.Dv TRUE 152if decoding succeeds, and 153.Dv FALSE 154otherwise. 155.It Fn svc_getreq_common 156This routine is called to handle a request on the given 157file descriptor. 158.It Fn svc_getreq_poll 159This routine is only of interest if a service implementor 160does not call 161.Fn svc_run , 162but instead implements custom asynchronous event processing. 163It is called when 164.Xr poll 2 165has determined that an RPC request has arrived on some RPC 166file descriptors; 167.Fa pollretval 168is the return value from 169.Xr poll 2 170and 171.Fa pfdp 172is the array of 173.Vt pollfd 174structures on which the 175.Xr poll 2 176was done. 177It is assumed to be an array large enough to 178contain the maximal number of descriptors allowed. 179.It Fn svc_getreqset 180This routine is only of interest if a service implementor 181does not call 182.Fn svc_run , 183but instead implements custom asynchronous event processing. 184It is called when 185.Xr poll 2 186has determined that an RPC 187request has arrived on some RPC file descriptors; 188.Fa rdfds 189is the resultant read file descriptor bit mask. 190The routine returns when all file descriptors 191associated with the value of 192.Fa rdfds 193have been serviced. 194.It Fn svc_getrpccaller 195The approved way of getting the network address of the caller 196of a procedure associated with the 197RPC service transport handle 198.Fa xprt . 199.It Fn __svc_getcallercreds 200.Em Warning : 201this macro is specific to 202.Fx 203and thus not portable. 204This macro returns a pointer to a 205.Vt cmsgcred 206structure, defined in 207.In sys/socket.h , 208identifying the calling client. 209This only works if the client is 210calling the server over an 211.Dv AF_LOCAL 212socket. 213.It Xo 214.Vt struct pollfd Va svc_pollset[FD_SETSIZE] ; 215.Xc 216.Va svc_pollset 217is an array of 218.Vt pollfd 219structures derived from 220.Va svc_fdset[] . 221It is suitable as an argument to the 222.Xr poll 2 223system call. 224The derivation of 225.Va svc_pollset 226from 227.Va svc_fdset 228is made in the current implementation in 229.Fn svc_run . 230Service implementors who do not call 231.Fn svc_run 232and who wish to use this array must perform this derivation themselves. 233.It Fn svc_run 234This routine never returns. 235It waits for RPC 236requests to arrive, and calls the appropriate service 237procedure using 238.Fn svc_getreq_poll 239when one arrives. 240This procedure is usually waiting for the 241.Xr poll 2 242system call to return. 243.It Fn svc_sendreply 244Called by an RPC service's dispatch routine to send the results of a 245remote procedure call. 246The 247.Fa xprt 248argument 249is the request's associated transport handle; 250.Fa outproc 251is the XDR 252routine which is used to encode the results; and 253.Fa out 254is the address of the results. 255This routine returns 256.Dv TRUE 257if it succeeds, 258.Dv FALSE 259otherwise. 260.El 261.Sh SEE ALSO 262.Xr poll 2 , 263.Xr select 2 , 264.Xr rpc 3 , 265.Xr rpc_svc_create 3 , 266.Xr rpc_svc_err 3 , 267.Xr rpc_svc_reg 3 268