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