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