Numerous adjustments to the recent rpcbind etc. changes.
[dragonfly.git] / lib / libc / rpc / rpc.3
CommitLineData
ce0e08e2
PA
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 $
09ceb4e1 5.\" $DragonFly: src/lib/libc/rpc/rpc.3,v 1.8 2008/05/01 22:06:06 swildner Exp $
984263bc 6.\"
ce0e08e2 7.Dd May 7, 1993
984263bc
MD
8.Dt RPC 3
9.Os
10.Sh NAME
11.Nm rpc
ce0e08e2 12.Nd library routines for remote procedure calls
984263bc
MD
13.Sh LIBRARY
14.Lb libc
15.Sh SYNOPSIS
16.In rpc/rpc.h
ce0e08e2 17.In netconfig.h
984263bc 18.Sh DESCRIPTION
ce0e08e2
PA
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,
984263bc 40.Fn clnt_create ,
ce0e08e2
PA
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.
984263bc 46.Pp
984263bc 47The
ce0e08e2
PA
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
984263bc 76or
ce0e08e2
PA
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
984263bc 96or
ce0e08e2
PA
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
984263bc 109.Pp
984263bc 110If
ce0e08e2
PA
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;
984263bc 130.Ed
ce0e08e2
PA
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 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 */
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
ce0e08e2
PA
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
3b813696
SW
387.It Fn clntudp_create
388.Xr rpc_soc 3
ce0e08e2
PA
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
ce0e08e2
PA
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
3b813696
SW
433.\".It Fn svc_kerb_reg
434.\".Xr kerberos_rpc 3
ce0e08e2
PA
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
984263bc
MD
503.El
504.Sh SEE ALSO
ce0e08e2
PA
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