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