Commit | Line | Data |
---|---|---|
ce0e08e2 PA |
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 $ | |
a546d85a | 7 | .Dd January 31, 2009 |
ce0e08e2 PA |
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" | |
ce0e08e2 PA |
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. | |
a546d85a | 76 | .Bl -tag -width ".Fn svc_dg_enablecache" |
ce0e08e2 PA |
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 . | |
ce0e08e2 PA |
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 |