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