1RPC(3)                   BSD Library Functions Manual                   RPC(3)
2

NAME

4     rpc — library routines for remote procedure calls
5

LIBRARY

7     Standard C Library (libc, -lc)
8

SYNOPSIS

10     #include <rpc/rpc.h>
11     #include <netconfig.h>
12

DESCRIPTION

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
19     All RPC routines require the header <rpc/rpc.h>.  Routines that take a
20     struct netconfig also require that <netconfig.h> be included.
21

Nettype

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
28     The nettype argument can be one of the following:
29
30     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
35     visible     Choose the transports which have the visible flag (v) set in
36                 the /etc/netconfig file.
37
38     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
42     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
46     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
50     datagram_n  This is same as "netpath" except that it chooses only the
51                 connectionless datagram transports (semantics "tpi_clts").
52
53     udp         This refers to Internet UDP, both version 4 and 6.
54
55     tcp         This refers to Internet TCP, both version 4 and 6.
56
57     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

Derived Types

62     The derived types used in the RPC interfaces are defined as follows:
63
64             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

Data Structures

72     Some of the data structures used by the RPC package are shown below.
73

The AUTH Structure

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
84     /*
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

The CLIENT Structure

101     /*
102      * Client rpc handle.
103      * Created by individual implementations.
104      * Client is responsible for initializing auth.
105      */
106
107     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

The SVCXPRT structure

123     enum xprt_stat {
124         XPRT_DIED,
125         XPRT_MOREREQS,
126         XPRT_IDLE
127     };
128
129     /*
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

The svc_reg structure

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

The XDR structure

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
189     /*
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
200     /*
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
223     /*
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
237     /*
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
243     struct t_bind {
244             struct netbuf   addr;
245             unsigned int    qlen;
246     };
247

Index to Routines

249     The following table lists RPC routines and the manual reference pages on
250     which they are described:
251
252     RPC Routine                Manual Reference Page
253
254     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

FILES

346     /etc/netconfig
347

SEE ALSO

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)
353
354BSD                               May 7, 1993                              BSD
Impressum