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

NAME

4     rpc — library routines for remote procedure calls
5

SYNOPSIS

7     #include <rpc/rpc.h>
8     #include <netconfig.h>
9

DESCRIPTION

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

Nettype

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
25     The nettype argument can be one of the following:
26
27     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
32     visible     Choose the transports which have the visible flag (v) set in
33                 the /etc/netconfig file.
34
35     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
39     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
43     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
47     datagram_n  This is same as "netpath" except that it chooses only the
48                 connectionless datagram transports (semantics "tpi_clts").
49
50     udp         This refers to Internet UDP, both version 4 and 6.
51
52     tcp         This refers to Internet TCP, both version 4 and 6.
53
54     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

Derived Types

59     The derived types used in the RPC interfaces are defined as follows:
60
61             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

Data Structures

69     Some of the data structures used by the RPC package are shown below.
70

The AUTH Structure

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

The CLIENT Structure

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

The SVCXPRT structure

120     enum xprt_stat {
121         XPRT_DIED,
122         XPRT_MOREREQS,
123         XPRT_IDLE
124     };
125
126     /*
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

The svc_reg structure

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

The XDR structure

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
186     /*
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
197     /*
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
220     /*
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
234     /*
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
240     struct t_bind {
241             struct netbuf   addr;
242             unsigned int    qlen;
243     };
244

Index to Routines

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

FILES

343     /etc/netconfig
344

AVAILABILITY

346     These functions are part of libtirpc.
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