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 $
10 .Nd library routines for remote procedure calls
18 routines allow C language programs to make procedure
19 calls on other machines across a network.
20 First, the client sends a request to the server.
21 On receipt of the request, the server calls a dispatch routine
22 to perform the requested service, and then sends back a reply.
25 RPC routines require the header
28 .Vt "struct netconfig"
33 Some of the high-level
34 RPC interface routines take a
36 string as one of the arguments
42 This string defines a class of transports which can be used
43 for a particular application.
48 can be one of the following:
49 .Bl -tag -width datagram_v
51 Choose from the transports which have been
52 indicated by their token names in the
64 Choose the transports which have the visible flag (v)
71 except that it chooses only the connection oriented transports
76 from the entries in the
82 except that it chooses only the connectionless datagram transports
85 from the entries in the
91 except that it chooses only the connection oriented datagram transports
99 except that it chooses only the connectionless datagram transports
103 This refers to Internet UDP, both version 4 and 6.
105 This refers to Internet TCP, both version 4 and 6.
114 The transports are tried in left to right order in the
116 variable or in top to down order in the
120 The derived types used in the RPC interfaces are defined as follows:
122 typedef uint32_t rpcprog_t;
123 typedef uint32_t rpcvers_t;
124 typedef uint32_t rpcproc_t;
125 typedef uint32_t rpcprot_t;
126 typedef uint32_t rpcport_t;
127 typedef int32_t rpc_inline_t;
129 .Sh "Data Structures"
130 Some of the data structures used by the
131 RPC package are shown below.
132 .Sh "The AUTH Structure"
135 * Authentication info. Opaque to client.
138 enum_t oa_flavor; /* flavor of auth */
139 caddr_t oa_base; /* address of more auth stuff */
140 u_int oa_length; /* not to exceed MAX_AUTH_BYTES */
144 * Auth handle, interface to client side authenticators.
147 struct opaque_auth ah_cred;
148 struct opaque_auth ah_verf;
150 void (*ah_nextverf)(\|);
151 int (*ah_marshal)(\|); /* nextverf & serialize */
152 int (*ah_validate)(\|); /* validate verifier */
153 int (*ah_refresh)(\|); /* refresh credentials */
154 void (*ah_destroy)(\|); /* destroy this structure */
159 .Sh "The CLIENT Structure"
163 * Created by individual implementations.
164 * Client is responsible for initializing auth.
168 AUTH *cl_auth; /* authenticator */
170 enum clnt_stat (*cl_call)(); /* call remote procedure */
171 void (*cl_abort)(); /* abort a call */
172 void (*cl_geterr)(); /* get specific error code */
173 bool_t (*cl_freeres)(); /* frees results */
174 void (*cl_destroy)(); /* destroy this structure */
175 bool_t (*cl_control)(); /* the ioctl() of rpc */
177 caddr_t cl_private; /* private stuff */
178 char *cl_netid; /* network identifier */
179 char *cl_tp; /* device name */
182 .Sh "The SVCXPRT structure"
191 * Server side transport handle
194 int xp_fd; /* file descriptor for the server handle */
195 u_short xp_port; /* obsolete */
196 const struct xp_ops {
197 bool_t (*xp_recv)(); /* receive incoming requests */
198 enum xprt_stat (*xp_stat)(); /* get transport status */
199 bool_t (*xp_getargs)(); /* get arguments */
200 bool_t (*xp_reply)(); /* send reply */
201 bool_t (*xp_freeargs)(); /* free mem allocated for args */
202 void (*xp_destroy)(); /* destroy this struct */
204 int xp_addrlen; /* length of remote addr. Obsolete */
205 struct sockaddr_in xp_raddr; /* Obsolete */
206 const struct xp_ops2 {
207 bool_t (*xp_control)(); /* catch-all function */
209 char *xp_tp; /* transport provider device name */
210 char *xp_netid; /* network identifier */
211 struct netbuf xp_ltaddr; /* local transport address */
212 struct netbuf xp_rtaddr; /* remote transport address */
213 struct opaque_auth xp_verf; /* raw response verifier */
214 caddr_t xp_p1; /* private: for use by svc ops */
215 caddr_t xp_p2; /* private: for use by svc ops */
216 caddr_t xp_p3; /* private: for use by svc lib */
217 int xp_type /* transport type */
220 .Sh "The svc_reg structure"
223 rpcprog_t rq_prog; /* service program number */
224 rpcvers_t rq_vers; /* service protocol version */
225 rpcproc_t rq_proc; /* the desired procedure */
226 struct opaque_auth rq_cred; /* raw creds from the wire */
227 caddr_t rq_clntcred; /* read only cooked cred */
228 SVCXPRT *rq_xprt; /* associated transport */
231 .Sh "The XDR structure"
235 * XDR_ENCODE causes the type to be encoded into the stream.
236 * XDR_DECODE causes the type to be extracted from the stream.
237 * XDR_FREE can be used to release the space allocated by an XDR_DECODE
246 * This is the number of bytes per unit of external data.
248 #define BYTES_PER_XDR_UNIT (4)
249 #define RNDUP(x) ((((x) + BYTES_PER_XDR_UNIT - 1) /
250 BYTES_PER_XDR_UNIT) \e * BYTES_PER_XDR_UNIT)
253 * A xdrproc_t exists for each data type which is to be encoded or
254 * decoded. The second argument to the xdrproc_t is a pointer to
255 * an opaque pointer. The opaque pointer generally points to a
256 * structure of the data type to be decoded. If this points to 0,
257 * then the type routines should allocate dynamic storage of the
258 * appropriate size and return it.
259 * bool_t (*xdrproc_t)(XDR *, caddr_t *);
261 typedef bool_t (*xdrproc_t)();
265 * Contains operation which is being applied to the stream,
266 * an operations vector for the particular implementation
269 enum xdr_op x_op; /* operation; fast additional param */
271 bool_t (*x_getlong)(); /* get a long from underlying stream */
272 bool_t (*x_putlong)(); /* put a long to underlying stream */
273 bool_t (*x_getbytes)(); /* get bytes from underlying stream */
274 bool_t (*x_putbytes)(); /* put bytes to underlying stream */
275 u_int (*x_getpostn)(); /* returns bytes off from beginning */
276 bool_t (*x_setpostn)(); /* lets you reposition the stream */
277 long * (*x_inline)(); /* buf quick ptr to buffered data */
278 void (*x_destroy)(); /* free privates of this xdr_stream */
280 caddr_t x_public; /* users' data */
281 caddr_t x_private; /* pointer to private data */
282 caddr_t x_base; /* private used for position info */
283 u_int x_handy; /* extra private word */
287 * The netbuf structure. This structure is defined in <xti.h> on SysV
288 * systems, but NetBSD / FreeBSD do not use XTI.
290 * Usually, buf will point to a struct sockaddr, and len and maxlen
291 * will contain the length and maximum length of that socket address,
301 * The format of the address and options arguments of the XTI t_bind call.
302 * Only provided for compatibility, it should not be used other than
303 * as an argument to svc_tli_create().
311 .Sh "Index to Routines"
312 The following table lists RPC routines and the manual reference
313 pages on which they are described:
315 .Bl -tag -width "authunix_create_default()" -compact
317 .Em "Manual Reference Page"
321 .It Fn authdes_create
323 .It Fn authnone_create
325 .It Fn authsys_create
327 .It Fn authsys_create_default
329 .It Fn authunix_create
331 .It Fn authunix_create_default
335 .It Fn clnt_broadcast
340 .Xr rpc_clnt_create 3
342 .Xr rpc_clnt_create 3
343 .It Fn clnt_create_timed
344 .Xr rpc_clnt_create 3
345 .It Fn clnt_create_vers
346 .Xr rpc_clnt_create 3
347 .It Fn clnt_create_vers_timed
348 .Xr rpc_clnt_create 3
350 .Xr rpc_clnt_create 3
351 .It Fn clnt_dg_create
352 .Xr rpc_clnt_create 3
357 .It Fn clnt_pcreateerror
358 .Xr rpc_clnt_create 3
363 .It Fn clnt_raw_create
364 .Xr rpc_clnt_create 3
365 .It Fn clnt_spcreateerror
366 .Xr rpc_clnt_create 3
371 .It Fn clnt_tli_create
372 .Xr rpc_clnt_create 3
373 .It Fn clnt_tp_create
374 .Xr rpc_clnt_create 3
375 .It Fn clnt_tp_create_timed
376 .Xr rpc_clnt_create 3
377 .It Fn clnt_udpcreate
379 .It Fn clnt_vc_create
380 .Xr rpc_clnt_create 3
381 .It Fn clntraw_create
383 .It Fn clnttcp_create
385 .It Fn clntudp_bufcreate
403 .It Fn rpc_broadcast_exp
415 .It Fn svc_dg_enablecache
431 .It Fn svc_getrpccaller
435 .It Fn svc_raw_create
445 .It Fn svc_tli_create
451 .It Fn svc_unregister
463 .It Fn svcerr_progvers
465 .It Fn svcerr_systemerr
467 .It Fn svcerr_weakauth
475 .It Fn svcudp_bufcreate
479 .It Fn xdr_accepted_reply
481 .It Fn xdr_authsys_parms
483 .It Fn xdr_authunix_parms
489 .It Fn xdr_opaque_auth
491 .It Fn xdr_rejected_reply
497 .It Fn xprt_unregister
501 .Bl -tag -width /etc/netconfig
502 .It Pa /etc/netconfig
507 .Xr rpc_clnt_auth 3 ,
508 .Xr rpc_clnt_calls 3 ,
509 .Xr rpc_clnt_create 3 ,
510 .Xr rpc_svc_calls 3 ,
511 .Xr rpc_svc_create 3 ,