1RPC(3) BSD Library Functions Manual RPC(3)
2
4 rpc — library routines for remote procedure calls
5
7 Standard C Library (libc, -lc)
8
10 #include <rpc/rpc.h>
11 #include <netconfig.h>
12
14 These routines allow C language programs to make procedure calls on other
15 machines across a network. First, the client sends a request to the
16 server. On receipt of the request, the server calls a dispatch routine
17 to perform the requested service, and then sends back a reply.
18 All RPC routines require the header <rpc/rpc.h>. Routines that take a
20 struct netconfig also require that <netconfig.h> be included.
21
23 Some of the high-level RPC interface routines take a nettype string as
24 one of the arguments (for example, clnt_create(), svc_create(),
25 rpc_reg(), rpc_call()). This string defines a class of transports which
26 can be used for a particular application.
27 The nettype argument can be one of the following:
29 netpath Choose from the transports which have been indicated by their
31 token names in the NETPATH environment variable. NETPATH is
32 unset or NULL, it defaults to "visible". "netpath" is the
33 default nettype.
34 visible Choose the transports which have the visible flag (v) set in
36 the /etc/netconfig file.
37 circuit_v This is same as "visible" except that it chooses only the
39 connection oriented transports (semantics "tpi_cots" or
40 "tpi_cots_ord") from the entries in the /etc/netconfig file.
41 datagram_v This is same as "visible" except that it chooses only the
43 connectionless datagram transports (semantics "tpi_clts")
44 from the entries in the /etc/netconfig file.
45 circuit_n This is same as "netpath" except that it chooses only the
47 connection oriented datagram transports (semantics "tpi_cots"
48 or "tpi_cots_ord").
49 datagram_n This is same as "netpath" except that it chooses only the
51 connectionless datagram transports (semantics "tpi_clts").
52 udp This refers to Internet UDP, both version 4 and 6.
54 tcp This refers to Internet TCP, both version 4 and 6.
56 If nettype is NULL, it defaults to "netpath". The transports are tried
58 in left to right order in the NETPATH variable or in top to down order in
59 the /etc/netconfig file.
60
62 The derived types used in the RPC interfaces are defined as follows:
63 typedef u_int32_t rpcprog_t;
65 typedef u_int32_t rpcvers_t;
66 typedef u_int32_t rpcproc_t;
67 typedef u_int32_t rpcprot_t;
68 typedef u_int32_t rpcport_t;
69 typedef int32_t rpc_inline_t;
70
72 Some of the data structures used by the RPC package are shown below.
73
75 /*
76 * Authentication info. Opaque to client.
77 */
78 struct opaque_auth {
79 enum_t oa_flavor; /* flavor of auth */
80 caddr_t oa_base; /* address of more auth stuff */
81 u_int oa_length; /* not to exceed MAX_AUTH_BYTES */
82 };
83 /*
85 * Auth handle, interface to client side authenticators.
86 */
87 typedef struct {
88 struct opaque_auth ah_cred;
89 struct opaque_auth ah_verf;
90 struct auth_ops {
91 void (*ah_nextverf)();
92 int (*ah_marshal)(); /* nextverf & serialize */
93 int (*ah_validate)(); /* validate verifier */
94 int (*ah_refresh)(); /* refresh credentials */
95 void (*ah_destroy)(); /* destroy this structure */
96 } *ah_ops;
97 caddr_t ah_private;
98 } AUTH;
99
101 /*
102 * Client rpc handle.
103 * Created by individual implementations.
104 * Client is responsible for initializing auth.
105 */
106 typedef struct {
108 AUTH *cl_auth; /* authenticator */
109 struct clnt_ops {
110 enum clnt_stat (*cl_call)(); /* call remote procedure */
111 void (*cl_abort)(); /* abort a call */
112 void (*cl_geterr)(); /* get specific error code */
113 bool_t (*cl_freeres)(); /* frees results */
114 void (*cl_destroy)(); /* destroy this structure */
115 bool_t (*cl_control)(); /* the ioctl() of rpc */
116 } *cl_ops;
117 caddr_t cl_private; /* private stuff */
118 char *cl_netid; /* network identifier */
119 char *cl_tp; /* device name */
120 } CLIENT;
121
123 enum xprt_stat {
124 XPRT_DIED,
125 XPRT_MOREREQS,
126 XPRT_IDLE
127 };
128 /*
130 * Server side transport handle
131 */
132 typedef struct {
133 int xp_fd; /* file descriptor for the server handle */
134 u_short xp_port; /* obsolete */
135 const struct xp_ops {
136 bool_t (*xp_recv)(); /* receive incoming requests */
137 enum xprt_stat (*xp_stat)(); /* get transport status */
138 bool_t (*xp_getargs)(); /* get arguments */
139 bool_t (*xp_reply)(); /* send reply */
140 bool_t (*xp_freeargs)(); /* free mem allocated for args */
141 void (*xp_destroy)(); /* destroy this struct */
142 } *xp_ops;
143 int xp_addrlen; /* length of remote addr. Obsolete */
144 struct sockaddr_in xp_raddr; /* Obsolete */
145 const struct xp_ops2 {
146 bool_t (*xp_control)(); /* catch-all function */
147 } *xp_ops2;
148 char *xp_tp; /* transport provider device name */
149 char *xp_netid; /* network identifier */
150 struct netbuf xp_ltaddr; /* local transport address */
151 struct netbuf xp_rtaddr; /* remote transport address */
152 struct opaque_auth xp_verf; /* raw response verifier */
153 caddr_t xp_p1; /* private: for use by svc ops */
154 caddr_t xp_p2; /* private: for use by svc ops */
155 caddr_t xp_p3; /* private: for use by svc lib */
156 int xp_type /* transport type */
157 } SVCXPRT;
158
160 struct svc_req {
161 rpcprog_t rq_prog; /* service program number */
162 rpcvers_t rq_vers; /* service protocol version */
163 rpcproc_t rq_proc; /* the desired procedure */
164 struct opaque_auth rq_cred; /* raw creds from the wire */
165 caddr_t rq_clntcred; /* read only cooked cred */
166 SVCXPRT *rq_xprt; /* associated transport */
167 };
168
170 /*
171 * XDR operations.
172 * XDR_ENCODE causes the type to be encoded into the stream.
173 * XDR_DECODE causes the type to be extracted from the stream.
174 * XDR_FREE can be used to release the space allocated by an XDR_DECODE
175 * request.
176 */
177 enum xdr_op {
178 XDR_ENCODE=0,
179 XDR_DECODE=1,
180 XDR_FREE=2
181 };
182 /*
183 * This is the number of bytes per unit of external data.
184 */
185 #define BYTES_PER_XDR_UNIT (4)
186 #define RNDUP(x) ((((x) + BYTES_PER_XDR_UNIT - 1) /
187 BYTES_PER_XDR_UNIT) \ * BYTES_PER_XDR_UNIT)
188 /*
190 * A xdrproc_t exists for each data type which is to be encoded or
191 * decoded. The second argument to the xdrproc_t is a pointer to
192 * an opaque pointer. The opaque pointer generally points to a
193 * structure of the data type to be decoded. If this points to 0,
194 * then the type routines should allocate dynamic storage of the
195 * appropriate size and return it.
196 * bool_t (*xdrproc_t)(XDR *, caddr_t *);
197 */
198 typedef bool_t (*xdrproc_t)();
199 /*
201 * The XDR handle.
202 * Contains operation which is being applied to the stream,
203 * an operations vector for the particular implementation
204 */
205 typedef struct {
206 enum xdr_op x_op; /* operation; fast additional param */
207 struct xdr_ops {
208 bool_t (*x_getlong)(); /* get a long from underlying stream */
209 bool_t (*x_putlong)(); /* put a long to underlying stream */
210 bool_t (*x_getbytes)(); /* get bytes from underlying stream */
211 bool_t (*x_putbytes)(); /* put bytes to underlying stream */
212 u_int (*x_getpostn)(); /* returns bytes off from beginning */
213 bool_t (*x_setpostn)(); /* lets you reposition the stream */
214 long * (*x_inline)(); /* buf quick ptr to buffered data */
215 void (*x_destroy)(); /* free privates of this xdr_stream */
216 } *x_ops;
217 caddr_t x_public; /* users' data */
218 caddr_t x_private; /* pointer to private data */
219 caddr_t x_base; /* private used for position info */
220 u_int x_handy; /* extra private word */
221 } XDR;
222 /*
224 * The netbuf structure. This structure is defined in <xti.h> on SysV
225 * systems, but NetBSD / FreeBSD do not use XTI.
226 *
227 * Usually, buf will point to a struct sockaddr, and len and maxlen
228 * will contain the length and maximum length of that socket address,
229 * respectively.
230 */
231 struct netbuf {
232 unsigned int maxlen;
233 unsigned int len;
234 void *buf;
235 };
236 /*
238 * The format of the address and options arguments of the XTI t_bind call.
239 * Only provided for compatibility, it should not be used other than
240 * as an argument to svc_tli_create().
241 */
242 struct t_bind {
244 struct netbuf addr;
245 unsigned int qlen;
246 };
247
249 The following table lists RPC routines and the manual reference pages on
250 which they are described:
251 RPC Routine Manual Reference Page
253 auth_destroy() rpc_clnt_auth(3)
255 authdes_create() rpc_soc(3)
256 authnone_create() rpc_clnt_auth(3)
257 authsys_create() rpc_clnt_auth(3)
258 authsys_create_default() rpc_clnt_auth(3)
259 authunix_create() rpc_soc(3)
260 authunix_create_default() rpc_soc(3)
261 callrpc() rpc_soc(3)
262 clnt_broadcast() rpc_soc(3)
263 clnt_call() rpc_clnt_calls(3)
264 clnt_control() rpc_clnt_create(3)
265 clnt_create() rpc_clnt_create(3)
266 clnt_create_timed() rpc_clnt_create(3)
267 clnt_create_vers() rpc_clnt_create(3)
268 clnt_create_vers_timed() rpc_clnt_create(3)
269 clnt_destroy() rpc_clnt_create(3)
270 clnt_dg_create() rpc_clnt_create(3)
271 clnt_freeres() rpc_clnt_calls(3)
272 clnt_geterr() rpc_clnt_calls(3)
273 clnt_pcreateerror() rpc_clnt_create(3)
274 clnt_perrno() rpc_clnt_calls(3)
275 clnt_perror() rpc_clnt_calls(3)
276 clnt_raw_create() rpc_clnt_create(3)
277 clnt_spcreateerror() rpc_clnt_create(3)
278 clnt_sperrno() rpc_clnt_calls(3)
279 clnt_sperror() rpc_clnt_calls(3)
280 clnt_tli_create() rpc_clnt_create(3)
281 clnt_tp_create() rpc_clnt_create(3)
282 clnt_tp_create_timed() rpc_clnt_create(3)
283 clnt_udpcreate() rpc_soc(3)
284 clnt_vc_create() rpc_clnt_create(3)
285 clntraw_create() rpc_soc(3)
286 clnttcp_create() rpc_soc(3)
287 clntudp_bufcreate() rpc_soc(3)
288 get_myaddress() rpc_soc(3)
289 pmap_getmaps() rpc_soc(3)
290 pmap_getport() rpc_soc(3)
291 pmap_rmtcall() rpc_soc(3)
292 pmap_set() rpc_soc(3)
293 pmap_unset() rpc_soc(3)
294 registerrpc() rpc_soc(3)
295 rpc_broadcast() rpc_clnt_calls(3)
296 rpc_broadcast_exp() rpc_clnt_calls(3)
297 rpc_call() rpc_clnt_calls(3)
298 rpc_reg() rpc_svc_calls(3)
299 svc_create() rpc_svc_create(3)
300 svc_destroy() rpc_svc_create(3)
301 svc_dg_create() rpc_svc_create(3)
302 svc_dg_enablecache() rpc_svc_calls(3)
303 svc_fd_create() rpc_svc_create(3)
304 svc_fds() rpc_soc(3)
305 svc_freeargs() rpc_svc_reg(3)
306 svc_getargs() rpc_svc_reg(3)
307 svc_getcaller() rpc_soc(3)
308 svc_getreq() rpc_soc(3)
309 svc_getreqset() rpc_svc_calls(3)
310 svc_getrpccaller() rpc_svc_calls(3)
311 svc_kerb_reg() kerberos_rpc(3)
312 svc_raw_create() rpc_svc_create(3)
313 svc_reg() rpc_svc_calls(3)
314 svc_register() rpc_soc(3)
315 svc_run() rpc_svc_reg(3)
316 svc_sendreply() rpc_svc_reg(3)
317 svc_tli_create() rpc_svc_create(3)
318 svc_tp_create() rpc_svc_create(3)
319 svc_unreg() rpc_svc_calls(3)
320 svc_unregister() rpc_soc(3)
321 svc_vc_create() rpc_svc_create(3)
322 svcerr_auth() rpc_svc_err(3)
323 svcerr_decode() rpc_svc_err(3)
324 svcerr_noproc() rpc_svc_err(3)
325 svcerr_noprog() rpc_svc_err(3)
326 svcerr_progvers() rpc_svc_err(3)
327 svcerr_systemerr() rpc_svc_err(3)
328 svcerr_weakauth() rpc_svc_err(3)
329 svcfd_create() rpc_soc(3)
330 svcraw_create() rpc_soc(3)
331 svctcp_create() rpc_soc(3)
332 svcudp_bufcreate() rpc_soc(3)
333 svcudp_create() rpc_soc(3)
334 xdr_accepted_reply() rpc_xdr(3)
335 xdr_authsys_parms() rpc_xdr(3)
336 xdr_authunix_parms() rpc_soc(3)
337 xdr_callhdr() rpc_xdr(3)
338 xdr_callmsg() rpc_xdr(3)
339 xdr_opaque_auth() rpc_xdr(3)
340 xdr_rejected_reply() rpc_xdr(3)
341 xdr_replymsg() rpc_xdr(3)
342 xprt_register() rpc_svc_calls(3)
343 xprt_unregister() rpc_svc_calls(3)
344
346 /etc/netconfig
347
349 getnetconfig(3), getnetpath(3), rpcbind(3), rpc_clnt_auth(3),
350 rpc_clnt_calls(3), rpc_clnt_create(3), rpc_svc_calls(3),
351 rpc_svc_create(3), rpc_svc_err(3), rpc_svc_reg(3), rpc_xdr(3), xdr(3),
352 netconfig(5)
353BSD May 7, 1993 BSD