xref: /dragonfly/lib/libc/rpc/rpc.3 (revision 0db87cb7) 
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 February 23, 2009
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
19These
20routines allow C language programs to make procedure
21calls on other machines across a network.
22First, the client sends a request to the server.
23On receipt of the request, the server calls a dispatch routine
24to perform the requested service, and then sends back a reply.
25.Pp
26All
27RPC routines require the header
28.In rpc/rpc.h .
29Routines that take a
30.Vt "struct netconfig"
31also require that
32.In netconfig.h
33be included.
34.Sh Nettype
35Some of the high-level
36RPC interface routines take a
37.Fa nettype
38string as one of the arguments
39(for example,
40.Fn clnt_create ,
41.Fn svc_create ,
42.Fn rpc_reg ,
43.Fn rpc_call ) .
44This string defines a class of transports which can be used
45for a particular application.
46.Pp
47The
48.Fa nettype
49argument
50can be one of the following:
51.Bl -tag -width datagram_v
52.It netpath
53Choose from the transports which have been
54indicated by their token names in the
55.Ev NETPATH
56environment variable.
57.Ev NETPATH
58is unset or
59.Dv NULL ,
60it defaults to
61.Qq visible .
62.Qq netpath
63is the default
64.Fa nettype .
65.It visible
66Choose the transports which have the visible flag (v)
67set in the
68.Pa /etc/netconfig
69file.
70.It circuit_v
71This is same as
72.Qq visible
73except that it chooses only the connection oriented transports
74(semantics
75.Qq tpi_cots
76or
77.Qq tpi_cots_ord )
78from the entries in the
79.Pa /etc/netconfig
80file.
81.It datagram_v
82This is same as
83.Qq visible
84except that it chooses only the connectionless datagram transports
85(semantics
86.Qq tpi_clts )
87from the entries in the
88.Pa /etc/netconfig
89file.
90.It circuit_n
91This is same as
92.Qq netpath
93except that it chooses only the connection oriented datagram transports
94(semantics
95.Qq tpi_cots
96or
97.Qq tpi_cots_ord ) .
98.It datagram_n
99This is same as
100.Qq netpath
101except that it chooses only the connectionless datagram transports
102(semantics
103.Qq tpi_clts ) .
104.It udp
105This refers to Internet UDP, both version 4 and 6.
106.It tcp
107This refers to Internet TCP, both version 4 and 6.
108.El
109.Pp
110If
111.Fa nettype
112is
113.Dv NULL ,
114it defaults to
115.Qq netpath .
116The transports are tried in left to right order in the
117.Ev NETPATH
118variable or in top to down order in the
119.Pa /etc/netconfig
120file.
121.Sh Derived Types
122The 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"
132Some of the data structures used by the
133RPC package are shown below.
134.Sh "The AUTH Structure"
135.Bd -literal
136/*
137 * Authentication info. Opaque to client.
138 */
139struct 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 */
148typedef 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
169typedef 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
186enum xprt_stat {
187    XPRT_DIED,
188    XPRT_MOREREQS,
189    XPRT_IDLE
190};
191
192/*
193 * Server side transport handle
194 */
195typedef 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
224struct 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 */
242enum 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 */
263typedef  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 */
270typedef 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    char *    x_public;    /* users' data */
283    void *    x_private;    /* pointer to private data */
284    char *    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 */
296struct 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
308struct t_bind {
309	struct netbuf   addr;
310	unsigned int    qlen;
311};
312.Ed
313.Sh "Index to Routines"
314The following table lists RPC routines and the manual reference
315pages 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_vc_create
380.Xr rpc_clnt_create 3
381.It Fn clntraw_create
382.Xr rpc_soc 3
383.It Fn clnttcp_create
384.Xr rpc_soc 3
385.It Fn clntudp_bufcreate
386.Xr rpc_soc 3
387.It Fn clntudp_create
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_freeargs
422.Xr rpc_svc_reg 3
423.It Fn svc_getargs
424.Xr rpc_svc_reg 3
425.It Fn svc_getcaller
426.Xr rpc_soc 3
427.It Fn svc_getreq
428.Xr rpc_soc 3
429.It Fn svc_getreqset
430.Xr rpc_svc_calls 3
431.It Fn svc_getrpccaller
432.Xr rpc_svc_calls 3
433.\".It Fn svc_kerb_reg
434.\".Xr kerberos_rpc 3
435.It Fn svc_raw_create
436.Xr rpc_svc_create 3
437.It Fn svc_reg
438.Xr rpc_svc_calls 3
439.It Fn svc_register
440.Xr rpc_soc 3
441.It Fn svc_run
442.Xr rpc_svc_reg 3
443.It Fn svc_sendreply
444.Xr rpc_svc_reg 3
445.It Fn svc_tli_create
446.Xr rpc_svc_create 3
447.It Fn svc_tp_create
448.Xr rpc_svc_create 3
449.It Fn svc_unreg
450.Xr rpc_svc_calls 3
451.It Fn svc_unregister
452.Xr rpc_soc 3
453.It Fn svc_vc_create
454.Xr rpc_svc_create 3
455.It Fn svcerr_auth
456.Xr rpc_svc_err 3
457.It Fn svcerr_decode
458.Xr rpc_svc_err 3
459.It Fn svcerr_noproc
460.Xr rpc_svc_err 3
461.It Fn svcerr_noprog
462.Xr rpc_svc_err 3
463.It Fn svcerr_progvers
464.Xr rpc_svc_err 3
465.It Fn svcerr_systemerr
466.Xr rpc_svc_err 3
467.It Fn svcerr_weakauth
468.Xr rpc_svc_err 3
469.It Fn svcfd_create
470.Xr rpc_soc 3
471.It Fn svcraw_create
472.Xr rpc_soc 3
473.It Fn svctcp_create
474.Xr rpc_soc 3
475.It Fn svcudp_bufcreate
476.Xr rpc_soc 3
477.It Fn svcudp_create
478.Xr rpc_soc 3
479.It Fn xdr_accepted_reply
480.Xr rpc_xdr 3
481.It Fn xdr_authsys_parms
482.Xr rpc_xdr 3
483.It Fn xdr_authunix_parms
484.Xr rpc_soc 3
485.It Fn xdr_callhdr
486.Xr rpc_xdr 3
487.It Fn xdr_callmsg
488.Xr rpc_xdr 3
489.It Fn xdr_opaque_auth
490.Xr rpc_xdr 3
491.It Fn xdr_rejected_reply
492.Xr rpc_xdr 3
493.It Fn xdr_replymsg
494.Xr rpc_xdr 3
495.It Fn xprt_register
496.Xr rpc_svc_calls 3
497.It Fn xprt_unregister
498.Xr rpc_svc_calls 3
499.El
500.Sh FILES
501.Bl -tag -width /etc/netconfig
502.It Pa /etc/netconfig
503.El
504.Sh SEE ALSO
505.Xr getnetconfig 3 ,
506.Xr getnetpath 3 ,
507.Xr rpcbind 3 ,
508.Xr rpc_clnt_auth 3 ,
509.Xr rpc_clnt_calls 3 ,
510.Xr rpc_clnt_create 3 ,
511.Xr rpc_svc_calls 3 ,
512.Xr rpc_svc_create 3 ,
513.Xr rpc_svc_err 3 ,
514.Xr rpc_svc_reg 3 ,
515.Xr rpc_xdr 3 ,
516.Xr xdr 3 ,
517.Xr netconfig 5
518