1rpc(3NSL) Networking Services Library Functions rpc(3NSL)
2
6 rpc - library routines for remote procedure calls
7
9 cc [ flag ... ] file ... -lnsl [ library ... ]
10 #include <rpc/rpc.h>
11 #include <netconfig.h>
12
15 These routines allow C language programs to make procedure calls on
16 other machines across a network. First, the client sends a request to
17 the server. On receipt of the request, the server calls a dispatch rou‐
18 tine to perform the requested service, and then sends back a reply.
19 All RPC routines require the header <rpc/rpc.h>. Routines that take a
22 netconfig structure also require that <netconfig.h> be included. Appli‐
23 cations using RPC and XDR routines should be linked with the libnsl
24 library.
25 Multithread Considerations
27 In the case of multithreaded applications, the -mt option must be spec‐
28 ified on the command line at compilation time to enable a thread-spe‐
29 cific version of rpc_createerr(). See rpc_clnt_create(3NSL) and
30 threads(5).
31 When used in multithreaded applications, client-side routines are MT-
34 Safe. CLIENT handles can be shared between threads; however, in this
35 implementation, requests by different threads are serialized (that is,
36 the first request will receive its results before the second request is
37 sent). See rpc_clnt_create(3NSL).
38 When used in multithreaded applications, server-side routines are usu‐
41 ally Unsafe. In this implementation the service transport handle, SVCX‐
42 PRT contains a single data area for decoding arguments and encoding
43 results. See rpc_svc_create(3NSL). Therefore, this structure cannot be
44 freely shared between threads that call functions that do this. Rou‐
45 tines that are affected by this restriction are marked as unsafe for MT
46 applications. See rpc_svc_calls(3NSL).
47 Nettyp
49 Some of the high-level RPC interface routines take a nettype string as
50 one of the parameters (for example, clnt_create(), svc_create(),
51 rpc_reg(), rpc_call()). This string defines a class of transports which
52 can be used for a particular application.
53 nettype can be one of the following:
56 netpath Choose from the transports which have been indicated by
58 their token names in the NETPATH environment variable. If
59 NETPATH is unset or NULL, it defaults to visible. netpath
60 is the default nettype.
61 visible Choose the transports which have the visible flag (v) set
64 in the /etc/netconfig file.
65 circuit_v This is same as visible except that it chooses only the
68 connection oriented transports (semantics tpi_cots or
69 tpi_cots_ord) from the entries in the /etc/netconfig
70 file.
71 datagram_v This is same as visible except that it chooses only the
74 connectionless datagram transports (semantics tpi_clts)
75 from the entries in the /etc/netconfig file.
76 circuit_n This is same as netpath except that it chooses only the
79 connection oriented datagram transports (semantics
80 tpi_cots or tpi_cots_ord).
81 datagram_n This is same as netpath except that it chooses only the
84 connectionless datagram transports (semantics tpi_clts).
85 udp This refers to Internet UDP.
88 tcp This refers to Internet TCP.
91 If nettype is NULL, it defaults to netpath. The transports are tried
95 in left to right order in the NETPATH variable or in top to down order
96 in the /etc/netconfig file.
97 Derived Types
99 In a 64-bit environment, the derived types are defined as follows:
100 typedef uint32_t rpcprog_t;
105 typedef uint32_t rpcvers_t;
106 typedef uint32_t rpcproc_t;
107 typedef uint32_t rpcprot_t;
108 typedef uint32_t rpcport_t;
109 typedef int32_t rpc_inline_t;
110 In a 32-bit environment, the derived types are defined as follows:
114 typedef unsigned long rpcprog_t;
119 typedef unsigned long rpcvers_t;
120 typedef unsigned long rpcproc_t;
121 typedef unsigned long rpcprot_t;
122 typedef unsigned long rpcport_t;
123 typedef long rpc_inline_t;
124 Data Structures
127 Some of the data structures used by the RPC package are shown below.
128 The AUTH Structure
130 union des_block {
131 struct {
132 u_int32 high;
133 u_int32 low;
134 } key;
135 char c[8];
136 };
137 typedef union des_block des_block;
138 extern bool_t xdr_des_block();
139 /*
140 * Authentication info. Opaque to client.
141 */
142 struct opaque_auth {
143 enum_t oa_flavor; /* flavor of auth */
144 caddr_t oa_base; /* address of more auth stuff */
145 uint_t oa_length; /* not to exceed MAX_AUTH_BYTES */
146 };
147 /*
148 * Auth handle, interface to client side authenticators.
149 */
150 typedef struct {
151 struct opaque_auth ah_cred;
152 struct opaque_auth ah_verf;
153 union des_block ah_key;
154 struct auth_ops {
155 void(*ah_nextverf)();
156 int(*ah_marshal)(); /* nextverf & serialize */
157 int(*ah_validate)(); /* validate verifier */
158 int(*ah_refresh)(); /* refresh credentials */
159 void(*ah_destroy)(); /* destroy this structure */
160 } *ah_ops;
161 caddr_t ah_private;
162 } AUTH;
163 The CLIENT Structure
166 /*
167 * Client rpc handle.
168 * Created by individual implementations.
169 * Client is responsible for initializing auth.
170 */
171 typedef struct {
172 AUTH *cl_auth; /* authenticator */
173 struct clnt_ops {
174 enum clnt_stat (*cl_call)(); /* call remote procedure */
175 void (*cl_abort)(); /* abort a call */
176 void (*cl_geterr)(); /* get specific error code */
177 bool_t (*cl_freeres)(); /* frees results */
178 void (*cl_destroy)(); /* destroy this structure */
179 bool_t (*cl_control)(); /* the ioctl() of rpc */
180 int (*cl_settimers)(); /* set rpc level timers */
181 } *cl_ops;
182 caddr_t cl_private; /* private stuff */
183 char *cl_netid; /* network identifier */
184 char *cl_tp; /* device name */
185 } CLIENT;
186 The SVCXPRT Structure
189 enum xprt_stat {
190 XPRT_DIED,
191 XPRT_MOREREQS,
192 XPRT_IDLE
193 };
194 /*
195 * Server side transport handle
196 */
197 typedef struct {
198 int xp_fd; /* file descriptor for the
199 ushort_t xp_port; /* obsolete */
200 struct xp_ops {
201 bool_t (*xp_recv)(); /* receive incoming requests */
202 enum xprt_stat (*xp_stat)(); /* get transport status */
203 bool_t (*xp_getargs)(); /* get arguments */
204 bool_t (*xp_reply)(); /* send reply */
205 bool_t (*xp_freeargs)(); /* free mem allocated
206 for args */
207 void (*xp_destroy)(); /* destroy this struct */
208 } *xp_ops;
209 int xp_addrlen; /* length of remote addr.
210 Obsolete */
211 char *xp_tp; /* transport provider device
212 name */
213 char *xp_netid; /* network identifier */
214 struct netbuf xp_ltaddr; /* local transport address */
215 struct netbuf xp_rtaddr; /* remote transport address */
216 char xp_raddr[16]; /* remote address. Obsolete */
217 struct opaque_auth xp_verf; /* raw response verifier */
218 caddr_t xp_p1; /* private: for use
219 by svc ops */
220 caddr_t xp_p2; /* private: for use
221 by svc ops */
222 caddr_t xp_p3; /* private: for use
223 by svc lib */
224 int xp_type /* transport type */
225 } SVCXPRT;
226 The svc_reg Structure
229 struct svc_req {
230 rpcprog_t rq_prog; /* service program number */
231 rpcvers_t rq_vers; /* service protocol version */
232 rpcproc_t rq_proc; /* the desired procedure */
233 struct opaque_auth rq_cred; /* raw creds from the wire */
234 caddr_t rq_clntcred; /* read only cooked cred */
235 SVCXPRT *rq_xprt; /* associated transport */
236 };
238 The XDR Structure
241 /*
242 * XDR operations.
243 * XDR_ENCODE causes the type to be encoded into the stream.
244 * XDR_DECODE causes the type to be extracted from the stream.
245 * XDR_FREE can be used to release the space allocated by an XDR_DECODE
246 * request.
247 */
248 enum xdr_op {
249 XDR_ENCODE=0,
250 XDR_DECODE=1,
251 XDR_FREE=2
252 };
253 /*
254 * This is the number of bytes per unit of external data.
255 */
256 #define BYTES_PER_XDR_UNIT (4)
257 #define RNDUP(x) ((((x) + BYTES_PER_XDR_UNIT - 1) /
258 BYTES_PER_XDR_UNIT) \ * BYTES_PER_XDR_UNIT)
259 /*
260 * A xdrproc_t exists for each data type which is to be encoded or
261 * decoded. The second argument to the xdrproc_t is a pointer to
262 * an opaque pointer. The opaque pointer generally points to a
263 * structure of the data type to be decoded. If this points to 0,
264 * then the type routines should allocate dynamic storage of the
265 * appropriate size and return it.
266 * bool_t (*xdrproc_t)(XDR *, caddr_t *);
267 */
268 typedef bool_t (*xdrproc_t)();
269 /*
270 * The XDR handle.
271 * Contains operation which is being applied to the stream,
272 * an operations vector for the particular implementation
273 */
274 typedef struct {
275 enum xdr_op x_op; /* operation; fast additional param */
277 struct xdr_ops {
278 bool_t (*x_getlong)(); /* get long from underlying stream */
280 bool_t (*x_putlong)(); /* put long to underlying stream */
281 bool_t (*x_getbytes)(); /* get bytes from underlying stream */
282 bool_t (*x_putbytes)(); /* put bytes to underlying stream */
283 uint_t (*x_getpostn)(); /* returns bytes off from beginning */
284 bool_t (*x_setpostn)(); /* reposition the stream */
285 rpc_inline_t *(*x_inline)(); /* buf quick ptr to buffered data */
286 void (*x_destroy)(); /* free privates of this xdr_stream */
287 bool_t (*x_control)(); /* changed/retrieve client object info*/
288 bool_t (*x_getint32)(); /* get int from underlying stream */
289 bool_t (*x_putint32)(); /* put int to underlying stream */
290 } *x_ops;
292 caddr_t x_public; /* users' data */
294 caddr_t x_priv /* pointer to private data */
295 caddr_t x_base; /* private used for position info */
296 int x_handy; /* extra private word */
297 XDR;
298 Index to Routines
301 The following table lists RPC routines and the manual reference pages
302 on which they are described:
303 RPC Routine Manual Reference Page
305 auth_destroy rpc_clnt_auth(3NSL)
308 authdes_create rpc_soc(3NSL)
311 authdes_getucred secure_rpc(3NSL)
314 authdes_seccreate secure_rpc(3NSL)
317 authnone_create rpc_clnt_auth(3NSL)
320 authsys_create rpc_clnt_auth(3NSL)
323 authsys_create_default rpc_clnt_auth(3NSL)
326 authunix_create rpc_soc(3NSL)
329 authunix_create_default rpc_soc(3NSL)
332 callrpc rpc_soc(3NSL)
335 clnt_broadcast rpc_soc(3NSL)
338 clnt_call rpc_clnt_calls(3NSL)
341 clnt_control rpc_clnt_create(3NSL)
344 clnt_create rpc_clnt_create(3NSL)
347 clnt_destroy rpc_clnt_create(3NSL)
350 clnt_dg_create rpc_clnt_create(3NSL)
353 clnt_freeres rpc_clnt_calls(3NSL)
356 clnt_geterr rpc_clnt_calls(3NSL)
359 clnt_pcreateerror rpc_clnt_create(3NSL)
362 clnt_perrno rpc_clnt_calls(3NSL)
365 clnt_perror rpc_clnt_calls(3NSL)
368 clnt_raw_create rpc_clnt_create(3NSL)
371 clnt_spcreateerror rpc_clnt_create(3NSL)
374 clnt_sperrno rpc_clnt_calls(3NSL)
377 clnt_sperror rpc_clnt_calls(3NSL)
380 clnt_tli_create rpc_clnt_create(3NSL)
383 clnt_tp_create rpc_clnt_create(3NSL)
386 clnt_udpcreate rpc_soc(3NSL)
389 clnt_vc_create rpc_clnt_create(3NSL)
392 clntraw_create rpc_soc(3NSL)
395 clnttcp_create rpc_soc(3NSL)
398 clntudp_bufcreate rpc_soc(3NSL)
401 get_myaddress rpc_soc(3NSL)
404 getnetname secure_rpc(3NSL)
407 host2netname secure_rpc(3NSL)
410 key_decryptsession secure_rpc(3NSL)
413 key_encryptsession secure_rpc(3NSL)
416 key_gendes secure_rpc(3NSL)
419 key_setsecret secure_rpc(3NSL)
422 netname2host secure_rpc(3NSL)
425 netname2user secure_rpc(3NSL)
428 pmap_getmaps rpc_soc(3NSL)
431 pmap_getport rpc_soc(3NSL)
434 pmap_rmtcall rpc_soc(3NSL)
437 pmap_set rpc_soc(3NSL)
440 pmap_unset rpc_soc(3NSL)
443 registerrpc rpc_soc(3NSL)
446 rpc_broadcast rpc_clnt_calls(3NSL)
449 rpc_broadcast_exp rpc_clnt_calls(3NSL)
452 rpc_call rpc_clnt_calls(3NSL)
455 rpc_reg rpc_svc_calls(3NSL)
458 svc_create rpc_svc_create(3NSL)
461 svc_destroy rpc_svc_create(3NSL)
464 svc_dg_create rpc_svc_create(3NSL)
467 svc_dg_enablecache rpc_svc_calls(3NSL)
470 svc_fd_create rpc_svc_create(3NSL)
473 svc_fds rpc_soc(3NSL)
476 svc_freeargs rpc_svc_reg(3NSL)
479 svc_getargs rpc_svc_reg(3NSL)
482 svc_getcaller rpc_soc(3NSL)
485 svc_getreq rpc_soc(3NSL)
488 svc_getreqset rpc_svc_calls(3NSL)
491 svc_getrpccaller rpc_svc_calls(3NSL)
494 svc_raw_create rpc_svc_create(3NSL)
497 svc_reg rpc_svc_calls(3NSL)
500 svc_register rpc_soc(3NSL)
503 svc_run rpc_svc_reg(3NSL)
506 svc_sendreply rpc_svc_reg(3NSL)
509 svc_tli_create rpc_svc_create(3NSL)
512 svc_tp_create rpc_svc_create(3NSL)
515 svc_unreg rpc_svc_calls(3NSL)
518 svc_unregister rpc_soc(3NSL)
521 svc_vc_create rpc_svc_create(3NSL)
524 svcerr_auth rpc_svc_err(3NSL)
527 svcerr_decode rpc_svc_err(3NSL)
530 svcerr_noproc rpc_svc_err(3NSL)
533 svcerr_noprog rpc_svc_err(3NSL)
536 svcerr_progvers rpc_svc_err(3NSL)
539 svcerr_systemerr rpc_svc_err(3NSL)
542 svcerr_weakauth rpc_svc_err(3NSL)
545 svcfd_create rpc_soc(3NSL)
548 svcraw_create rpc_soc(3NSL)
551 svctcp_create rpc_soc(3NSL)
554 svcudp_bufcreate rpc_soc(3NSL)
557 svcudp_create rpc_soc(3NSL)
560 user2netname secure_rpc(3NSL)
563 xdr_accepted_reply rpc_xdr(3NSL)
566 xdr_authsys_parms rpc_xdr(3NSL)
569 xdr_authunix_parms rpc_soc(3NSL)
572 xdr_callhdr rpc_xdr(3NSL)
575 xdr_callmsg rpc_xdr(3NSL)
578 xdr_opaque_auth rpc_xdr(3NSL)
581 xdr_rejected_reply rpc_xdr(3NSL)
584 xdr_replymsg rpc_xdr(3NSL)
587 xprt_register rpc_svc_calls(3NSL)
590 xprt_unregister rpc_svc_calls(3NSL)
593
596 /etc/netconfig
597
599 See attributes(5) for descriptions of the following attributes:
600 ┌─────────────────────────────┬─────────────────────────────┐
605 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
606 ├─────────────────────────────┼─────────────────────────────┤
607 │MT-Level │MT-Safe with exceptions │
608 └─────────────────────────────┴─────────────────────────────┘
609
611 getnetconfig(3NSL), getnetpath(3NSL), rpc_clnt_auth(3NSL),
612 rpc_clnt_calls(3NSL), rpc_clnt_create(3NSL), rpc_svc_calls(3NSL),
613 rpc_svc_create(3NSL), rpc_svc_err(3NSL), rpc_svc_reg(3NSL),
614 rpc_xdr(3NSL), rpcbind(3NSL), secure_rpc(3NSL), threads(5), xdr(3NSL),
615 netconfig(4), rpc(4), attributes(5), environ(5)
616SunOS 5.11 5 Jun 2001 rpc(3NSL)