0a92a3690eec3e4e60bcd5afd4f873b00ae18aca
[dragonfly.git] / lib / libc / rpc / rpc.3
1 .\" @(#)rpc.3n 1.31 93/08/31 SMI; from SVr4
2 .\" Copyright 1989 AT&T
3 .\" $NetBSD: rpc.3,v 1.10 2000/06/02 23:11:12 fvdl Exp $
4 .\" $FreeBSD: src/lib/libc/rpc/rpc.3,v 1.23 2004/07/03 22:30:09 ru Exp $
5 .\" $DragonFly: src/lib/libc/rpc/rpc.3,v 1.8 2008/05/01 22:06:06 swildner Exp $
6 .\"
7 .Dd May 7, 1993
8 .Dt RPC 3
9 .Os
10 .Sh NAME
11 .Nm rpc
12 .Nd library routines for remote procedure calls
13 .Sh LIBRARY
14 .Lb libc
15 .Sh SYNOPSIS
16 .In rpc/rpc.h
17 .In netconfig.h
18 .Sh DESCRIPTION
19 These
20 routines allow C language programs to make procedure
21 calls on other machines across a network.
22 First, the client sends a request to the server.
23 On receipt of the request, the server calls a dispatch routine
24 to perform the requested service, and then sends back a reply.
25 .Pp
26 All
27 RPC routines require the header
28 .In rpc/rpc.h .
29 Routines that take a
30 .Vt "struct netconfig"
31 also require that
32 .In netconfig.h
33 be included.
34 .Sh Nettype
35 Some of the high-level
36 RPC interface routines take a
37 .Fa nettype
38 string as one of the arguments
39 (for example,
40 .Fn clnt_create ,
41 .Fn svc_create ,
42 .Fn rpc_reg ,
43 .Fn rpc_call ) .
44 This string defines a class of transports which can be used
45 for a particular application.
46 .Pp
47 The
48 .Fa nettype
49 argument
50 can be one of the following:
51 .Bl -tag -width datagram_v
52 .It netpath
53 Choose from the transports which have been
54 indicated by their token names in the
55 .Ev NETPATH
56 environment variable.
57 .Ev NETPATH
58 is unset or
59 .Dv NULL ,
60 it defaults to
61 .Qq visible .
62 .Qq netpath
63 is the default
64 .Fa nettype .
65 .It visible
66 Choose the transports which have the visible flag (v)
67 set in the
68 .Pa /etc/netconfig
69 file.
70 .It circuit_v
71 This is same as
72 .Qq visible
73 except that it chooses only the connection oriented transports
74 (semantics
75 .Qq tpi_cots
76 or
77 .Qq tpi_cots_ord )
78 from the entries in the
79 .Pa /etc/netconfig
80 file.
81 .It datagram_v
82 This is same as
83 .Qq visible
84 except that it chooses only the connectionless datagram transports
85 (semantics
86 .Qq tpi_clts )
87 from the entries in the
88 .Pa /etc/netconfig
89 file.
90 .It circuit_n
91 This is same as
92 .Qq netpath
93 except that it chooses only the connection oriented datagram transports
94 (semantics
95 .Qq tpi_cots
96 or
97 .Qq tpi_cots_ord ) .
98 .It datagram_n
99 This is same as
100 .Qq netpath
101 except that it chooses only the connectionless datagram transports
102 (semantics
103 .Qq tpi_clts ) .
104 .It udp
105 This refers to Internet UDP, both version 4 and 6.
106 .It tcp
107 This refers to Internet TCP, both version 4 and 6.
108 .El
109 .Pp
110 If
111 .Fa nettype
112 is
113 .Dv NULL ,
114 it defaults to
115 .Qq netpath .
116 The transports are tried in left to right order in the
117 .Ev NETPATH
118 variable or in top to down order in the
119 .Pa /etc/netconfig
120 file.
121 .Sh Derived Types
122 The derived types used in the RPC interfaces are defined as follows:
123 .Bd -literal
124         typedef u_int32_t rpcprog_t;
125         typedef u_int32_t rpcvers_t;
126         typedef u_int32_t rpcproc_t;
127         typedef u_int32_t rpcprot_t;
128         typedef u_int32_t rpcport_t;
129         typedef   int32_t rpc_inline_t;
130 .Ed
131 .Sh "Data Structures"
132 Some of the data structures used by the
133 RPC package are shown below.
134 .Sh "The AUTH Structure"
135 .Bd -literal
136 /*
137  * Authentication info. Opaque to client.
138  */
139 struct opaque_auth {
140     enum_t    oa_flavor;    /* flavor of auth */
141     caddr_t    oa_base;    /* address of more auth stuff */
142     u_int    oa_length;    /* not to exceed MAX_AUTH_BYTES */
143 };
144
145 /*
146  * Auth handle, interface to client side authenticators.
147  */
148 typedef struct {
149     struct    opaque_auth    ah_cred;
150     struct    opaque_auth    ah_verf;
151     struct auth_ops {
152         void    (*ah_nextverf)(\|);
153         int    (*ah_marshal)(\|);    /* nextverf & serialize */
154         int    (*ah_validate)(\|);    /* validate verifier */
155         int    (*ah_refresh)(\|);    /* refresh credentials */
156         void    (*ah_destroy)(\|);    /* destroy this structure */
157     } *ah_ops;
158     caddr_t ah_private;
159 } AUTH;
160 .Ed
161 .Sh "The CLIENT Structure"
162 .Bd -literal
163 /*
164  * Client rpc handle.
165  * Created by individual implementations.
166  * Client is responsible for initializing auth.
167  */
168
169 typedef struct {
170     AUTH    *cl_auth;    /* authenticator */
171     struct clnt_ops {
172         enum clnt_stat    (*cl_call)();    /* call remote procedure */
173         void    (*cl_abort)();        /* abort a call */
174         void    (*cl_geterr)();        /* get specific error code */
175         bool_t    (*cl_freeres)();    /* frees results */
176         void    (*cl_destroy)();    /* destroy this structure */
177         bool_t    (*cl_control)();    /* the ioctl() of rpc */
178     } *cl_ops;
179     caddr_t    cl_private;    /* private stuff */
180     char    *cl_netid;    /* network identifier */
181     char    *cl_tp;        /* device name */
182 } CLIENT;
183 .Ed
184 .Sh "The SVCXPRT structure"
185 .Bd -literal
186 enum xprt_stat {
187     XPRT_DIED,
188     XPRT_MOREREQS,
189     XPRT_IDLE
190 };
191
192 /*
193  * Server side transport handle
194  */
195 typedef struct {
196     int    xp_fd;    /* file descriptor for the server handle */
197     u_short    xp_port;    /* obsolete */
198     const struct xp_ops {
199         bool_t    (*xp_recv)();    /* receive incoming requests */
200         enum xprt_stat    (*xp_stat)();    /* get transport status */
201         bool_t    (*xp_getargs)();    /* get arguments */
202         bool_t    (*xp_reply)();      /* send reply */
203         bool_t    (*xp_freeargs)(); /* free mem allocated for args */
204         void    (*xp_destroy)();    /* destroy this struct */
205     } *xp_ops;
206     int    xp_addrlen;    /* length of remote addr.  Obsolete */
207     struct sockaddr_in    xp_raddr; /* Obsolete */
208     const struct xp_ops2 {
209         bool_t    (*xp_control)();    /* catch-all function */
210     } *xp_ops2;
211     char    *xp_tp;    /* transport provider device name */
212     char    *xp_netid;    /* network identifier */
213     struct netbuf    xp_ltaddr;    /* local transport address */
214     struct netbuf    xp_rtaddr;    /* remote transport address */
215     struct opaque_auth    xp_verf;    /* raw response verifier */
216     caddr_t    xp_p1;    /* private: for use by svc ops */
217     caddr_t    xp_p2;    /* private: for use by svc ops */
218     caddr_t    xp_p3;    /* private: for use by svc lib */
219     int    xp_type    /* transport type */
220 } SVCXPRT;
221 .Ed
222 .Sh "The svc_reg structure"
223 .Bd -literal
224 struct svc_req {
225     rpcprog_t    rq_prog;    /* service program number */
226     rpcvers_t    rq_vers;    /* service protocol version */
227     rpcproc_t    rq_proc;    /* the desired procedure */
228     struct opaque_auth    rq_cred;    /* raw creds from the wire */
229     caddr_t    rq_clntcred;    /* read only cooked cred */
230     SVCXPRT    *rq_xprt;    /* associated transport */
231 };
232 .Ed
233 .Sh "The XDR structure"
234 .Bd -literal
235 /*
236  * XDR operations.
237  * XDR_ENCODE causes the type to be encoded into the stream.
238  * XDR_DECODE causes the type to be extracted from the stream.
239  * XDR_FREE can be used to release the space allocated by an XDR_DECODE
240  * request.
241  */
242 enum xdr_op {
243     XDR_ENCODE=0,
244     XDR_DECODE=1,
245     XDR_FREE=2
246 };
247 /*
248  * This is the number of bytes per unit of external data.
249  */
250 #define BYTES_PER_XDR_UNIT    (4)
251 #define RNDUP(x)  ((((x) + BYTES_PER_XDR_UNIT - 1) /
252                    BYTES_PER_XDR_UNIT) \e * BYTES_PER_XDR_UNIT)
253
254 /*
255  * A xdrproc_t exists for each data type which is to be encoded or
256  * decoded.  The second argument to the xdrproc_t is a pointer to
257  * an opaque pointer.  The opaque pointer generally points to a
258  * structure of the data type to be decoded.  If this points to 0,
259  * then the type routines should allocate dynamic storage of the
260  * appropriate size and return it.
261  * bool_t  (*xdrproc_t)(XDR *, caddr_t *);
262  */
263 typedef  bool_t (*xdrproc_t)();
264
265 /*
266  * The XDR handle.
267  * Contains operation which is being applied to the stream,
268  * an operations vector for the particular implementation
269  */
270 typedef struct {
271     enum xdr_op    x_op;    /* operation; fast additional param */
272     struct xdr_ops {
273         bool_t    (*x_getlong)();    /* get a long from underlying stream */
274         bool_t    (*x_putlong)();    /* put a long to underlying stream */
275         bool_t    (*x_getbytes)(); /* get bytes from underlying stream */
276         bool_t    (*x_putbytes)(); /* put bytes to underlying stream */
277         u_int    (*x_getpostn)(); /* returns bytes off from beginning */
278         bool_t    (*x_setpostn)(); /* lets you reposition the stream */
279         long *    (*x_inline)();    /* buf quick ptr to buffered data */
280         void    (*x_destroy)();    /* free privates of this xdr_stream */
281     } *x_ops;
282     caddr_t    x_public;    /* users' data */
283     caddr_t    x_private;    /* pointer to private data */
284     caddr_t    x_base;    /* private used for position info */
285     u_int    x_handy;    /* extra private word */
286 } XDR;
287
288 /*
289  * The netbuf structure. This structure is defined in <xti.h> on SysV
290  * systems, but NetBSD / FreeBSD do not use XTI.
291  *
292  * Usually, buf will point to a struct sockaddr, and len and maxlen
293  * will contain the length and maximum length of that socket address,
294  * respectively.
295  */
296 struct netbuf {
297         unsigned int maxlen;
298         unsigned int len;
299         void *buf;
300 };
301
302 /*
303  * The format of the address and options arguments of the XTI t_bind call.
304  * Only provided for compatibility, it should not be used other than
305  * as an argument to svc_tli_create().
306  */
307
308 struct t_bind {
309         struct netbuf   addr;
310         unsigned int    qlen;
311 };
312 .Ed
313 .Sh "Index to Routines"
314 The following table lists RPC routines and the manual reference
315 pages on which they are described:
316 .Pp
317 .Bl -tag -width "authunix_create_default()" -compact
318 .It Em "RPC Routine"
319 .Em "Manual Reference Page"
320 .Pp
321 .It Fn auth_destroy
322 .Xr rpc_clnt_auth 3
323 .It Fn authdes_create
324 .Xr rpc_soc 3
325 .It Fn authnone_create
326 .Xr rpc_clnt_auth 3
327 .It Fn authsys_create
328 .Xr rpc_clnt_auth 3
329 .It Fn authsys_create_default
330 .Xr rpc_clnt_auth 3
331 .It Fn authunix_create
332 .Xr rpc_soc 3
333 .It Fn authunix_create_default
334 .Xr rpc_soc 3
335 .It Fn callrpc
336 .Xr rpc_soc 3
337 .It Fn clnt_broadcast
338 .Xr rpc_soc 3
339 .It Fn clnt_call
340 .Xr rpc_clnt_calls 3
341 .It Fn clnt_control
342 .Xr rpc_clnt_create 3
343 .It Fn clnt_create
344 .Xr rpc_clnt_create 3
345 .It Fn clnt_create_timed
346 .Xr rpc_clnt_create 3
347 .It Fn clnt_create_vers
348 .Xr rpc_clnt_create 3
349 .It Fn clnt_create_vers_timed
350 .Xr rpc_clnt_create 3
351 .It Fn clnt_destroy
352 .Xr rpc_clnt_create 3
353 .It Fn clnt_dg_create
354 .Xr rpc_clnt_create 3
355 .It Fn clnt_freeres
356 .Xr rpc_clnt_calls 3
357 .It Fn clnt_geterr
358 .Xr rpc_clnt_calls 3
359 .It Fn clnt_pcreateerror
360 .Xr rpc_clnt_create 3
361 .It Fn clnt_perrno
362 .Xr rpc_clnt_calls 3
363 .It Fn clnt_perror
364 .Xr rpc_clnt_calls 3
365 .It Fn clnt_raw_create
366 .Xr rpc_clnt_create 3
367 .It Fn clnt_spcreateerror
368 .Xr rpc_clnt_create 3
369 .It Fn clnt_sperrno
370 .Xr rpc_clnt_calls 3
371 .It Fn clnt_sperror
372 .Xr rpc_clnt_calls 3
373 .It Fn clnt_tli_create
374 .Xr rpc_clnt_create 3
375 .It Fn clnt_tp_create
376 .Xr rpc_clnt_create 3
377 .It Fn clnt_tp_create_timed
378 .Xr rpc_clnt_create 3
379 .It Fn clnt_udpcreate
380 .Xr rpc_soc 3
381 .It Fn clnt_vc_create
382 .Xr rpc_clnt_create 3
383 .It Fn clntraw_create
384 .Xr rpc_soc 3
385 .It Fn clnttcp_create
386 .Xr rpc_soc 3
387 .It Fn clntudp_bufcreate
388 .Xr rpc_soc 3
389 .It Fn get_myaddress
390 .Xr rpc_soc 3
391 .It Fn pmap_getmaps
392 .Xr rpc_soc 3
393 .It Fn pmap_getport
394 .Xr rpc_soc 3
395 .It Fn pmap_rmtcall
396 .Xr rpc_soc 3
397 .It Fn pmap_set
398 .Xr rpc_soc 3
399 .It Fn pmap_unset
400 .Xr rpc_soc 3
401 .It Fn registerrpc
402 .Xr rpc_soc 3
403 .It Fn rpc_broadcast
404 .Xr rpc_clnt_calls 3
405 .It Fn rpc_broadcast_exp
406 .Xr rpc_clnt_calls 3
407 .It Fn rpc_call
408 .Xr rpc_clnt_calls 3
409 .It Fn rpc_reg
410 .Xr rpc_svc_calls 3
411 .It Fn svc_create
412 .Xr rpc_svc_create 3
413 .It Fn svc_destroy
414 .Xr rpc_svc_create 3
415 .It Fn svc_dg_create
416 .Xr rpc_svc_create 3
417 .It Fn svc_dg_enablecache
418 .Xr rpc_svc_calls 3
419 .It Fn svc_fd_create
420 .Xr rpc_svc_create 3
421 .It Fn svc_fds
422 .Xr rpc_soc 3
423 .It Fn svc_freeargs
424 .Xr rpc_svc_reg 3
425 .It Fn svc_getargs
426 .Xr rpc_svc_reg 3
427 .It Fn svc_getcaller
428 .Xr rpc_soc 3
429 .It Fn svc_getreq
430 .Xr rpc_soc 3
431 .It Fn svc_getreqset
432 .Xr rpc_svc_calls 3
433 .It Fn svc_getrpccaller
434 .Xr rpc_svc_calls 3
435 .It Fn svc_kerb_reg
436 .Xr kerberos_rpc 3
437 .It Fn svc_raw_create
438 .Xr rpc_svc_create 3
439 .It Fn svc_reg
440 .Xr rpc_svc_calls 3
441 .It Fn svc_register
442 .Xr rpc_soc 3
443 .It Fn svc_run
444 .Xr rpc_svc_reg 3
445 .It Fn svc_sendreply
446 .Xr rpc_svc_reg 3
447 .It Fn svc_tli_create
448 .Xr rpc_svc_create 3
449 .It Fn svc_tp_create
450 .Xr rpc_svc_create 3
451 .It Fn svc_unreg
452 .Xr rpc_svc_calls 3
453 .It Fn svc_unregister
454 .Xr rpc_soc 3
455 .It Fn svc_vc_create
456 .Xr rpc_svc_create 3
457 .It Fn svcerr_auth
458 .Xr rpc_svc_err 3
459 .It Fn svcerr_decode
460 .Xr rpc_svc_err 3
461 .It Fn svcerr_noproc
462 .Xr rpc_svc_err 3
463 .It Fn svcerr_noprog
464 .Xr rpc_svc_err 3
465 .It Fn svcerr_progvers
466 .Xr rpc_svc_err 3
467 .It Fn svcerr_systemerr
468 .Xr rpc_svc_err 3
469 .It Fn svcerr_weakauth
470 .Xr rpc_svc_err 3
471 .It Fn svcfd_create
472 .Xr rpc_soc 3
473 .It Fn svcraw_create
474 .Xr rpc_soc 3
475 .It Fn svctcp_create
476 .Xr rpc_soc 3
477 .It Fn svcudp_bufcreate
478 .Xr rpc_soc 3
479 .It Fn svcudp_create
480 .Xr rpc_soc 3
481 .It Fn xdr_accepted_reply
482 .Xr rpc_xdr 3
483 .It Fn xdr_authsys_parms
484 .Xr rpc_xdr 3
485 .It Fn xdr_authunix_parms
486 .Xr rpc_soc 3
487 .It Fn xdr_callhdr
488 .Xr rpc_xdr 3
489 .It Fn xdr_callmsg
490 .Xr rpc_xdr 3
491 .It Fn xdr_opaque_auth
492 .Xr rpc_xdr 3
493 .It Fn xdr_rejected_reply
494 .Xr rpc_xdr 3
495 .It Fn xdr_replymsg
496 .Xr rpc_xdr 3
497 .It Fn xprt_register
498 .Xr rpc_svc_calls 3
499 .It Fn xprt_unregister
500 .Xr rpc_svc_calls 3
501 .El
502 .Sh FILES
503 .Bl -tag -width /etc/netconfig
504 .It Pa /etc/netconfig
505 .El
506 .Sh SEE ALSO
507 .Xr getnetconfig 3 ,
508 .Xr getnetpath 3 ,
509 .Xr rpcbind 3 ,
510 .Xr rpc_clnt_auth 3 ,
511 .Xr rpc_clnt_calls 3 ,
512 .Xr rpc_clnt_create 3 ,
513 .Xr rpc_svc_calls 3 ,
514 .Xr rpc_svc_create 3 ,
515 .Xr rpc_svc_err 3 ,
516 .Xr rpc_svc_reg 3 ,
517 .Xr rpc_xdr 3 ,
518 .Xr xdr 3 ,
519 .Xr netconfig 5