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