Debian Codegraph @

upstream/debian-unstable/man3/rpc.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" %%%LICENSE_START(BSD_ONELINE_CDROM)
5 .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
6 .\" %%%LICENSE_END
7 .\"
8 .TH rpc 3 2025-09-21 "Linux man-pages 6.18"
9 .SH NAME
10 rpc \- library routines for remote procedure calls
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS AND DESCRIPTION
15 These routines allow C programs to make procedure
16 calls on other machines across the network.
17 First, the client calls a procedure to send a data packet to the server.
18 Upon receipt of the packet, the server calls a dispatch routine
19 to perform the requested service, and then sends back a reply.
20 Finally, the procedure call returns to the client.
21 .\" .P
22 .\" We don't have an rpc_secure.3 page at the moment -- MTK, 19 Sep 05
23 .\" Routines that are used for Secure RPC (DES authentication) are described in
24 .\" .BR rpc_secure (3).
25 .\" Secure RPC can be used only if DES encryption is available.
26 .P
27 To take use of these routines, include the header file
28 .IR "<rpc/rpc.h>" .
29 .P
30 The prototypes below make use of the following types:
31 .P
32 .RS 4
33 .EX
34 .BI "typedef int " bool_t ;
35 .P
36 .BI "typedef typeof(bool_t (XDR *, void *, ...)) *" xdrproc_t ;
37 .P
38 .BI "typedef typeof(bool_t (caddr_t " resp ", struct sockaddr_in *" raddr )
39 .BI " *" resultproc_t ;
40 .EE
41 .RE
42 .P
43 See the header files for the declarations of the
44 .IR AUTH ,
45 .IR CLIENT ,
46 .IR SVCXPRT ,
47 and
48 .I XDR
49 types.
50 .P
51 .nf
52 .BI "void auth_destroy(AUTH *" auth );
53 .fi
54 .IP
55 A macro that destroys the authentication information associated with
56 .IR auth .
57 Destruction usually involves deallocation of private data structures.
58 The use of
59 .I auth
60 is undefined after calling
61 .BR auth_destroy ().
62 .P
63 .nf
64 .B AUTH *authnone_create(void);
65 .fi
66 .IP
67 Create and return an RPC
68 authentication handle that passes nonusable authentication
69 information with each remote procedure call.
70 This is the default authentication used by RPC.
71 .P
72 .nf
73 .BI "AUTH *authunix_create(char *" host ", uid_t " uid ", gid_t " gid ,
74 .BI " int " n ", gid_t " aup_gids [ n ]);
75 .fi
76 .IP
77 Create and return an RPC authentication handle that contains
78 authentication information.
79 The parameter
80 .I host
81 is the name of the machine on which the information was created;
82 .I uid
83 is the user's user ID;
84 .I gid
85 is the user's current group ID;
86 .I n
87 and
88 .I aup_gids
89 refer to a counted array of groups to which the user belongs.
90 It is easy to impersonate a user.
91 .P
92 .nf
93 .B AUTH *authunix_create_default(void);
94 .fi
95 .IP
96 Calls
97 .BR authunix_create ()
98 with the appropriate parameters.
99 .P
100 .nf
101 .BI "int callrpc(char *" host ", unsigned long " prognum ,
102 .BI " unsigned long " versnum ", unsigned long " procnum ,
103 .BI " xdrproc_t " inproc ", const char *" in ,
104 .BI " xdrproc_t " outproc ", char *" out );
105 .fi
106 .IP
107 Call the remote procedure associated with
108 .IR prognum ,
109 .IR versnum ,
110 and
111 .I procnum
112 on the machine,
113 .IR host .
114 The parameter
115 .I in
116 is the address of the procedure's argument(s), and
117 .I out
118 is the address of where to place the result(s);
119 .I inproc
120 is used to encode the procedure's parameters, and
121 .I outproc
122 is used to decode the procedure's results.
123 This routine returns zero if it succeeds, or the value of
124 .B "enum clnt_stat"
125 cast to an integer if it fails.
126 The routine
127 .BR clnt_perrno ()
128 is handy for translating failure statuses into messages.
129 .IP
130 Warning:
131 calling remote procedures with this routine
132 uses UDP/IP as a transport;
133 see
134 .BR clntudp_create ()
135 for restrictions.
136 You do not have control of timeouts or authentication using this routine.
137 .P
138 .nf
139 .BI "enum clnt_stat clnt_broadcast(unsigned long " prognum ,
140 .BI " unsigned long " versnum ", unsigned long " procnum ,
141 .BI " xdrproc_t " inproc ", char *" in ,
142 .BI " xdrproc_t " outproc ", char *" out ,
143 .BI " resultproc_t " eachresult );
144 .fi
145 .IP
146 Like
147 .BR callrpc (),
148 except the call message is broadcast to all locally
149 connected broadcast nets.
150 Each time it receives a response, this routine calls
151 .BR eachresult (),
152 whose form is:
153 .IP
154 .in +4n
155 .EX
156 .BI "eachresult(char *" out ", struct sockaddr_in *" addr );
157 .EE
158 .in
159 .IP
160 where
161 .I out
162 is the same as
163 .I out
164 passed to
165 .BR clnt_broadcast (),
166 except that the remote procedure's output is decoded there;
167 .I addr
168 points to the address of the machine that sent the results.
169 If
170 .BR eachresult ()
171 returns zero,
172 .BR clnt_broadcast ()
173 waits for more replies;
174 otherwise it returns with appropriate status.
175 .IP
176 Warning:
177 broadcast sockets are limited in size to the
178 maximum transfer unit of the data link.
179 For ethernet,
180 this value is 1500 bytes.
181 .P
182 .nf
183 .BI "enum clnt_stat clnt_call(CLIENT *" clnt ", unsigned long " procnum ,
184 .BI " xdrproc_t " inproc ", char *" in ,
185 .BI " xdrproc_t " outproc ", char *" out ,
186 .BI " struct timeval " tout );
187 .fi
188 .IP
189 A macro that calls the remote procedure
190 .I procnum
191 associated with the client handle,
192 .IR clnt ,
193 which is obtained with an RPC client creation routine such as
194 .BR clnt_create ().
195 The parameter
196 .I in
197 is the address of the procedure's argument(s), and
198 .I out
199 is the address of where to place the result(s);
200 .I inproc
201 is used to encode the procedure's parameters, and
202 .I outproc
203 is used to decode the procedure's results;
204 .I tout
205 is the time allowed for results to come back.
206 .P
207 .nf
208 .BI "clnt_destroy(CLIENT *" clnt );
209 .fi
210 .IP
211 A macro that destroys the client's RPC handle.
212 Destruction usually involves deallocation
213 of private data structures, including
214 .I clnt
215 itself.
216 Use of
217 .I clnt
218 is undefined after calling
219 .BR clnt_destroy ().
220 If the RPC library opened the associated socket, it will close it also.
221 Otherwise, the socket remains open.
222 .P
223 .nf
224 .BI "CLIENT *clnt_create(const char *" host ", unsigned long " prog ,
225 .BI " unsigned long " vers ", const char *" proto );
226 .fi
227 .IP
228 Generic client creation routine.
229 .I host
230 identifies the name of the remote host where the server is located.
231 .I proto
232 indicates which kind of transport protocol to use.
233 The currently supported values for this field are \[lq]udp\[rq]
234 and \[lq]tcp\[rq].
235 Default timeouts are set, but can be modified using
236 .BR clnt_control ().
237 .IP
238 Warning:
239 using UDP has its shortcomings.
240 Since UDP-based RPC messages can hold only up to 8 Kbytes of encoded data,
241 this transport cannot be used for
242 procedures that take large arguments or return huge results.
243 .P
244 .nf
245 .BI "bool_t clnt_control(CLIENT *" cl ", int " req ", char *" info );
246 .fi
247 .IP
248 A macro used to change or retrieve various information
249 about a client object.
250 .I req
251 indicates the type of operation, and
252 .I info
253 is a pointer to the information.
254 For both UDP and TCP, the supported values of
255 .I req
256 and their argument types and what they do are:
257 .IP
258 .in +4n
259 .EX
260 \f[B]CLSET_TIMEOUT\f[] \f[I]struct timeval\f[] // set total timeout
261 \f[B]CLGET_TIMEOUT\f[] \f[I]struct timeval\f[] // get total timeout
262 .EE
263 .in
264 .IP
265 Note: if you set the timeout using
266 .BR clnt_control (),
267 the timeout parameter passed to
268 .BR clnt_call ()
269 will be ignored in all future calls.
270 .IP
271 .in +4n
272 .EX
273 \f[B]CLGET_SERVER_ADDR\f[] \f[I]struct sockaddr_in\f[]
274 // get server\[aq]s address
275 .EE
276 .in
277 .IP
278 The following operations are valid for UDP only:
279 .IP
280 .in +4n
281 .EX
282 \f[B]CLSET_RETRY_TIMEOUT\f[] \f[I]struct timeval\f[] // set the retry timeout
283 \f[B]CLGET_RETRY_TIMEOUT\f[] \f[I]struct timeval\f[] // get the retry timeout
284 .EE
285 .in
286 .IP
287 The retry timeout is the time that "UDP RPC"
288 waits for the server to reply before
289 retransmitting the request.
290 .P
291 .nf
292 .BI "clnt_freeres(CLIENT * " clnt ", xdrproc_t " outproc ", char *" out );
293 .fi
294 .IP
295 A macro that frees any data allocated by the RPC/XDR
296 system when it decoded the results of an RPC call.
297 The parameter
298 .I out
299 is the address of the results, and
300 .I outproc
301 is the XDR routine describing the results.
302 This routine returns one if the results were successfully freed,
303 and zero otherwise.
304 .P
305 .nf
306 .BI "void clnt_geterr(CLIENT *" clnt ", struct rpc_err *" errp );
307 .fi
308 .IP
309 A macro that copies the error structure out of the client
310 handle to the structure at address
311 .IR errp .
312 .P
313 .nf
314 .BI "void clnt_pcreateerror(const char *" s );
315 .fi
316 .IP
317 Print a message to standard error indicating why a client RPC
318 handle could not be created.
319 The message is prepended with string
320 .I s
321 and a colon.
322 Used when a
323 .BR clnt_create (),
324 .BR clntraw_create (),
325 .BR clnttcp_create (),
326 or
327 .BR clntudp_create ()
328 call fails.
329 .P
330 .nf
331 .BI "void clnt_perrno(enum clnt_stat " stat );
332 .fi
333 .IP
334 Print a message to standard error corresponding
335 to the condition indicated by
336 .IR stat .
337 Used after
338 .BR callrpc ().
339 .P
340 .nf
341 .BI "clnt_perror(CLIENT *" clnt ", const char *" s );
342 .fi
343 .IP
344 Print a message to standard error indicating why an RPC call failed;
345 .I clnt
346 is the handle used to do the call.
347 The message is prepended with string
348 .I s
349 and a colon.
350 Used after
351 .BR clnt_call ().
352 .P
353 .nf
354 .BI "char *clnt_spcreateerror(const char *" s );
355 .fi
356 .IP
357 Like
358 .BR clnt_pcreateerror (),
359 except that it returns a string instead of printing to the standard error.
360 .IP
361 Bugs: returns pointer to static data that is overwritten on each call.
362 .P
363 .nf
364 .BI "char *clnt_sperrno(enum clnt_stat " stat );
365 .fi
366 .IP
367 Take the same arguments as
368 .BR clnt_perrno (),
369 but instead of sending a message to the standard error indicating why an RPC
370 call failed, return a pointer to a string which contains the message.
371 The string ends with a NEWLINE.
372 .IP
373 .BR clnt_sperrno ()
374 is used instead of
375 .BR clnt_perrno ()
376 if the program does not have a standard error (as a program
377 running as a server quite likely does not), or if the programmer
378 does not want the message to be output with
379 .BR printf (3),
380 or if a message format different than that supported by
381 .BR clnt_perrno ()
382 is to be used.
383 Note: unlike
384 .BR clnt_sperror ()
385 and
386 .BR clnt_spcreateerror (),
387 .BR clnt_sperrno ()
388 returns pointer to static data, but the
389 result will not get overwritten on each call.
390 .P
391 .nf
392 .BI "char *clnt_sperror(CLIENT *" rpch ", const char *" s );
393 .fi
394 .IP
395 Like
396 .BR clnt_perror (),
397 except that (like
398 .BR clnt_sperrno ())
399 it returns a string instead of printing to standard error.
400 .IP
401 Bugs: returns pointer to static data that is overwritten on each call.
402 .P
403 .nf
404 .BI "CLIENT *clntraw_create(unsigned long " prognum \
405 ", unsigned long " versnum );
406 .fi
407 .IP
408 This routine creates a toy RPC client for the remote program
409 .IR prognum ,
410 version
411 .IR versnum .
412 The transport used to pass messages to the service
413 is actually a buffer within the process's address space,
414 so the corresponding RPC server
415 should live in the same address space;
416 see
417 .BR svcraw_create ().
418 This allows simulation of RPC and acquisition of RPC overheads,
419 such as round trip times,
420 without any kernel interference.
421 This routine returns NULL if it fails.
422 .P
423 .nf
424 .BI "CLIENT *clnttcp_create(struct sockaddr_in *" addr ,
425 .BI " unsigned long " prognum ", unsigned long " versnum ,
426 .BI " int *" sockp ", unsigned int " sendsz \
427 ", unsigned int " recvsz );
428 .fi
429 .IP
430 This routine creates an RPC client for the remote program
431 .IR prognum ,
432 version
433 .IR versnum ;
434 the client uses TCP/IP as a transport.
435 The remote program is located at Internet address
436 .IR *addr .
437 If
438 .\"The following inline font conversion is necessary for the hyphen indicator
439 .I addr\->sin_port
440 is zero, then it is set to the actual port that the remote
441 program is listening on (the remote
442 .B portmap
443 service is consulted for this information).
444 The parameter
445 .I sockp
446 is a socket;
447 if it is
448 .BR RPC_ANYSOCK ,
449 then this routine opens a new one and sets
450 .IR sockp .
451 Since TCP-based RPC uses buffered I/O,
452 the user may specify the size of the send and receive buffers
453 with the parameters
454 .I sendsz
455 and
456 .IR recvsz ;
457 values of zero choose suitable defaults.
458 This routine returns NULL if it fails.
459 .P
460 .nf
461 .BI "CLIENT *clntudp_create(struct sockaddr_in *" addr ,
462 .BI " unsigned long " prognum ", unsigned long " versnum ,
463 .BI " struct timeval " wait ", int *" sockp );
464 .fi
465 .IP
466 This routine creates an RPC client for the remote program
467 .IR prognum ,
468 version
469 .IR versnum ;
470 the client uses use UDP/IP as a transport.
471 The remote program is located at Internet address
472 .IR addr .
473 If
474 .I addr\->sin_port
475 is zero, then it is set to actual port that the remote
476 program is listening on (the remote
477 .B portmap
478 service is consulted for this information).
479 The parameter
480 .I sockp
481 is a socket;
482 if it is
483 .BR RPC_ANYSOCK ,
484 then this routine opens a new one and sets
485 .IR sockp .
486 The UDP transport resends the call message in intervals of
487 .I wait
488 time until a response is received or until the call times out.
489 The total time for the call to time out is specified by
490 .BR clnt_call ().
491 .IP
492 Warning:
493 since UDP-based RPC messages can hold only
494 up to 8 Kbytes of encoded data,
495 this transport cannot be used for
496 procedures that take large arguments or return huge results.
497 .P
498 .nf
499 .BI "CLIENT *clntudp_bufcreate(struct sockaddr_in *" addr ,
500 .BI " unsigned long " prognum ", unsigned long " versnum ,
501 .BI " struct timeval " wait ", int *" sockp ,
502 .BI " unsigned int " sendsize ", unsigned int "recosize );
503 .fi
504 .IP
505 This routine creates an RPC client for the remote program
506 .IR prognum ,
507 on
508 .IR versnum ;
509 the client uses use UDP/IP as a transport.
510 The remote program is located at Internet address
511 .IR addr .
512 If
513 .I addr\->sin_port
514 is zero, then it is set to actual port that the remote
515 program is listening on (the remote
516 .B portmap
517 service is consulted for this information).
518 The parameter
519 .I sockp
520 is a socket;
521 if it is
522 .BR RPC_ANYSOCK ,
523 then this routine opens a new one and sets
524 .IR sockp .
525 The UDP transport resends the call message in intervals of
526 .I wait
527 time until a response is received or until the call times out.
528 The total time for the call to time out is specified by
529 .BR clnt_call ().
530 .IP
531 This allows the user to specify the maximum packet
532 size for sending and receiving UDP-based RPC messages.
533 .P
534 .nf
535 .BI "void get_myaddress(struct sockaddr_in *" addr );
536 .fi
537 .IP
538 Stuff the machine's IP address into
539 .IR *addr ,
540 without consulting the library routines that deal with
541 .IR /etc/hosts .
542 The port number is always set to
543 .BR htons(PMAPPORT) .
544 .P
545 .nf
546 .BI "struct pmaplist *pmap_getmaps(struct sockaddr_in *" addr );
547 .fi
548 .IP
549 A user interface to the
550 .B portmap
551 service, which returns a list of the current RPC
552 program-to-port mappings on the host located at IP address
553 .IR *addr .
554 This routine can return NULL.
555 The command
556 .I rpcinfo\~\-p
557 uses this routine.
558 .P
559 .nf
560 .BI "unsigned short pmap_getport(struct sockaddr_in *" addr ,
561 .BI " unsigned long " prognum ", unsigned long " versnum ,
562 .BI " unsigned int " protocol );
563 .fi
564 .IP
565 A user interface to the
566 .B portmap
567 service, which returns the port number
568 on which waits a service that supports program number
569 .IR prognum ,
570 version
571 .IR versnum ,
572 and speaks the transport protocol associated with
573 .IR protocol .
574 The value of
575 .I protocol
576 is most likely
577 .B IPPROTO_UDP
578 or
579 .BR IPPROTO_TCP .
580 A return value of zero means that the mapping does not exist
581 or that the RPC system failed to contact the remote
582 .B portmap
583 service.
584 In the latter case, the global variable
585 .I rpc_createerr
586 contains the RPC status.
587 .P
588 .nf
589 .BI "enum clnt_stat pmap_rmtcall(struct sockaddr_in *" addr ,
590 .BI " unsigned long " prognum ", unsigned long " versnum ,
591 .BI " unsigned long " procnum ,
592 .BI " xdrproc_t " inproc ", char *" in ,
593 .BI " xdrproc_t " outproc ", char *" out ,
594 .BI " struct timeval " tout ", unsigned long *" portp );
595 .fi
596 .IP
597 A user interface to the
598 .B portmap
599 service, which instructs
600 .B portmap
601 on the host at IP address
602 .I *addr
603 to make an RPC call on your behalf to a procedure on that host.
604 The parameter
605 .I *portp
606 will be modified to the program's port number if the procedure succeeds.
607 The definitions of other parameters are discussed
608 in
609 .BR callrpc ()
610 and
611 .BR clnt_call ().
612 This procedure should be used for a \[lq]ping\[rq] and nothing else.
613 See also
614 .BR clnt_broadcast ().
615 .P
616 .nf
617 .BI "bool_t pmap_set(unsigned long " prognum ", unsigned long " versnum ,
618 .BI " int " protocol ", unsigned short " port );
619 .fi
620 .IP
621 A user interface to the
622 .B portmap
623 service, which establishes a mapping between the triple
624 .RI [ prognum , versnum , protocol ]
625 and
626 .I port
627 on the machine's
628 .B portmap
629 service.
630 The value of
631 .I protocol
632 is most likely
633 .B IPPROTO_UDP
634 or
635 .BR IPPROTO_TCP .
636 This routine returns one if it succeeds, zero otherwise.
637 Automatically done by
638 .BR svc_register ().
639 .P
640 .nf
641 .BI "bool_t pmap_unset(unsigned long " prognum ", unsigned long " versnum );
642 .fi
643 .IP
644 A user interface to the
645 .B portmap
646 service, which destroys all mapping between the triple
647 .RI [ prognum , versnum , * ]
648 and
649 .B ports
650 on the machine's
651 .B portmap
652 service.
653 This routine returns one if it succeeds, zero otherwise.
654 .P
655 .nf
656 .BI "int registerrpc(unsigned long " prognum ", unsigned long " versnum ,
657 .BI " unsigned long " procnum ", typeof(char *(char *)) *" procname ,
658 .BI " xdrproc_t " inproc ", xdrproc_t " outproc );
659 .fi
660 .IP
661 Register procedure
662 .I procname
663 with the RPC service package.
664 If a request arrives for program
665 .IR prognum ,
666 version
667 .IR versnum ,
668 and procedure
669 .IR procnum ,
670 .I procname
671 is called with a pointer to its parameter(s);
672 .I procname
673 should return a pointer to its static result(s);
674 .I inproc
675 is used to decode the parameters while
676 .I outproc
677 is used to encode the results.
678 This routine returns zero if the registration succeeded, \-1 otherwise.
679 .IP
680 Warning:
681 remote procedures registered in this form
682 are accessed using the UDP/IP transport;
683 see
684 .BR svcudp_create ()
685 for restrictions.
686 .P
687 .nf
688 .BI "struct rpc_createerr " rpc_createerr ;
689 .fi
690 .IP
691 A global variable whose value is set by any RPC client creation routine
692 that does not succeed.
693 Use the routine
694 .BR clnt_pcreateerror ()
695 to print the reason why.
696 .P
697 .nf
698 .BI "void svc_destroy(SVCXPRT *" xprt );
699 .fi
700 .IP
701 A macro that destroys the RPC service transport handle,
702 .IR xprt .
703 Destruction usually involves deallocation
704 of private data structures, including
705 .I xprt
706 itself.
707 Use of
708 .I xprt
709 is undefined after calling this routine.
710 .P
711 .nf
712 .BI "fd_set " svc_fdset ;
713 .fi
714 .IP
715 A global variable reflecting the RPC service side's
716 read file descriptor bit mask;
717 it is suitable as a parameter to the
718 .BR select (2)
719 system call.
720 This is of interest
721 only if a service implementor does their own
722 asynchronous event processing,
723 instead of calling
724 .BR svc_run ().
725 This variable is read-only
726 (do not pass its address to
727 .BR select (2)!),
728 yet it may change after calls to
729 .BR svc_getreqset ()
730 or any creation routines.
731 .P
732 .nf
733 .BI "int " svc_fds ;
734 .fi
735 .IP
736 Similar to
737 .BR svc_fdset ,
738 but limited to 32 file descriptors.
739 This interface is obsoleted by
740 .BR svc_fdset .
741 .P
742 .nf
743 .BI "svc_freeargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in );
744 .fi
745 .IP
746 A macro that frees any data allocated by the RPC/XDR
747 system when it decoded the arguments to a service procedure using
748 .BR svc_getargs ().
749 This routine returns 1 if the results were successfully freed,
750 and zero otherwise.
751 .P
752 .nf
753 .BI "svc_getargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in );
754 .fi
755 .IP
756 A macro that decodes the arguments of an RPC request
757 associated with the RPC service transport handle,
758 .IR xprt .
759 The parameter
760 .I in
761 is the address where the arguments will be placed;
762 .I inproc
763 is the XDR routine used to decode the arguments.
764 This routine returns one if decoding succeeds, and zero otherwise.
765 .P
766 .nf
767 .BI "struct sockaddr_in *svc_getcaller(SVCXPRT *" xprt );
768 .fi
769 .IP
770 The approved way of getting the network address of the caller
771 of a procedure associated with the RPC service transport handle,
772 .IR xprt .
773 .P
774 .nf
775 .BI "void svc_getreqset(fd_set *" rdfds );
776 .fi
777 .IP
778 This routine is of interest only if a service implementor does not call
779 .BR svc_run (),
780 but instead implements custom asynchronous event processing.
781 It is called when the
782 .BR select (2)
783 system call has determined that an RPC request has arrived on some
784 RPC socket(s);
785 .I rdfds
786 is the resultant read file descriptor bit mask.
787 The routine returns when all sockets associated with the value of
788 .I rdfds
789 have been serviced.
790 .P
791 .nf
792 .BI "void svc_getreq(int " rdfds );
793 .fi
794 .IP
795 Similar to
796 .BR svc_getreqset (),
797 but limited to 32 file descriptors.
798 This interface is obsoleted by
799 .BR svc_getreqset ().
800 .P
801 .nf
802 .BI "bool_t svc_register(SVCXPRT *" xprt ", unsigned long " prognum ,
803 .BI " unsigned long " versnum ,
804 .BI " typeof(void (struct svc_req *, SVCXPRT *)) *" dispatch ,
805 .BI " unsigned long " protocol );
806 .fi
807 .IP
808 Associates
809 .I prognum
810 and
811 .I versnum
812 with the service dispatch procedure,
813 .IR dispatch .
814 If
815 .I protocol
816 is zero, the service is not registered with the
817 .B portmap
818 service.
819 If
820 .I protocol
821 is nonzero, then a mapping of the triple
822 .RI [ prognum , versnum , protocol ]
823 to
824 .I xprt\->xp_port
825 is established with the local
826 .B portmap
827 service (generally
828 .I protocol
829 is zero,
830 .B IPPROTO_UDP
831 or
832 .BR IPPROTO_TCP ).
833 The procedure
834 .I dispatch
835 has the following form:
836 .IP
837 .in +4n
838 .EX
839 dispatch(struct svc_req *request, SVCXPRT *xprt);
840 .EE
841 .in
842 .IP
843 The
844 .BR svc_register ()
845 routine returns one if it succeeds, and zero otherwise.
846 .P
847 .nf
848 .B "void svc_run(void);"
849 .fi
850 .IP
851 This routine never returns.
852 It waits for RPC requests to arrive, and calls the appropriate service
853 procedure using
854 .BR svc_getreq ()
855 when one arrives.
856 This procedure is usually waiting for a
857 .BR select (2)
858 system call to return.
859 .P
860 .nf
861 .BI "bool_t svc_sendreply(SVCXPRT *" xprt ", xdrproc_t " outproc \
862 ", char *" out );
863 .fi
864 .IP
865 Called by an RPC service's dispatch routine to send the results of a
866 remote procedure call.
867 The parameter
868 .I xprt
869 is the request's associated transport handle;
870 .I outproc
871 is the XDR routine which is used to encode the results;
872 and
873 .I out
874 is the address of the results.
875 This routine returns one if it succeeds, zero otherwise.
876 .P
877 .nf
878 .BI "void svc_unregister(unsigned long " prognum ", unsigned long " versnum );
879 .fi
880 .IP
881 Remove all mapping of the double
882 .RI [ prognum , versnum ]
883 to dispatch routines, and of the triple
884 .RI [ prognum , versnum , * ]
885 to port number.
886 .P
887 .nf
888 .BI "void svcerr_auth(SVCXPRT *" xprt ", enum auth_stat " why );
889 .fi
890 .IP
891 Called by a service dispatch routine that refuses to perform
892 a remote procedure call due to an authentication error.
893 .P
894 .nf
895 .BI "void svcerr_decode(SVCXPRT *" xprt );
896 .fi
897 .IP
898 Called by a service dispatch routine that cannot successfully
899 decode its parameters.
900 See also
901 .BR svc_getargs ().
902 .P
903 .nf
904 .BI "void svcerr_noproc(SVCXPRT *" xprt );
905 .fi
906 .IP
907 Called by a service dispatch routine that does not implement
908 the procedure number that the caller requests.
909 .P
910 .nf
911 .BI "void svcerr_noprog(SVCXPRT *" xprt );
912 .fi
913 .IP
914 Called when the desired program is not registered with the RPC package.
915 Service implementors usually do not need this routine.
916 .P
917 .nf
918 .BI "void svcerr_progvers(SVCXPRT *" xprt ", unsigned long " low_vers ,
919 .BI " unsigned long " high_vers );
920 .fi
921 .IP
922 Called when the desired version of a program is not registered
923 with the RPC package.
924 Service implementors usually do not need this routine.
925 .P
926 .nf
927 .BI "void svcerr_systemerr(SVCXPRT *" xprt );
928 .fi
929 .IP
930 Called by a service dispatch routine when it detects a system
931 error not covered by any particular protocol.
932 For example, if a service can no longer allocate storage,
933 it may call this routine.
934 .P
935 .nf
936 .BI "void svcerr_weakauth(SVCXPRT *" xprt );
937 .fi
938 .IP
939 Called by a service dispatch routine that refuses to perform
940 a remote procedure call due to insufficient authentication parameters.
941 The routine calls
942 .BR "svcerr_auth(xprt, AUTH_TOOWEAK)" .
943 .P
944 .nf
945 .BI "SVCXPRT *svcfd_create(int " fd ", unsigned int " sendsize ,
946 .BI " unsigned int " recvsize );
947 .fi
948 .IP
949 Create a service on top of any open file descriptor.
950 Typically, this file descriptor is a connected socket for a stream protocol such
951 as TCP.
952 .I sendsize
953 and
954 .I recvsize
955 indicate sizes for the send and receive buffers.
956 If they are zero, a reasonable default is chosen.
957 .P
958 .nf
959 .B SVCXPRT *svcraw_create(void);
960 .fi
961 .IP
962 This routine creates a toy RPC
963 service transport, to which it returns a pointer.
964 The transport is really a buffer within the process's address space,
965 so the corresponding RPC client should live in the same address space;
966 see
967 .BR clntraw_create ().
968 This routine allows simulation of RPC and acquisition of RPC overheads
969 (such as round trip times),
970 without any kernel interference.
971 This routine returns NULL if it fails.
972 .P
973 .nf
974 .BI "SVCXPRT *svctcp_create(int " sock ", unsigned int " send_buf_size ,
975 .BI " unsigned int " recv_buf_size );
976 .fi
977 .IP
978 This routine creates a TCP/IP-based RPC
979 service transport, to which it returns a pointer.
980 The transport is associated with the socket
981 .IR sock ,
982 which may be
983 .BR RPC_ANYSOCK ,
984 in which case a new socket is created.
985 If the socket is not bound to a local TCP port,
986 then this routine binds it to an arbitrary port.
987 Upon completion,
988 .I xprt\->xp_sock
989 is the transport's socket descriptor,
990 and
991 .I xprt\->xp_port
992 is the transport's port number.
993 This routine returns NULL if it fails.
994 Since TCP-based RPC uses buffered I/O,
995 users may specify the size of buffers;
996 values of zero
997 choose suitable defaults.
998 .P
999 .nf
1000 .BI "SVCXPRT *svcudp_bufcreate(int " sock ", unsigned int " sendsize ,
1001 .BI " unsigned int " recosize );
1002 .fi
1003 .IP
1004 This routine creates a UDP/IP-based RPC
1005 service transport, to which it returns a pointer.
1006 The transport is associated with the socket
1007 .IR sock ,
1008 which may be
1009 .BR RPC_ANYSOCK ,
1010 in which case a new socket is created.
1011 If the socket is not bound to a local UDP
1012 port, then this routine binds it to an arbitrary port.
1013 Upon completion,
1014 .I xprt\->xp_sock
1015 is the transport's socket descriptor, and
1016 .I xprt\->xp_port
1017 is the transport's port number.
1018 This routine returns NULL if it fails.
1019 .IP
1020 This allows the user to specify the maximum packet size for sending and
1021 receiving UDP-based RPC messages.
1022 .P
1023 .nf
1024 .BI "SVCXPRT *svcudp_create(int " sock );
1025 .fi
1026 .IP
1027 This call is equivalent to
1028 .I svcudp_bufcreate(sock,SZ,SZ)
1029 for some default size
1030 .IR SZ .
1031 .P
1032 .nf
1033 .BI "bool_t xdr_accepted_reply(XDR *" xdrs ", struct accepted_reply *" ar );
1034 .fi
1035 .IP
1036 Used for encoding RPC reply messages.
1037 This routine is useful for users who wish to generate
1038 RPC-style messages without using the RPC package.
1039 .P
1040 .nf
1041 .BI "bool_t xdr_authunix_parms(XDR *" xdrs ", struct authunix_parms *" aupp );
1042 .fi
1043 .IP
1044 Used for describing UNIX credentials.
1045 This routine is useful for users
1046 who wish to generate these credentials without using the RPC
1047 authentication package.
1048 .P
1049 .nf
1050 .BI "void xdr_callhdr(XDR *" xdrs ", struct rpc_msg *" chdr );
1051 .fi
1052 .IP
1053 Used for describing RPC call header messages.
1054 This routine is useful for users who wish to generate
1055 RPC-style messages without using the RPC package.
1056 .P
1057 .nf
1058 .BI "bool_t xdr_callmsg(XDR *" xdrs ", struct rpc_msg *" cmsg );
1059 .fi
1060 .IP
1061 Used for describing RPC call messages.
1062 This routine is useful for users who wish to generate RPC-style
1063 messages without using the RPC package.
1064 .P
1065 .nf
1066 .BI "bool_t xdr_opaque_auth(XDR *" xdrs ", struct opaque_auth *" ap );
1067 .fi
1068 .IP
1069 Used for describing RPC authentication information messages.
1070 This routine is useful for users who wish to generate
1071 RPC-style messages without using the RPC package.
1072 .P
1073 .nf
1074 .BI "bool_t xdr_pmap(XDR *" xdrs ", struct pmap *" regs );
1075 .fi
1076 .IP
1077 Used for describing parameters to various
1078 .B portmap
1079 procedures, externally.
1080 This routine is useful for users who wish to generate
1081 these parameters without using the
1082 .B pmap
1083 interface.
1084 .P
1085 .nf
1086 .BI "bool_t xdr_pmaplist(XDR *" xdrs ", struct pmaplist **" rp );
1087 .fi
1088 .IP
1089 Used for describing a list of port mappings, externally.
1090 This routine is useful for users who wish to generate
1091 these parameters without using the
1092 .B pmap
1093 interface.
1094 .P
1095 .nf
1096 .BI "bool_t xdr_rejected_reply(XDR *" xdrs ", struct rejected_reply *" rr );
1097 .fi
1098 .IP
1099 Used for describing RPC reply messages.
1100 This routine is useful for users who wish to generate
1101 RPC-style messages without using the RPC package.
1102 .P
1103 .nf
1104 .BI "bool_t xdr_replymsg(XDR *" xdrs ", struct rpc_msg *" rmsg );
1105 .fi
1106 .IP
1107 Used for describing RPC reply messages.
1108 This routine is useful for users who wish to generate
1109 RPC style messages without using the RPC package.
1110 .P
1111 .nf
1112 .BI "void xprt_register(SVCXPRT *" xprt );
1113 .fi
1114 .IP
1115 After RPC service transport handles are created,
1116 they should register themselves with the RPC service package.
1117 This routine modifies the global variable
1118 .IR svc_fds .
1119 Service implementors usually do not need this routine.
1120 .P
1121 .nf
1122 .BI "void xprt_unregister(SVCXPRT *" xprt );
1123 .fi
1124 .IP
1125 Before an RPC service transport handle is destroyed,
1126 it should unregister itself with the RPC service package.
1127 This routine modifies the global variable
1128 .IR svc_fds .
1129 Service implementors usually do not need this routine.
1130 .SH ATTRIBUTES
1131 For an explanation of the terms used in this section, see
1132 .BR attributes (7).
1133 .TS
1134 allbox;
1135 lbx lb lb
1136 l l l.
1137 Interface Attribute Value
1138 T{
1139 .na
1140 .nh
1141 .BR auth_destroy (),
1142 .BR authnone_create (),
1143 .BR authunix_create (),
1144 .BR authunix_create_default (),
1145 .BR callrpc (),
1146 .BR clnt_broadcast (),
1147 .BR clnt_call (),
1148 .BR clnt_destroy (),
1149 .BR clnt_create (),
1150 .BR clnt_control (),
1151 .BR clnt_freeres (),
1152 .BR clnt_geterr (),
1153 .BR clnt_pcreateerror (),
1154 .BR clnt_perrno (),
1155 .BR clnt_perror (),
1156 .BR clnt_spcreateerror (),
1157 .BR clnt_sperrno (),
1158 .BR clnt_sperror (),
1159 .BR clntraw_create (),
1160 .BR clnttcp_create (),
1161 .BR clntudp_create (),
1162 .BR clntudp_bufcreate (),
1163 .BR get_myaddress (),
1164 .BR pmap_getmaps (),
1165 .BR pmap_getport (),
1166 .BR pmap_rmtcall (),
1167 .BR pmap_set (),
1168 .BR pmap_unset (),
1169 .BR registerrpc (),
1170 .BR svc_destroy (),
1171 .BR svc_freeargs (),
1172 .BR svc_getargs (),
1173 .BR svc_getcaller (),
1174 .BR svc_getreqset (),
1175 .BR svc_getreq (),
1176 .BR svc_register (),
1177 .BR svc_run (),
1178 .BR svc_sendreply (),
1179 .BR svc_unregister (),
1180 .BR svcerr_auth (),
1181 .BR svcerr_decode (),
1182 .BR svcerr_noproc (),
1183 .BR svcerr_noprog (),
1184 .BR svcerr_progvers (),
1185 .BR svcerr_systemerr (),
1186 .BR svcerr_weakauth (),
1187 .BR svcfd_create (),
1188 .BR svcraw_create (),
1189 .BR svctcp_create (),
1190 .BR svcudp_bufcreate (),
1191 .BR svcudp_create (),
1192 .BR xdr_accepted_reply (),
1193 .BR xdr_authunix_parms (),
1194 .BR xdr_callhdr (),
1195 .BR xdr_callmsg (),
1196 .BR xdr_opaque_auth (),
1197 .BR xdr_pmap (),
1198 .BR xdr_pmaplist (),
1199 .BR xdr_rejected_reply (),
1200 .BR xdr_replymsg (),
1201 .BR xprt_register (),
1202 .BR xprt_unregister ()
1203 T} Thread safety MT-Safe
1204 .TE
1205 .SH SEE ALSO
1206 .\" We don't have an rpc_secure.3 page in the set at the moment -- MTK, 19 Sep 05
1207 .\" .BR rpc_secure (3),
1208 .BR xdr (3)
1209 .P
1210 The following manuals:
1211 .RS
1212 Remote Procedure Calls: Protocol Specification
1213 .br
1214 Remote Procedure Call Programming Guide
1215 .br
1216 rpcgen Programming Guide
1217 .br
1218 .RE
1219 .P
1220 .IR "RPC: Remote Procedure Call Protocol Specification" ,
1221 RFC\ 1050, Sun Microsystems, Inc.,
1222 USC-ISI.