1RPC(3) Linux Programmer's Manual RPC(3)
2
6 rpc - library routines for remote procedure calls
7
9 These routines allow C programs to make procedure calls on other
10 machines across the network. First, the client calls a procedure to
11 send a data packet to the server. Upon receipt of the packet, the
12 server calls a dispatch routine to perform the requested service, and
13 then sends back a reply. Finally, the procedure call returns to the
14 client.
15 To take use of these routines, include the header file <rpc/rpc.h>.
17 The prototypes below make use of the following types:
19 typedef int bool_t;
21 typedef bool_t (*xdrproc_t) (XDR *, void *,...);
23 typedef bool_t (*resultproc_t) (caddr_t resp,
25 struct sockaddr_in *raddr);
26 See the header files for the declarations of the AUTH, CLIENT, SVCXPRT,
28 and XDR types.
29 void auth_destroy(AUTH *auth);
31 A macro that destroys the authentication information associated
33 with auth. Destruction usually involves deallocation of private
34 data structures. The use of auth is undefined after calling
35 auth_destroy().
36 AUTH *authnone_create(void);
38 Create and return an RPC authentication handle that passes
40 nonusable authentication information with each remote procedure
41 call. This is the default authentication used by RPC.
42 AUTH *authunix_create(char *host, int uid, int gid,
44 int len, int *aup_gids);
45 Create and return an RPC authentication handle that contains
47 authentication information. The parameter host is the name of
48 the machine on which the information was created; uid is the
49 user's user ID; gid is the user's current group ID; len and
50 aup_gids refer to a counted array of groups to which the user
51 belongs. It is easy to impersonate a user.
52 AUTH *authunix_create_default(void);
54 Calls authunix_create() with the appropriate parameters.
56 int callrpc(char *host, unsigned long prognum,
58 unsigned long versnum, unsigned long procnum,
59 xdrproc_t inproc, char *in,
60 xdrproc_t outproc, char *out);
61 Call the remote procedure associated with prognum, versnum, and
63 procnum on the machine, host. The parameter in is the address
64 of the procedure's argument(s), and out is the address of where
65 to place the result(s); inproc is used to encode the procedure's
66 parameters, and outproc is used to decode the procedure's
67 results. This routine returns zero if it succeeds, or the value
68 of enum clnt_stat cast to an integer if it fails. The routine
69 clnt_perrno() is handy for translating failure statuses into
70 messages.
71 Warning: calling remote procedures with this routine uses UDP/IP
73 as a transport; see clntudp_create() for restrictions. You do
74 not have control of timeouts or authentication using this rou‐
75 tine.
76 enum clnt_stat clnt_broadcast(unsigned long prognum,
78 unsigned long versnum, unsigned long procnum,
79 xdrproc_t inproc, char *in,
80 xdrproc_t outproc, char *out,
81 resultproc_t eachresult);
82 Like callrpc(), except the call message is broadcast to all
84 locally connected broadcast nets. Each time it receives a
85 response, this routine calls eachresult(), whose form is:
86 eachresult(char *out, struct sockaddr_in *addr);
88 where out is the same as out passed to clnt_broadcast(), except
90 that the remote procedure's output is decoded there; addr points
91 to the address of the machine that sent the results. If eachre‐
92 sult() returns zero, clnt_broadcast() waits for more replies;
93 otherwise it returns with appropriate status.
94 Warning: broadcast sockets are limited in size to the maximum
96 transfer unit of the data link. For ethernet, this value is
97 1500 bytes.
98 enum clnt_stat clnt_call(CLIENT *clnt, unsigned long procnum,
100 xdrproc_t inproc, char *in,
101 xdrproc_t outproc, char *out,
102 struct timeval tout);
103 A macro that calls the remote procedure procnum associated with
105 the client handle, clnt, which is obtained with an RPC client
106 creation routine such as clnt_create(). The parameter in is the
107 address of the procedure's argument(s), and out is the address
108 of where to place the result(s); inproc is used to encode the
109 procedure's parameters, and outproc is used to decode the proce‐
110 dure's results; tout is the time allowed for results to come
111 back.
112 clnt_destroy(CLIENT *clnt);
114 A macro that destroys the client's RPC handle. Destruction usu‐
116 ally involves deallocation of private data structures, including
117 clnt itself. Use of clnt is undefined after calling
118 clnt_destroy(). If the RPC library opened the associated
119 socket, it will close it also. Otherwise, the socket remains
120 open.
121 CLIENT *clnt_create(char *host, unsigned long prog,
123 unsigned long vers, char *proto);
124 Generic client creation routine. host identifies the name of
126 the remote host where the server is located. proto indicates
127 which kind of transport protocol to use. The currently sup‐
128 ported values for this field are “udp” and “tcp”. Default time‐
129 outs are set, but can be modified using clnt_control().
130 Warning: Using UDP has its shortcomings. Since UDP-based RPC
132 messages can only hold up to 8 Kbytes of encoded data, this
133 transport cannot be used for procedures that take large argu‐
134 ments or return huge results.
135 bool_t clnt_control(CLIENT *cl, int req, char *info);
137 A macro used to change or retrieve various information about a
139 client object. req indicates the type of operation, and info is
140 a pointer to the information. For both UDP and TCP, the sup‐
141 ported values of req and their argument types and what they do
142 are:
143 CLSET_TIMEOUT struct timeval // set total timeout
145 CLGET_TIMEOUT struct timeval // get total timeout
146 Note: if you set the timeout using clnt_control(), the timeout
148 parameter passed to clnt_call() will be ignored in all future
149 calls.
150 CLGET_SERVER_ADDR struct sockaddr_in // get server's address
152 The following operations are valid for UDP only:
154 CLSET_RETRY_TIMEOUT struct timeval // set the retry timeout
156 CLGET_RETRY_TIMEOUT struct timeval // get the retry timeout
157 The retry timeout is the time that "UDP RPC" waits for the
159 server to reply before retransmitting the request.
160 clnt_freeres(CLIENT * clnt, xdrproc_t outproc, char *out);
162 A macro that frees any data allocated by the RPC/XDR system when
164 it decoded the results of an RPC call. The parameter out is the
165 address of the results, and outproc is the XDR routine describ‐
166 ing the results. This routine returns one if the results were
167 successfully freed, and zero otherwise.
168 void clnt_geterr(CLIENT *clnt, struct rpc_err *errp);
170 A macro that copies the error structure out of the client handle
172 to the structure at address errp.
173 void clnt_pcreateerror(char *s);
175 Print a message to standard error indicating why a client RPC
177 handle could not be created. The message is prepended with
178 string s and a colon. Used when a clnt_create(), clntraw_cre‐
179 ate(), clnttcp_create(), or clntudp_create() call fails.
180 void clnt_perrno(enum clnt_stat stat);
182 Print a message to standard error corresponding to the condition
184 indicated by stat. Used after callrpc().
185 clnt_perror(CLIENT *clnt, char *s);
187 Print a message to standard error indicating why an RPC call
189 failed; clnt is the handle used to do the call. The message is
190 prepended with string s and a colon. Used after clnt_call().
191 char *clnt_spcreateerror(char *s);
193 Like clnt_pcreateerror(), except that it returns a string
195 instead of printing to the standard error.
196 Bugs: returns pointer to static data that is overwritten on each
198 call.
199 char *clnt_sperrno(enum clnt_stat stat);
201 Take the same arguments as clnt_perrno(), but instead of sending
203 a message to the standard error indicating why an RPC call
204 failed, return a pointer to a string which contains the message.
205 The string ends with a NEWLINE.
206 clnt_sperrno() is used instead of clnt_perrno() if the program
208 does not have a standard error (as a program running as a server
209 quite likely does not), or if the programmer does not want the
210 message to be output with printf(3), or if a message format dif‐
211 ferent than that supported by clnt_perrno() is to be used.
212 Note: unlike clnt_sperror() and clnt_spcreaterror(), clnt_sper‐
213 rno() returns pointer to static data, but the result will not
214 get overwritten on each call.
215 char *clnt_sperror(CLIENT *rpch, char *s);
217 Like clnt_perror(), except that (like clnt_sperrno()) it returns
219 a string instead of printing to standard error.
220 Bugs: returns pointer to static data that is overwritten on each
222 call.
223 CLIENT *clntraw_create(unsigned long prognum, unsigned long versnum);
225 This routine creates a toy RPC client for the remote program
227 prognum, version versnum. The transport used to pass messages
228 to the service is actually a buffer within the process's address
229 space, so the corresponding RPC server should live in the same
230 address space; see svcraw_create(). This allows simulation of
231 RPC and acquisition of RPC overheads, such as round trip times,
232 without any kernel interference. This routine returns NULL if
233 it fails.
234 CLIENT *clnttcp_create(struct sockaddr_in *addr,
236 unsigned long prognum, unsigned long versnum,
237 int *sockp, unsigned int sendsz, unsigned int recvsz);
238 This routine creates an RPC client for the remote program
240 prognum, version versnum; the client uses TCP/IP as a transport.
241 The remote program is located at Internet address *addr. If
242 addr->sin_port is zero, then it is set to the actual port that
243 the remote program is listening on (the remote portmap service
244 is consulted for this information). The parameter sockp is a
245 socket; if it is RPC_ANYSOCK, then this routine opens a new one
246 and sets sockp. Since TCP-based RPC uses buffered I/O, the user
247 may specify the size of the send and receive buffers with the
248 parameters sendsz and recvsz; values of zero choose suitable
249 defaults. This routine returns NULL if it fails.
250 CLIENT *clntudp_create(struct sockaddr_in *addr,
252 unsigned long prognum, unsigned long versnum,
253 struct timeval wait, int *sockp);
254 This routine creates an RPC client for the remote program
256 prognum, version versnum; the client uses use UDP/IP as a trans‐
257 port. The remote program is located at Internet address addr.
258 If addr->sin_port is zero, then it is set to actual port that
259 the remote program is listening on (the remote portmap service
260 is consulted for this information). The parameter sockp is a
261 socket; if it is RPC_ANYSOCK, then this routine opens a new one
262 and sets sockp. The UDP transport resends the call message in
263 intervals of wait time until a response is received or until the
264 call times out. The total time for the call to time out is
265 specified by clnt_call().
266 Warning: since UDP-based RPC messages can only hold up to 8
268 Kbytes of encoded data, this transport cannot be used for proce‐
269 dures that take large arguments or return huge results.
270 CLIENT *clntudp_bufcreate(struct sockaddr_in *addr,
272 unsigned long prognum, unsigned long versnum,
273 struct timeval wait, int *sockp,
274 unsigned int sendsize, unsigned int recosize);
275 This routine creates an RPC client for the remote program
277 prognum, on versnum; the client uses use UDP/IP as a transport.
278 The remote program is located at Internet address addr. If
279 addr->sin_port is zero, then it is set to actual port that the
280 remote program is listening on (the remote portmap service is
281 consulted for this information). The parameter sockp is a
282 socket; if it is RPC_ANYSOCK, then this routine opens a new one
283 and sets sockp. The UDP transport resends the call message in
284 intervals of wait time until a response is received or until the
285 call times out. The total time for the call to time out is
286 specified by clnt_call().
287 This allows the user to specify the maximum packet size for
289 sending and receiving UDP-based RPC messages.
290 void get_myaddress(struct sockaddr_in *addr);
292 Stuff the machine's IP address into *addr, without consulting
294 the library routines that deal with /etc/hosts. The port number
295 is always set to htons(PMAPPORT).
296 struct pmaplist *pmap_getmaps(struct sockaddr_in *addr);
298 A user interface to the portmap service, which returns a list of
300 the current RPC program-to-port mappings on the host located at
301 IP address *addr. This routine can return NULL. The command
302 rpcinfo -p uses this routine.
303 unsigned short pmap_getport(struct sockaddr_in *addr,
305 unsigned long prognum, unsigned long versnum,
306 unsigned int protocol);
307 A user interface to the portmap service, which returns the port
309 number on which waits a service that supports program number
310 prognum, version versnum, and speaks the transport protocol
311 associated with protocol. The value of protocol is most likely
312 IPPROTO_UDP or IPPROTO_TCP. A return value of zero means that
313 the mapping does not exist or that the RPC system failed to con‐
314 tact the remote portmap service. In the latter case, the global
315 variable rpc_createerr contains the RPC status.
316 enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr,
318 unsigned long prognum, unsigned long versnum,
319 unsigned long procnum,
320 xdrproc_t inproc, char *in,
321 xdrproc_t outproc, char *out,
322 struct timeval tout, unsigned long *portp);
323 A user interface to the portmap service, which instructs portmap
325 on the host at IP address *addr to make an RPC call on your
326 behalf to a procedure on that host. The parameter *portp will
327 be modified to the program's port number if the procedure suc‐
328 ceeds. The definitions of other parameters are discussed in
329 callrpc() and clnt_call(). This procedure should be used for a
330 “ping” and nothing else. See also clnt_broadcast().
331 bool_t pmap_set(unsigned long prognum, unsigned long versnum,
333 unsigned int protocol, unsigned short port);
334 A user interface to the portmap service, which establishes a
336 mapping between the triple [prognum,versnum,protocol] and port
337 on the machine's portmap service. The value of protocol is most
338 likely IPPROTO_UDP or IPPROTO_TCP. This routine returns one if
339 it succeeds, zero otherwise. Automatically done by svc_regis‐
340 ter().
341 bool_t pmap_unset(unsigned long prognum, unsigned long versnum);
343 A user interface to the portmap service, which destroys all map‐
345 ping between the triple [prognum,versnum,*] and ports on the
346 machine's portmap service. This routine returns one if it suc‐
347 ceeds, zero otherwise.
348 int registerrpc(unsigned long prognum, unsigned long versnum,
350 unsigned long procnum, char *(*procname)(char *),
351 xdrproc_t inproc, xdrproc_t outproc);
352 Register procedure procname with the RPC service package. If a
354 request arrives for program prognum, version versnum, and proce‐
355 dure procnum, procname is called with a pointer to its parame‐
356 ter(s); progname should return a pointer to its static
357 result(s); inproc is used to decode the parameters while outproc
358 is used to encode the results. This routine returns zero if the
359 registration succeeded, -1 otherwise.
360 Warning: remote procedures registered in this form are accessed
362 using the UDP/IP transport; see svcudp_create() for restric‐
363 tions.
364 struct rpc_createerr rpc_createerr;
366 A global variable whose value is set by any RPC client creation
368 routine that does not succeed. Use the routine clnt_pcreateer‐
369 ror() to print the reason why.
370 void svc_destroy(SVCXPRT *xprt);
372 A macro that destroys the RPC service transport handle, xprt.
374 Destruction usually involves deallocation of private data struc‐
375 tures, including xprt itself. Use of xprt is undefined after
376 calling this routine.
377 fd_set svc_fdset;
379 A global variable reflecting the RPC service side's read file
381 descriptor bit mask; it is suitable as a parameter to the
382 select(2) system call. This is only of interest if a service
383 implementor does not call svc_run(), but rather does his own
384 asynchronous event processing. This variable is read-only (do
385 not pass its address to select(2)!), yet it may change after
386 calls to svc_getreqset() or any creation routines.
387 int svc_fds;
389 Similar to svc_fdset, but limited to 32 descriptors. This
391 interface is obsoleted by svc_fdset.
392 svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);
394 A macro that frees any data allocated by the RPC/XDR system when
396 it decoded the arguments to a service procedure using
397 svc_getargs(). This routine returns 1 if the results were suc‐
398 cessfully freed, and zero otherwise.
399 svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);
401 A macro that decodes the arguments of an RPC request associated
403 with the RPC service transport handle, xprt. The parameter in
404 is the address where the arguments will be placed; inproc is the
405 XDR routine used to decode the arguments. This routine returns
406 one if decoding succeeds, and zero otherwise.
407 struct sockaddr_in *svc_getcaller(SVCXPRT *xprt);
409 The approved way of getting the network address of the caller of
411 a procedure associated with the RPC service transport handle,
412 xprt.
413 void svc_getreqset(fd_set *rdfds);
415 This routine is only of interest if a service implementor does
417 not call svc_run(), but instead implements custom asynchronous
418 event processing. It is called when the select(2) system call
419 has determined that an RPC request has arrived on some RPC
420 socket(s); rdfds is the resultant read file descriptor bit mask.
421 The routine returns when all sockets associated with the value
422 of rdfds have been serviced.
423 void svc_getreq(int rdfds);
425 Similar to svc_getreqset(), but limited to 32 descriptors. This
427 interface is obsoleted by svc_getreqset().
428 bool_t svc_register(SVCXPRT *xprt, unsigned long prognum,
430 unsigned long versnum,
431 void (*dispatch)(svc_req *, SVCXPRT *),
432 unsigned long protocol);
433 Associates prognum and versnum with the service dispatch proce‐
435 dure, dispatch. If protocol is zero, the service is not regis‐
436 tered with the portmap service. If protocol is nonzero, then a
437 mapping of the triple [prognum,versnum,protocol] to
438 xprt->xp_port is established with the local portmap service
439 (generally protocol is zero, IPPROTO_UDP or IPPROTO_TCP). The
440 procedure dispatch has the following form:
441 dispatch(struct svc_req *request, SVCXPRT *xprt);
443 The svc_register() routine returns one if it succeeds, and zero
445 otherwise.
446 void svc_run(void);
448 This routine never returns. It waits for RPC requests to
450 arrive, and calls the appropriate service procedure using
451 svc_getreq() when one arrives. This procedure is usually wait‐
452 ing for a select(2) system call to return.
453 bool_t svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, char *out);
455 Called by an RPC service's dispatch routine to send the results
457 of a remote procedure call. The parameter xprt is the request's
458 associated transport handle; outproc is the XDR routine which is
459 used to encode the results; and out is the address of the
460 results. This routine returns one if it succeeds, zero other‐
461 wise.
462 void svc_unregister(unsigned long prognum, unsigned long versnum);
464 Remove all mapping of the double [prognum,versnum] to dispatch
466 routines, and of the triple [prognum,versnum,*] to port number.
467 void svcerr_auth(SVCXPRT *xprt, enum auth_stat why);
469 Called by a service dispatch routine that refuses to perform a
471 remote procedure call due to an authentication error.
472 void svcerr_decode(SVCXPRT *xprt);
474 Called by a service dispatch routine that cannot successfully
476 decode its parameters. See also svc_getargs().
477 void svcerr_noproc(SVCXPRT *xprt);
479 Called by a service dispatch routine that does not implement the
481 procedure number that the caller requests.
482 void svcerr_noprog(SVCXPRT *xprt);
484 Called when the desired program is not registered with the RPC
486 package. Service implementors usually do not need this routine.
487 void svcerr_progvers(SVCXPRT *xprt);
489 Called when the desired version of a program is not registered
491 with the RPC package. Service implementors usually do not need
492 this routine.
493 void svcerr_systemerr(SVCXPRT *xprt);
495 Called by a service dispatch routine when it detects a system
497 error not covered by any particular protocol. For example, if a
498 service can no longer allocate storage, it may call this rou‐
499 tine.
500 void svcerr_weakauth(SVCXPRT *xprt);
502 Called by a service dispatch routine that refuses to perform a
504 remote procedure call due to insufficient authentication parame‐
505 ters. The routine calls svcerr_auth(xprt, AUTH_TOOWEAK).
506 SVCXPRT *svcfd_create(int fd, unsigned int sendsize,
508 unsigned int recvsize);
509 Create a service on top of any open descriptor. Typically, this
511 descriptor is a connected socket for a stream protocol such as
512 TCP. sendsize and recvsize indicate sizes for the send and
513 receive buffers. If they are zero, a reasonable default is cho‐
514 sen.
515 SVCXPRT *svcraw_create(void);
517 This routine creates a toy RPC service transport, to which it
519 returns a pointer. The transport is really a buffer within the
520 process's address space, so the corresponding RPC client should
521 live in the same address space; see clntraw_create(). This rou‐
522 tine allows simulation of RPC and acquisition of RPC overheads
523 (such as round trip times), without any kernel interference.
524 This routine returns NULL if it fails.
525 SVCXPRT *svctcp_create(int sock, unsigned int send_buf_size,
527 unsigned int recv_buf_size);
528 This routine creates a TCP/IP-based RPC service transport, to
530 which it returns a pointer. The transport is associated with
531 the socket sock, which may be RPC_ANYSOCK, in which case a new
532 socket is created. If the socket is not bound to a local TCP
533 port, then this routine binds it to an arbitrary port. Upon
534 completion, xprt->xp_sock is the transport's socket descriptor,
535 and xprt->xp_port is the transport's port number. This routine
536 returns NULL if it fails. Since TCP-based RPC uses buffered
537 I/O, users may specify the size of buffers; values of zero
538 choose suitable defaults.
539 SVCXPRT *svcudp_bufcreate(int sock, unsigned int sendsize,
541 unsigned int recosize);
542 This routine creates a UDP/IP-based RPC service transport, to
544 which it returns a pointer. The transport is associated with
545 the socket sock, which may be RPC_ANYSOCK, in which case a new
546 socket is created. If the socket is not bound to a local UDP
547 port, then this routine binds it to an arbitrary port. Upon
548 completion, xprt->xp_sock is the transport's socket descriptor,
549 and xprt->xp_port is the transport's port number. This routine
550 returns NULL if it fails.
551 This allows the user to specify the maximum packet size for
553 sending and receiving UDP-based RPC messages.
554 SVCXPRT *svcudp_create(int sock);
556 This call is equivalent to svcudp_bufcreate(sock,SZ,SZ) for some
558 default size SZ.
559 bool_t xdr_accepted_reply(XDR *xdrs, struct accepted_reply *ar);
561 Used for encoding RPC reply messages. This routine is useful
563 for users who wish to generate RPC-style messages without using
564 the RPC package.
565 bool_t xdr_authunix_parms(XDR *xdrs, struct authunix_parms *aupp);
567 Used for describing Unix credentials. This routine is useful
569 for users who wish to generate these credentials without using
570 the RPC authentication package.
571 void xdr_callhdr(XDR *xdrs, struct rpc_msg *chdr);
573 Used for describing RPC call header messages. This routine is
575 useful for users who wish to generate RPC-style messages without
576 using the RPC package.
577 bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsg);
579 Used for describing RPC call messages. This routine is useful
581 for users who wish to generate RPC-style messages without using
582 the RPC package.
583 bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *ap);
585 Used for describing RPC authentication information messages.
587 This routine is useful for users who wish to generate RPC-style
588 messages without using the RPC package.
589 bool_t xdr_pmap(XDR *xdrs, struct pmap *regs);
591 Used for describing parameters to various portmap procedures,
593 externally. This routine is useful for users who wish to gener‐
594 ate these parameters without using the pmap interface.
595 bool_t xdr_pmaplist(XDR *xdrs, struct pmaplist **rp);
597 Used for describing a list of port mappings, externally. This
599 routine is useful for users who wish to generate these parame‐
600 ters without using the pmap interface.
601 bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply *rr);
603 Used for describing RPC reply messages. This routine is useful
605 for users who wish to generate RPC-style messages without using
606 the RPC package.
607 bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsg);
609 Used for describing RPC reply messages. This routine is useful
611 for users who wish to generate RPC style messages without using
612 the RPC package.
613 void xprt_register(SVCXPRT *xprt);
615 After RPC service transport handles are created, they should
617 register themselves with the RPC service package. This routine
618 modifies the global variable svc_fds. Service implementors usu‐
619 ally do not need this routine.
620 void xprt_unregister(SVCXPRT *xprt);
622 Before an RPC service transport handle is destroyed, it should
624 unregister itself with the RPC service package. This routine
625 modifies the global variable svc_fds. Service implementors usu‐
626 ally do not need this routine.
627
629 xdr(3)
630 The following manuals:
631 Remote Procedure Calls: Protocol Specification
632 Remote Procedure Call Programming Guide
633 rpcgen Programming Guide
634 RPC: Remote Procedure Call Protocol Specification, RFC 1050, Sun
635 Microsystems, Inc., USC-ISI.
636
638 This page is part of release 3.25 of the Linux man-pages project. A
639 description of the project, and information about reporting bugs, can
640 be found at http://www.kernel.org/doc/man-pages/.
641 2008-07-17 RPC(3)