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 $
12 .Nd library routines for remote procedure calls
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.
27 RPC routines require the header
30 .Vt "struct netconfig"
35 Some of the high-level
36 RPC interface routines take a
38 string as one of the arguments
44 This string defines a class of transports which can be used
45 for a particular application.
50 can be one of the following:
51 .Bl -tag -width datagram_v
53 Choose from the transports which have been
54 indicated by their token names in the
66 Choose the transports which have the visible flag (v)
73 except that it chooses only the connection oriented transports
78 from the entries in the
84 except that it chooses only the connectionless datagram transports
87 from the entries in the
93 except that it chooses only the connection oriented datagram transports
101 except that it chooses only the connectionless datagram transports
105 This refers to Internet UDP, both version 4 and 6.
107 This refers to Internet TCP, both version 4 and 6.
116 The transports are tried in left to right order in the
118 variable or in top to down order in the
122 The derived types used in the RPC interfaces are defined as follows:
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;
131 .Sh "Data Structures"
132 Some of the data structures used by the
133 RPC package are shown below.
134 .Sh "The AUTH Structure"
137 * Authentication info. Opaque to client.
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 */
146 * Auth handle, interface to client side authenticators.
149 struct opaque_auth ah_cred;
150 struct opaque_auth ah_verf;
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 */
161 .Sh "The CLIENT Structure"
165 * Created by individual implementations.
166 * Client is responsible for initializing auth.
170 AUTH *cl_auth; /* authenticator */
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 */
179 caddr_t cl_private; /* private stuff */
180 char *cl_netid; /* network identifier */
181 char *cl_tp; /* device name */
184 .Sh "The SVCXPRT structure"
193 * Server side transport handle
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 */
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 */
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 */
222 .Sh "The svc_reg structure"
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 */
233 .Sh "The XDR structure"
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
248 * This is the number of bytes per unit of external data.
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)
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 *);
263 typedef bool_t (*xdrproc_t)();
267 * Contains operation which is being applied to the stream,
268 * an operations vector for the particular implementation
271 enum xdr_op x_op; /* operation; fast additional param */
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 */
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 */
289 * The netbuf structure. This structure is defined in <xti.h> on SysV
290 * systems, but NetBSD / FreeBSD do not use XTI.
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,
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().
313 .Sh "Index to Routines"
314 The following table lists RPC routines and the manual reference
315 pages on which they are described:
317 .Bl -tag -width "authunix_create_default()" -compact
319 .Em "Manual Reference Page"
323 .It Fn authdes_create
325 .It Fn authnone_create
327 .It Fn authsys_create
329 .It Fn authsys_create_default
331 .It Fn authunix_create
333 .It Fn authunix_create_default
337 .It Fn clnt_broadcast
342 .Xr rpc_clnt_create 3
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
352 .Xr rpc_clnt_create 3
353 .It Fn clnt_dg_create
354 .Xr rpc_clnt_create 3
359 .It Fn clnt_pcreateerror
360 .Xr rpc_clnt_create 3
365 .It Fn clnt_raw_create
366 .Xr rpc_clnt_create 3
367 .It Fn clnt_spcreateerror
368 .Xr rpc_clnt_create 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
381 .It Fn clnt_vc_create
382 .Xr rpc_clnt_create 3
383 .It Fn clntraw_create
385 .It Fn clnttcp_create
387 .It Fn clntudp_bufcreate
405 .It Fn rpc_broadcast_exp
417 .It Fn svc_dg_enablecache
433 .It Fn svc_getrpccaller
437 .It Fn svc_raw_create
447 .It Fn svc_tli_create
453 .It Fn svc_unregister
465 .It Fn svcerr_progvers
467 .It Fn svcerr_systemerr
469 .It Fn svcerr_weakauth
477 .It Fn svcudp_bufcreate
481 .It Fn xdr_accepted_reply
483 .It Fn xdr_authsys_parms
485 .It Fn xdr_authunix_parms
491 .It Fn xdr_opaque_auth
493 .It Fn xdr_rejected_reply
499 .It Fn xprt_unregister
503 .Bl -tag -width /etc/netconfig
504 .It Pa /etc/netconfig
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 ,