libc: Comment out documentation of svc_control() which we don't have.
[dragonfly.git] / lib / libc / rpc / rpc_svc_create.3
1 .\" @(#)rpc_svc_create.3n 1.26 93/08/26 SMI; from SVr4
2 .\" Copyright 1989 AT&T
3 .\" @(#)rpc_svc_create 1.3 89/06/28 SMI;
4 .\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
5 .\" $FreeBSD: src/lib/libc/rpc/rpc_svc_create.3,v 1.7 2003/09/08 19:57:15 ru Exp $
6 .Dd May 3, 1993
7 .Dt RPC_SVC_CREATE 3
8 .Os
9 .Sh NAME
10 .Nm rpc_svc_create ,
11 .\".Nm svc_control ,
12 .Nm svc_create ,
13 .Nm svc_destroy ,
14 .Nm svc_dg_create ,
15 .Nm svc_fd_create ,
16 .Nm svc_raw_create ,
17 .Nm svc_tli_create ,
18 .Nm svc_tp_create ,
19 .Nm svc_vc_create
20 .Nd library routines for the creation of server handles
21 .Sh LIBRARY
22 .Lb libc
23 .Sh SYNOPSIS
24 .In rpc/rpc.h
25 .\".Ft bool_t
26 .\".Fn svc_control "SVCXPRT *svc" "const u_int req" "void *info"
27 .Ft int
28 .Fn svc_create "void (*dispatch)(struct svc_req *, SVCXPRT *)" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype"
29 .Ft SVCXPRT *
30 .Fn svc_dg_create "const int fildes" "const u_int sendsz" "const u_int recvsz"
31 .Ft void
32 .Fn svc_destroy "SVCXPRT *xprt"
33 .Ft "SVCXPRT *"
34 .Fn svc_fd_create "const int fildes" "const u_int sendsz" "const u_int recvsz"
35 .Ft "SVCXPRT *"
36 .Fn svc_raw_create "void"
37 .Ft "SVCXPRT *"
38 .Fn svc_tli_create "const int fildes" "const struct netconfig *netconf" "const struct t_bind *bindaddr" "const u_int sendsz" "const u_int recvsz"
39 .Ft "SVCXPRT *"
40 .Fn svc_tp_create "void (*dispatch)(struct svc_req *, SVCXPRT *)" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf"
41 .Ft "SVCXPRT *"
42 .Fn svc_vc_create "const int fildes" "const u_int sendsz" "const u_int recvsz"
43 .Sh DESCRIPTION
44 These routines are part of the RPC
45 library which allows C language programs to make procedure
46 calls on servers across the network.
47 These routines deal with the creation of service handles.
48 Once the handle is created, the server can be invoked by calling
49 .Fn svc_run .
50 .Sh Routines
51 See
52 .Xr rpc 3
53 for the definition of the
54 .Vt SVCXPRT
55 data structure.
56 .Bl -tag -width XXXXX
57 .\".It Fn svc_control
58 .\"A function to change or retrieve various information
59 .\"about a service object.
60 .\"The
61 .\".Fa req
62 .\"argument
63 .\"indicates the type of operation and
64 .\".Fa info
65 .\"is a pointer to the information.
66 .\"The supported values of
67 .\".Fa req ,
68 .\"their argument types, and what they do are:
69 .\".Bl -tag -width SVCGET_XID
70 .\".It Dv SVCGET_VERSQUIET
71 .\"If a request is received for a program number
72 .\"served by this server but the version number
73 .\"is outside the range registered with the server,
74 .\"an
75 .\".Dv RPC_PROGVERSMISMATCH
76 .\"error will normally
77 .\"be returned.
78 .\"The
79 .\".Fa info
80 .\"argument
81 .\"should be a pointer to an
82 .\"integer.
83 .\"Upon successful completion of the
84 .\".Dv SVCGET_VERSQUIET
85 .\"request,
86 .\".Fa *info
87 .\"contains an
88 .\"integer which describes the server's current
89 .\"behavior: 0 indicates normal server behavior
90 .\"(that is, an
91 .\".Dv RPC_PROGVERSMISMATCH
92 .\"error
93 .\"will be returned); 1 indicates that the out of
94 .\"range request will be silently ignored.
95 .\".It Dv SVCSET_VERSQUIET
96 .\"If a request is received for a program number
97 .\"served by this server but the version number
98 .\"is outside the range registered with the server,
99 .\"an
100 .\".Dv RPC_PROGVERSMISMATCH
101 .\"error will normally
102 .\"be returned.
103 .\"It is sometimes desirable to
104 .\"change this behavior.
105 .\"The
106 .\".Fa info
107 .\"argument
108 .\"should be a
109 .\"pointer to an integer which is either 0
110 .\"(indicating normal server behavior - an
111 .\".Dv RPC_PROGVERSMISMATCH
112 .\"error will be returned),
113 .\"or 1 (indicating that the out of range request
114 .\"should be silently ignored).
115 .\".El
116 .It Fn svc_create
117 The
118 .Fn svc_create
119 function
120 creates server handles for all the transports
121 belonging to the class
122 .Fa nettype .
123 The
124 .Fa nettype
125 argument
126 defines a class of transports which can be used
127 for a particular application.
128 The transports are tried in left to right order in
129 .Ev NETPATH
130 variable or in top to bottom order in the netconfig database.
131 If
132 .Fa nettype
133 is
134 .Dv NULL ,
135 it defaults to
136 .Qq netpath .
137 .Pp
138 The
139 .Fn svc_create
140 function
141 registers itself with the rpcbind
142 service (see
143 .Xr rpcbind 8 ) .
144 The
145 .Fa dispatch
146 function
147 is called when there is a remote procedure call for the given
148 .Fa prognum
149 and
150 .Fa versnum ;
151 this requires calling
152 .Fn svc_run
153 (see
154 .Fn svc_run
155 in
156 .Xr rpc_svc_reg 3 ) .
157 If
158 .Fn svc_create
159 succeeds, it returns the number of server
160 handles it created,
161 otherwise it returns 0 and an error message is logged.
162 .It Fn svc_destroy
163 A function macro that destroys the RPC
164 service handle
165 .Fa xprt .
166 Destruction usually involves deallocation
167 of private data structures,
168 including
169 .Fa xprt
170 itself.
171 Use of
172 .Fa xprt
173 is undefined after calling this routine.
174 .It Fn svc_dg_create
175 This routine creates a connectionless RPC
176 service handle, and returns a pointer to it.
177 This routine returns
178 .Dv NULL
179 if it fails, and an error message is logged.
180 The
181 .Fa sendsz
182 and
183 .Fa recvsz
184 arguments
185 are arguments used to specify the size of the buffers.
186 If they are 0, suitable defaults are chosen.
187 The file descriptor
188 .Fa fildes
189 should be open and bound.
190 The server is not registered with
191 .Xr rpcbind 8 .
192 .Pp
193 Warning:
194 since connectionless-based RPC
195 messages can only hold limited amount of encoded data,
196 this transport cannot be used for procedures
197 that take large arguments or return huge results.
198 .It Fn svc_fd_create
199 This routine creates a service on top of an open and bound file descriptor,
200 and returns the handle to it.
201 Typically, this descriptor is a connected file descriptor for a
202 connection-oriented transport.
203 The
204 .Fa sendsz
205 and
206 .Fa recvsz
207 arguments
208 indicate sizes for the send and receive buffers.
209 If they are 0, reasonable defaults are chosen.
210 This routine returns
211 .Dv NULL
212 if it fails, and an error message is logged.
213 .It Fn svc_raw_create
214 This routine creates an RPC
215 service handle and returns a pointer to it.
216 The transport is really a buffer within the process's
217 address space, so the corresponding RPC
218 client should live in the same address space;
219 (see
220 .Fn clnt_raw_create
221 in
222 .Xr rpc_clnt_create 3 ) .
223 This routine allows simulation of RPC and acquisition of
224 RPC overheads (such as round trip times),
225 without any kernel and networking interference.
226 This routine returns
227 .Dv NULL
228 if it fails, and an error message is logged.
229 .Pp
230 Note:
231 .Fn svc_run
232 should not be called when the raw interface is being used.
233 .It Fn svc_tli_create
234 This routine creates an RPC
235 server handle, and returns a pointer to it.
236 The
237 .Fa fildes
238 argument
239 is the file descriptor on which the service is listening.
240 If
241 .Fa fildes
242 is
243 .Dv RPC_ANYFD ,
244 it opens a file descriptor on the transport specified by
245 .Fa netconf .
246 If the file descriptor is unbound and
247 .Fa bindaddr
248 is not
249 .Dv NULL ,
250 .Fa fildes
251 is bound to the address specified by
252 .Fa bindaddr ,
253 otherwise
254 .Fa fildes
255 is bound to a default address chosen by the transport.
256 .Pp
257 Note: the
258 .Vt t_bind
259 structure comes from the TLI/XTI SysV interface, which
260 .Nx
261 does not use.
262 The structure is defined in
263 .In rpc/types.h
264 for compatibility as:
265 .Bd -literal
266 struct t_bind {
267     struct netbuf addr; /* network address, see rpc(3) */
268     unsigned int  qlen; /* queue length (for listen(2)) */
269 };
270 .Ed
271 .Pp
272 In the case where the default address is chosen,
273 the number of outstanding connect requests is set to 8
274 for connection-oriented transports.
275 The user may specify the size of the send and receive buffers
276 with the arguments
277 .Fa sendsz
278 and
279 .Fa recvsz ;
280 values of 0 choose suitable defaults.
281 This routine returns
282 .Dv NULL
283 if it fails,
284 and an error message is logged.
285 The server is not registered with the
286 .Xr rpcbind 8
287 service.
288 .It Fn svc_tp_create
289 The
290 .Fn svc_tp_create
291 function
292 creates a server handle for the network
293 specified by
294 .Fa netconf ,
295 and registers itself with the rpcbind service.
296 The
297 .Fa dispatch
298 function
299 is called when there is a remote procedure call
300 for the given
301 .Fa prognum
302 and
303 .Fa versnum ;
304 this requires calling
305 .Fn svc_run .
306 The
307 .Fn svc_tp_create
308 function
309 returns the service handle if it succeeds,
310 otherwise a
311 .Dv NULL
312 is returned and an error message is logged.
313 .It Fn svc_vc_create
314 This routine creates a connection-oriented RPC
315 service and returns a pointer to it.
316 This routine returns
317 .Dv NULL
318 if it fails, and an error message is logged.
319 The users may specify the size of the send and receive buffers
320 with the arguments
321 .Fa sendsz
322 and
323 .Fa recvsz ;
324 values of 0 choose suitable defaults.
325 The file descriptor
326 .Fa fildes
327 should be open and bound.
328 The server is not registered with the
329 .Xr rpcbind 8
330 service.
331 .El
332 .Sh SEE ALSO
333 .Xr rpc 3 ,
334 .Xr rpc_svc_calls 3 ,
335 .Xr rpc_svc_err 3 ,
336 .Xr rpc_svc_reg 3 ,
337 .Xr rpcbind 8