Add PCICAP_{ID,NEXTPTR} to avoid using magic number
[dragonfly.git] / lib / libc / rpc / rpc.3
blob5450746dc1ab8c650b9bd330870ee27a785e56dc
1 .\" @(#)rpc.3n  2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI
2 .\" $FreeBSD: src/lib/libc/rpc/rpc.3,v 1.11.2.5 2001/12/14 18:33:56 ru Exp $
3 .\" $DragonFly: src/lib/libc/rpc/rpc.3,v 1.8 2008/05/01 22:06:06 swildner Exp $
4 .\"
5 .Dd February 16, 1988
6 .Dt RPC 3
7 .Os
8 .Sh NAME
9 .Nm rpc
10 .Nd "library routines for remote procedure calls"
11 .Sh LIBRARY
12 .Lb libc
13 .Sh SYNOPSIS
14 .In rpc/rpc.h
15 .Pp
16 See
17 .Sx DESCRIPTION
18 for function declarations.
19 .Sh DESCRIPTION
20 These routines allow C programs to make procedure
21 calls on other machines across the network.
22 First, the client calls a procedure to send a
23 data packet to the server.
24 Upon receipt of the packet, the server calls a dispatch routine
25 to perform the requested service, and then sends back a
26 reply.
27 Finally, the procedure call returns to the client.
28 .Pp
29 Routines that are used for Secure
30 .Tn RPC ( DES
31 authentication) are described in
32 .Xr rpc_secure 3 .
33 Secure
34 .Tn RPC
35 can be used only if
36 .Tn DES
37 encryption is available.
38 .Pp
39 .Bl -tag -width indent -compact
40 .It Xo
41 .Ft void
42 .Xc
43 .It Xo
44 .Fn auth_destroy "AUTH *auth"
45 .Xc
46 .Pp
47 A macro that destroys the authentication information associated with
48 .Fa auth .
49 Destruction usually involves deallocation of private data
50 structures.
51 The use of
52 .Fa auth
53 is undefined after calling
54 .Fn auth_destroy .
55 .Pp
56 .It Xo
57 .Ft "AUTH *"
58 .Xc
59 .It Xo
60 .Fn authnone_create
61 .Xc
62 .Pp
63 Create and return an
64 .Tn RPC
65 authentication handle that passes nonusable authentication
66 information with each remote procedure call.
67 This is the
68 default authentication used by
69 .Tn RPC .
70 .Pp
71 .It Xo
72 .Ft "AUTH *"
73 .Xc
74 .It Xo
75 .Fn authunix_create "char *host" "int uid" "int gid" "int len" "int *aup_gids"
76 .Xc
77 .Pp
78 Create and return an
79 .Tn RPC
80 authentication handle that contains
81 .Ux
82 authentication information.
83 The parameter
84 .Fa host
85 is the name of the machine on which the information was
86 created;
87 .Fa uid
88 is the user's user ID;
89 .Fa gid
90 is the user's current group ID;
91 .Fa len
92 and
93 .Fa aup_gids
94 refer to a counted array of groups to which the user belongs.
95 It is easy to impersonate a user.
96 .Pp
97 .It Xo
98 .Ft "AUTH *"
99 .Xc
100 .It Xo
101 .Fn authunix_create_default
104 Calls
105 .Fn authunix_create
106 with the appropriate parameters.
108 .It Xo
109 .Ft int
110 .Fo callrpc
111 .Fa "char *host"
112 .Fa "u_long prognum"
113 .Fa "u_long versnum"
114 .Fa "u_long procnum"
115 .Fa "xdrproc_t inproc"
116 .Fa "char *in"
117 .Fa "xdrproc_t outproc"
118 .Fa "char *out"
122 Call the remote procedure associated with
123 .Fa prognum ,
124 .Fa versnum ,
126 .Fa procnum
127 on the machine
128 .Fa host .
129 The parameter
130 .Fa in
131 is the address of the procedure's argument(s), and
132 .Fa out
133 is the address of where to place the result(s);
134 .Fa inproc
135 is used to encode the procedure's parameters, and
136 .Fa outproc
137 is used to decode the procedure's results.
138 This routine returns zero if it succeeds, or the value of
139 .Vt "enum clnt_stat"
140 cast to an integer if it fails.
141 The routine
142 .Fn clnt_perrno
143 is handy for translating failure statuses into messages.
145 Warning: calling remote procedures with this routine
146 uses
147 .Tn UDP/IP
148 as a transport; see
149 .Fn clntudp_create
150 for restrictions.
151 You do not have control of timeouts or authentication using
152 this routine.
154 .It Xo
155 .Ft "enum clnt_stat"
157 .It Xo
158 .Fo clnt_broadcast
159 .Fa "u_long prognum"
160 .Fa "u_long versnum"
161 .Fa "u_long procnum"
162 .Fa "xdrproc_t inproc"
163 .Fa "char *in"
164 .Fa "xdrproc_t outproc"
165 .Fa "char *out"
166 .Fa "bool_t (*eachresult)(caddr_t, struct sockaddr_in *)
170 Like
171 .Fn callrpc ,
172 except the call message is broadcast to all locally
173 connected broadcast nets.
174 Each time it receives a
175 response, this routine calls
176 .Fn eachresult ,
177 whose form is:
178 .Bd -ragged -offset indent
179 .Ft bool_t
180 .Fn eachresult "caddr_t out" "struct sockaddr_in *addr"
183 where
184 .Fa out
185 is the same as
186 .Fa out
187 passed to
188 .Fn clnt_broadcast ,
189 except that the remote procedure's output is decoded there;
190 .Fa addr
191 points to the address of the machine that sent the results.
193 .Fn eachresult
194 returns zero,
195 .Fn clnt_broadcast
196 waits for more replies; otherwise it returns with appropriate
197 status.
199 Warning: broadcast sockets are limited in size to the
200 maximum transfer unit of the data link.
201 For ethernet,
202 this value is 1500 bytes.
204 .It Xo
205 .Ft "enum clnt_stat"
207 .It Xo
208 .Fo clnt_call
209 .Fa "CLIENT *clnt"
210 .Fa "u_long procnum"
211 .Fa "xdrproc_t inproc"
212 .Fa "char *in"
213 .Fa "xdrproc_t outproc"
214 .Fa "char *out"
215 .Fa "struct timeval tout"
219 A macro that calls the remote procedure
220 .Fa procnum
221 associated with the client handle,
222 .Fa clnt ,
223 which is obtained with an
224 .Tn RPC
225 client creation routine such as
226 .Fn clnt_create .
227 The parameter
228 .Fa in
229 is the address of the procedure's argument(s), and
230 .Fa out
231 is the address of where to place the result(s);
232 .Fa inproc
233 is used to encode the procedure's parameters, and
234 .Fa outproc
235 is used to decode the procedure's results;
236 .Fa tout
237 is the time allowed for results to come back.
239 .It Xo
240 .Ft void
241 .Fn clnt_destroy "CLIENT *clnt"
244 A macro that destroys the client's
245 .Tn RPC
246 handle.
247 Destruction usually involves deallocation
248 of private data structures, including
249 .Fa clnt
250 itself.
251 Use of
252 .Fa clnt
253 is undefined after calling
254 .Fn clnt_destroy .
255 If the
256 .Tn RPC
257 library opened the associated socket, it will close it also.
258 Otherwise, the socket remains open.
260 .It Xo
261 .Ft CLIENT *
263 .It Xo
264 .Fn clnt_create "const char *host" "u_long prog" "u_long vers" "const char *proto"
267 Generic client creation routine.
268 .Fa host
269 identifies the name of the remote host where the server
270 is located.
271 .Fa proto
272 indicates which kind of transport protocol to use.
274 currently supported values for this field are
275 .Qq Li udp
277 .Qq Li tcp .
278 Default timeouts are set, but can be modified using
279 .Fn clnt_control .
281 Warning: Using
282 .Tn UDP
283 has its shortcomings.
284 Since
285 .Tn UDP Ns \-based
286 .Tn RPC
287 messages can only hold up to 8 Kbytes of encoded data,
288 this transport cannot be used for procedures that take
289 large arguments or return huge results.
291 .It Xo
292 .Ft bool_t
294 .It Xo
295 .Fn clnt_control "CLIENT *cl" "u_int req" "char *info"
298 A macro used to change or retrieve various information
299 about a client object.
300 .Fa req
301 indicates the type of operation, and
302 .Fa info
303 is a pointer to the information.
304 For both
305 .Tn UDP
307 .Tn TCP ,
308 the supported values of
309 .Fa req
310 and their argument types and what they do are:
311 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
312 .It Dv CLSET_TIMEOUT Ta Xo
313 .Vt "struct timeval" Ta "set total timeout"
315 .It Dv CLGET_TIMEOUT Ta Xo
316 .Vt "struct timeval" Ta "get total timeout"
320 Note: if you set the timeout using
321 .Fn clnt_control ,
322 the timeout parameter passed to
323 .Fn clnt_call
324 will be ignored in all future calls.
325 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
326 .It Dv CLGET_SERVER_ADDR Ta Xo
327 .Vt "struct sockaddr_in" Ta "get server's address"
331 The following operations are valid for
332 .Tn UDP
333 only:
334 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
335 .It Dv CLSET_RETRY_TIMEOUT Ta Xo
336 .Vt "struct timeval" Ta "set the retry timeout"
338 .It Dv CLGET_RETRY_TIMEOUT Ta Xo
339 .Vt "struct timeval" Ta "get the retry timeout"
341 .It Dv CLSET_CONNECT Ta Vt "int" Ta use Xr connect 2
344 The retry timeout is the time that
345 .Tn "UDP RPC"
346 waits for the server to reply before
347 retransmitting the request.
349 .It Xo
350 .Ft bool_t
351 .Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out"
354 A macro that frees any data allocated by the
355 .Tn RPC/XDR
356 system when it decoded the results of an
357 .Tn RPC
358 call.
359 The parameter
360 .Fa out
361 is the address of the results, and
362 .Fa outproc
363 is the
364 .Tn XDR
365 routine describing the results.
366 This routine returns one if the results were successfully
367 freed,
368 and zero otherwise.
370 .It Xo
371 .Ft void
373 .It Xo
374 .Fn clnt_geterr "CLIENT *clnt" "struct rpc_err *errp"
377 A macro that copies the error structure out of the client
378 handle
379 to the structure at address
380 .Fa errp .
382 .It Xo
383 .Ft void
385 .It Xo
386 .Fn clnt_pcreateerror "const char *s"
389 prints a message to standard error indicating
390 why a client
391 .Tn RPC
392 handle could not be created.
393 The message is prepended with string
394 .Fa s
395 and a colon.
396 Used when a
397 .Fn clnt_create ,
398 .Fn clntraw_create ,
399 .Fn clnttcp_create ,
401 .Fn clntudp_create
402 call fails.
404 .It Xo
405 .Ft void
407 .It Xo
408 .Fn clnt_perrno "enum clnt_stat stat"
411 Print a message to standard error corresponding
412 to the condition indicated by
413 .Fa stat .
414 Used after
415 .Fn callrpc .
417 .It Xo
418 .Ft void
419 .Fn clnt_perror "CLIENT *clnt" "const char *s"
422 Print a message to standard error indicating why an
423 .Tn RPC
424 call failed;
425 .Fa clnt
426 is the handle used to do the call.
427 The message is prepended with string
428 .Fa s
429 and a colon.
430 Used after
431 .Fn clnt_call .
433 .It Xo
434 .Ft "char *"
436 .It Xo
437 .Fn clnt_spcreateerror "const char *s"
440 Like
441 .Fn clnt_pcreateerror ,
442 except that it returns a string
443 instead of printing to the standard error.
445 Bugs: returns pointer to static data that is overwritten
446 on each call.
448 .It Xo
449 .Ft "char *"
451 .It Xo
452 .Fn clnt_sperrno "enum clnt_stat stat"
455 Take the same arguments as
456 .Fn clnt_perrno ,
457 but instead of sending a message to the standard error
458 indicating why an
459 .Tn RPC
460 call failed, return a pointer to a string which contains
461 the message.
462 The string ends with a newline
463 .Pq Ql "\en" .
465 .Fn clnt_sperrno
466 is used instead of
467 .Fn clnt_perrno
468 if the program does not have a standard error (as a program
469 running as a server quite likely does not), or if the
470 programmer
471 does not want the message to be output with
472 .Fn printf ,
473 or if a message format different from that supported by
474 .Fn clnt_perrno
475 is to be used.
477 Note: unlike
478 .Fn clnt_sperror
480 .Fn clnt_spcreateerror ,
481 .Fn clnt_sperrno
482 returns pointer to static data, but the
483 result will not get overwritten on each call.
485 .It Xo
486 .Ft "char *"
488 .It Xo
489 .Fn clnt_sperror "CLIENT *rpch" "const char *s"
492 Like
493 .Fn clnt_perror ,
494 except that (like
495 .Fn clnt_sperrno )
496 it returns a string instead of printing to standard error.
498 Bugs: returns pointer to static data that is overwritten
499 on each call.
501 .It Xo
502 .Ft "CLIENT *"
504 .It Xo
505 .Fn clntraw_create "u_long prognum" "u_long versnum"
508 This routine creates a toy
509 .Tn RPC
510 client for the remote program
511 .Fa prognum ,
512 version
513 .Fa versnum .
514 The transport used to pass messages to the service is
515 actually a buffer within the process's address space, so the
516 corresponding
517 .Tn RPC
518 server should live in the same address space; see
519 .Fn svcraw_create .
520 This allows simulation of
521 .Tn RPC
522 and acquisition of
523 .Tn RPC
524 overheads, such as round trip times, without any
525 kernel interference.
526 This routine returns
527 .Dv NULL
528 if it fails.
530 .It Xo
531 .Ft "CLIENT *"
533 .It Xo
534 .Fo clnttcp_create
535 .Fa "struct sockaddr_in *addr"
536 .Fa "u_long prognum"
537 .Fa "u_long versnum"
538 .Fa "int *sockp"
539 .Fa "u_int sendsz"
540 .Fa "u_int recvsz"
544 This routine creates an
545 .Tn RPC
546 client for the remote program
547 .Fa prognum ,
548 version
549 .Fa versnum ;
550 the client uses
551 .Tn TCP/IP
552 as a transport.
553 The remote program is located at Internet
554 address
555 .Fa addr .
557 .Fa addr\->sin_port
558 is zero, then it is set to the actual port that the remote
559 program is listening on (the remote
560 .Xr portmap 8
561 service is consulted for this information).
562 The parameter
563 .Fa sockp
564 is a socket; if it is
565 .Dv RPC_ANYSOCK ,
566 then this routine opens a new one and sets
567 .Fa sockp .
568 Since
569 .Tn TCP Ns \-based
570 .Tn RPC
571 uses buffered
572 .Tn I/O ,
573 the user may specify the size of the send and receive buffers
574 with the parameters
575 .Fa sendsz
577 .Fa recvsz ;
578 values of zero choose suitable defaults.
579 This routine returns
580 .Dv NULL
581 if it fails.
583 .It Xo
584 .Ft "CLIENT *"
586 .It Xo
587 .Fo clntudp_create
588 .Fa "struct sockaddr_in *addr"
589 .Fa "u_long prognum"
590 .Fa "u_long versnum"
591 .Fa "struct timeval wait"
592 .Fa "int *sockp"
596 This routine creates an
597 .Tn RPC
598 client for the remote program
599 .Fa prognum ,
600 version
601 .Fa versnum ;
602 the client uses
603 .Tn UDP/IP
604 as a transport.
605 The remote program is located at Internet
606 address
607 .Fa addr .
609 .Fa addr\->sin_port
610 is zero, then it is set to actual port that the remote
611 program is listening on (the remote
612 .Xr portmap 8
613 service is consulted for this information).
614 The parameter
615 .Fa sockp
616 is a socket; if it is
617 .Dv RPC_ANYSOCK ,
618 then this routine opens a new one and sets
619 .Fa sockp .
621 .Tn UDP
622 transport resends the call message in intervals of
623 .Fa wait
624 time until a response is received or until the call times
625 out.
626 The total time for the call to time out is specified by
627 .Fn clnt_call .
629 Warning: since
630 .Tn UDP Ns \-based
631 .Tn RPC
632 messages can only hold up to 8 Kbytes
633 of encoded data, this transport cannot be used for procedures
634 that take large arguments or return huge results.
636 .It Xo
637 .Ft "CLIENT *"
639 .It Xo
640 .Fo clntudp_bufcreate
641 .Fa "struct sockaddr_in *addr"
642 .Fa "u_long prognum"
643 .Fa "u_long versnum"
644 .Fa "struct timeval wait"
645 .Fa "int *sockp"
646 .Fa "unsigned int sendsize"
647 .Fa "unsigned int recosize"
651 This routine creates an
652 .Tn RPC
653 client for the remote program
654 .Fa prognum ,
656 .Fa versnum ;
657 the client uses
658 .Tn UDP/IP
659 as a transport.
660 The remote program is located at Internet
661 address
662 .Fa addr .
664 .Fa addr\->sin_port
665 is zero, then it is set to actual port that the remote
666 program is listening on (the remote
667 .Xr portmap 8
668 service is consulted for this information).
669 The parameter
670 .Fa sockp
671 is a socket; if it is
672 .Dv RPC_ANYSOCK ,
673 then this routine opens a new one and sets
674 .Fa sockp .
676 .Tn UDP
677 transport resends the call message in intervals of
678 .Fa wait
679 time until a response is received or until the call times
680 out.
681 The total time for the call to time out is specified by
682 .Fn clnt_call .
684 This allows the user to specify the maximum packet size
685 for sending and receiving
686 .Tn UDP Ns \-based
687 .Tn RPC
688 messages.
690 .It Xo
691 .Ft int
693 .It Xo
694 .Fn get_myaddress "struct sockaddr_in *addr"
697 Stuff the machine's
698 .Tn IP
699 address into
700 .Fa addr ,
701 without consulting the library routines that deal with
702 .Pa /etc/hosts .
703 The port number is always set to
704 .Fn htons PMAPPORT .
705 Returns zero on success, non-zero on failure.
707 .It Xo
708 .Ft "struct pmaplist *"
710 .It Xo
711 .Fn pmap_getmaps "struct sockaddr_in *addr"
714 A user interface to the
715 .Xr portmap 8
716 service, which returns a list of the current
717 .Tn RPC
718 program\-to\-port mappings
719 on the host located at
720 .Tn IP
721 address
722 .Fa addr .
723 This routine can return
724 .Dv NULL .
725 The command
726 .Dq Nm rpcinfo Fl p
727 uses this routine.
729 .It Xo
730 .Ft u_short
732 .It Xo
733 .Fo pmap_getport
734 .Fa "struct sockaddr_in *addr"
735 .Fa "u_long prognum"
736 .Fa "u_long versnum"
737 .Fa "u_long protocol"
741 A user interface to the
742 .Xr portmap 8
743 service, which returns the port number
744 on which waits a service that supports program number
745 .Fa prognum ,
746 version
747 .Fa versnum ,
748 and speaks the transport protocol associated with
749 .Fa protocol .
750 The value of
751 .Fa protocol
752 is most likely
753 .Dv IPPROTO_UDP
755 .Dv IPPROTO_TCP .
756 A return value of zero means that the mapping does not exist
757 or that
759 .Tn RPC
760 system failed to contact the remote
761 .Xr portmap 8
762 service.
763 In the latter case, the global variable
764 .Va rpc_createerr
765 contains the
766 .Tn RPC
767 status.
769 .It Xo
770 .Ft "enum clnt_stat"
772 .It Xo
773 .Fo pmap_rmtcall
774 .Fa "struct sockaddr_in *addr"
775 .Fa "u_long prognum"
776 .Fa "u_long versnum"
777 .Fa "u_long procnum"
778 .Fa "xdrproc_t inproc"
779 .Fa "char *in"
780 .Fa "xdrproc_t outproc"
781 .Fa "char *out"
782 .Fa "struct timeval tout"
783 .Fa "u_long *portp"
787 A user interface to the
788 .Xr portmap 8
789 service, which instructs
790 .Xr portmap 8
791 on the host at
792 .Tn IP
793 address
794 .Fa addr
795 to make an
796 .Tn RPC
797 call on your behalf to a procedure on that host.
798 The parameter
799 .Fa portp
800 will be modified to the program's port number if the
801 procedure
802 succeeds.
803 The definitions of other parameters are discussed
805 .Fn callrpc
807 .Fn clnt_call .
808 This procedure should be used for a
809 .Dq ping
810 and nothing
811 else.
812 See also
813 .Fn clnt_broadcast .
815 .It Xo
816 .Ft bool_t
817 .Fn pmap_set "u_long prognum" "u_long versnum" "u_long protocol" "u_short port"
820 A user interface to the
821 .Xr portmap 8
822 service, which establishes a mapping between the triple
823 .Pq Fa prognum , versnum , protocol
825 .Fa port
826 on the machine's
827 .Xr portmap 8
828 service.
829 The value of
830 .Fa protocol
831 is most likely
832 .Dv IPPROTO_UDP
834 .Dv IPPROTO_TCP .
835 This routine returns one if it succeeds, zero otherwise.
836 Automatically done by
837 .Fn svc_register .
839 .It Xo
840 .Ft bool_t
841 .Fn pmap_unset "u_long prognum" "u_long versnum"
844 A user interface to the
845 .Xr portmap 8
846 service, which destroys all mapping between the triple
847 .Pq Fa prognum , versnum , *
849 .Fa ports
850 on the machine's
851 .Xr portmap 8
852 service.
853 This routine returns one if it succeeds, zero
854 otherwise.
856 .It Xo
857 .Ft bool_t
858 .Fo registerrpc
859 .Fa "u_long prognum"
860 .Fa "u_long versnum"
861 .Fa "u_long procnum"
862 .Fa "char *(*procname)(void)"
863 .Fa "xdrproc_t inproc"
864 .Fa "xdrproc_t outproc"
868 Register procedure
869 .Fa procname
870 with the
871 .Tn RPC
872 service package.
873 If a request arrives for program
874 .Fa prognum ,
875 version
876 .Fa versnum ,
877 and procedure
878 .Fa procnum ,
879 .Fa procname
880 is called with a pointer to its parameter(s);
881 .Fa progname
882 should return a pointer to its static result(s);
883 .Fa inproc
884 is used to decode the parameters while
885 .Fa outproc
886 is used to encode the results.
887 This routine returns zero if the registration succeeded, \-1
888 otherwise.
890 Warning: remote procedures registered in this form
891 are accessed using the
892 .Tn UDP/IP
893 transport; see
894 .Fn svcudp_create
895 for restrictions.
897 .It Xo
898 .Vt "struct rpc_createerr" rpc_createerr ;
901 A global variable whose value is set by any
902 .Tn RPC
903 client creation routine
904 that does not succeed.
905 Use the routine
906 .Fn clnt_pcreateerror
907 to print the reason why.
909 .It Xo
910 .Ft bool_t
911 .Fn svc_destroy "SVCXPRT * xprt"
914 A macro that destroys the
915 .Tn RPC
916 service transport handle,
917 .Fa xprt .
918 Destruction usually involves deallocation
919 of private data structures, including
920 .Fa xprt
921 itself.
922 Use of
923 .Fa xprt
924 is undefined after calling this routine.
926 .It Xo
927 .Vt fd_set svc_fdset ;
930 A global variable reflecting the
931 .Tn RPC
932 service side's
933 read file descriptor bit mask; it is suitable as a template parameter
934 to the
935 .Xr select 2
936 system call.
937 This is only of interest
938 if a service implementor does not call
939 .Fn svc_run ,
940 but rather does his own asynchronous event processing.
941 This variable is read\-only (do not pass its address to
942 .Xr select 2 ! ) ,
943 yet it may change after calls to
944 .Fn svc_getreqset
945 or any creation routines.
946 As well, note that if the process has descriptor limits
947 which are extended beyond
948 .Dv FD_SETSIZE ,
949 this variable will only be usable for the first
950 .Dv FD_SETSIZE
951 descriptors.
953 .It Xo
954 .Vt int svc_fds ;
957 Similar to
958 .Va svc_fdset ,
959 but limited to 32 descriptors.
960 This
961 interface is obsoleted by
962 .Va svc_fdset .
964 .It Xo
965 .Ft bool_t
966 .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
969 A macro that frees any data allocated by the
970 .Tn RPC/XDR
971 system when it decoded the arguments to a service procedure
972 using
973 .Fn svc_getargs .
974 This routine returns 1 if the results were successfully
975 freed,
976 and zero otherwise.
978 .It Xo
979 .Ft bool_t
980 .Fn svc_getargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
983 A macro that decodes the arguments of an
984 .Tn RPC
985 request
986 associated with the
987 .Tn RPC
988 service transport handle,
989 .Fa xprt .
990 The parameter
991 .Fa in
992 is the address where the arguments will be placed;
993 .Fa inproc
994 is the
995 .Tn XDR
996 routine used to decode the arguments.
997 This routine returns one if decoding succeeds, and zero
998 otherwise.
1000 .It Xo
1001 .Ft "struct sockaddr_in *"
1003 .It Xo
1004 .Fn svc_getcaller "SVCXPRT *xprt"
1007 The approved way of getting the network address of the caller
1008 of a procedure associated with the
1009 .Tn RPC
1010 service transport handle,
1011 .Fa xprt .
1013 .It Xo
1014 .Ft void
1015 .Fn svc_getreqset "fd_set *rdfds"
1018 This routine is only of interest if a service implementor
1019 does not call
1020 .Fn svc_run ,
1021 but instead implements custom asynchronous event processing.
1022 It is called when the
1023 .Xr select 2
1024 system call has determined that an
1025 .Tn RPC
1026 request has arrived on some
1027 .Tn RPC
1028 socket(s);
1029 .Fa rdfds
1030 is the resultant read file descriptor bit mask.
1031 The routine returns when all sockets associated with the
1032 value of
1033 .Fa rdfds
1034 have been serviced.
1036 .It Xo
1037 .Ft void
1038 .Fn svc_getreq "int rdfds"
1041 Similar to
1042 .Fn svc_getreqset ,
1043 but limited to 32 descriptors.
1044 This interface is obsoleted by
1045 .Fn svc_getreqset .
1047 .It Xo
1048 .Ft bool_t
1049 .Fo svc_register
1050 .Fa "SVCXPRT *xprt"
1051 .Fa "u_long prognum"
1052 .Fa "u_long versnum"
1053 .Fa "void (*dispatch)(struct svc_req *, SVCXPRT *)"
1054 .Fa "int protocol"
1058 Associates
1059 .Fa prognum
1061 .Fa versnum
1062 with the service dispatch procedure,
1063 .Fn dispatch .
1065 .Fa protocol
1066 is zero, the service is not registered with the
1067 .Xr portmap 8
1068 service.
1070 .Fa protocol
1071 is non-zero, then a mapping of the triple
1072 .Pq Fa prognum , versnum , protocol
1074 .Fa xprt\->xp_port
1075 is established with the local
1076 .Xr portmap 8
1077 service (generally
1078 .Fa protocol
1079 is zero,
1080 .Dv IPPROTO_UDP
1082 .Dv IPPROTO_TCP ) .
1083 The procedure
1084 .Fn dispatch
1085 has the following form:
1086 .Bd -ragged -offset indent
1087 .Ft bool_t
1088 .Fn dispatch "struct svc_req *request" "SVCXPRT *xprt"
1092 .Fn svc_register
1093 routine returns one if it succeeds, and zero otherwise.
1095 .It Xo
1096 .Fn svc_run
1099 This routine never returns.
1100 It waits for
1101 .Tn RPC
1102 requests to arrive, and calls the appropriate service
1103 procedure using
1104 .Fn svc_getreq
1105 when one arrives.
1106 This procedure is usually waiting for a
1107 .Xr select 2
1108 system call to return.
1110 .It Xo
1111 .Ft bool_t
1112 .Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "char *out"
1115 Called by an
1116 .Tn RPC
1117 service's dispatch routine to send the results of a
1118 remote procedure call.
1119 The parameter
1120 .Fa xprt
1121 is the request's associated transport handle;
1122 .Fa outproc
1123 is the
1124 .Tn XDR
1125 routine which is used to encode the results; and
1126 .Fa out
1127 is the address of the results.
1128 This routine returns one if it succeeds, zero otherwise.
1130 .It Xo
1131 .Ft void
1133 .It Xo
1134 .Fn svc_unregister "u_long prognum" "u_long versnum"
1137 Remove all mapping of the double
1138 .Pq Fa prognum , versnum
1139 to dispatch routines, and of the triple
1140 .Pq Fa prognum , versnum , *
1141 to port number.
1143 .It Xo
1144 .Ft void
1146 .It Xo
1147 .Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why"
1150 Called by a service dispatch routine that refuses to perform
1151 a remote procedure call due to an authentication error.
1153 .It Xo
1154 .Ft void
1156 .It Xo
1157 .Fn svcerr_decode "SVCXPRT *xprt"
1160 Called by a service dispatch routine that cannot successfully
1161 decode its parameters.
1162 See also
1163 .Fn svc_getargs .
1165 .It Xo
1166 .Ft void
1168 .It Xo
1169 .Fn svcerr_noproc "SVCXPRT *xprt"
1172 Called by a service dispatch routine that does not implement
1173 the procedure number that the caller requests.
1175 .It Xo
1176 .Ft void
1178 .It Xo
1179 .Fn svcerr_noprog "SVCXPRT *xprt"
1182 Called when the desired program is not registered with the
1183 .Tn RPC
1184 package.
1185 Service implementors usually do not need this routine.
1187 .It Xo
1188 .Ft void
1190 .It Xo
1191 .Fn svcerr_progvers "SVCXPRT *xprt" "u_long low_vers" "u_long high_vers"
1194 Called when the desired version of a program is not registered
1195 with the
1196 .Tn RPC
1197 package.
1198 Service implementors usually do not need this routine.
1200 .It Xo
1201 .Ft void
1203 .It Xo
1204 .Fn svcerr_systemerr "SVCXPRT *xprt"
1207 Called by a service dispatch routine when it detects a system
1208 error
1209 not covered by any particular protocol.
1210 For example, if a service can no longer allocate storage,
1211 it may call this routine.
1213 .It Xo
1214 .Ft void
1216 .It Xo
1217 .Fn svcerr_weakauth "SVCXPRT *xprt"
1220 Called by a service dispatch routine that refuses to perform
1221 a remote procedure call due to insufficient
1222 authentication parameters.
1223 The routine calls
1224 .Fn svcerr_auth xprt AUTH_TOOWEAK .
1226 .It Xo
1227 .Ft "SVCXPRT *"
1229 .It Xo
1230 .Fn svcraw_create void
1233 This routine creates a toy
1234 .Tn RPC
1235 service transport, to which it returns a pointer.
1236 The transport
1237 is really a buffer within the process's address space,
1238 so the corresponding
1239 .Tn RPC
1240 client should live in the same
1241 address space;
1243 .Fn clntraw_create .
1244 This routine allows simulation of
1245 .Tn RPC
1246 and acquisition of
1247 .Tn RPC
1248 overheads (such as round trip times), without any kernel
1249 interference.
1250 This routine returns
1251 .Dv NULL
1252 if it fails.
1254 .It Xo
1255 .Ft "SVCXPRT *"
1257 .It Xo
1258 .Fn svctcp_create "int sock" "u_int send_buf_size" "u_int recv_buf_size"
1261 This routine creates a
1262 .Tn TCP/IP Ns \-based
1263 .Tn RPC
1264 service transport, to which it returns a pointer.
1265 The transport is associated with the socket
1266 .Fa sock ,
1267 which may be
1268 .Dv RPC_ANYSOCK ,
1269 in which case a new socket is created.
1270 If the socket is not bound to a local
1271 .Tn TCP
1272 port, then this routine binds it to an arbitrary port.
1273 Upon completion,
1274 .Fa xprt\->xp_sock
1275 is the transport's socket descriptor, and
1276 .Fa xprt\->xp_port
1277 is the transport's port number.
1278 This routine returns
1279 .Dv NULL
1280 if it fails.
1281 Since
1282 .Tn TCP Ns \-based
1283 .Tn RPC
1284 uses buffered
1285 .Tn I/O ,
1286 users may specify the size of buffers; values of zero
1287 choose suitable defaults.
1289 .It Xo
1290 .Ft "SVCXPRT *"
1292 .It Xo
1293 .Fn svcfd_create "int fd" "u_int sendsize" "u_int recvsize"
1296 Create a service on top of any open descriptor.
1297 Typically,
1298 this
1299 descriptor is a connected socket for a stream protocol such
1301 .Tn TCP .
1302 .Fa sendsize
1304 .Fa recvsize
1305 indicate sizes for the send and receive buffers.
1306 If they are
1307 zero, a reasonable default is chosen.
1309 .It Xo
1310 .Ft "SVCXPRT *"
1312 .It Xo
1313 .Fn svcudp_bufcreate "int sock" "u_int sendsize" "u_int recvsize"
1316 This routine creates a
1317 .Tn UDP/IP Ns \-based
1318 .Tn RPC
1319 service transport, to which it returns a pointer.
1320 The transport is associated with the socket
1321 .Fa sock ,
1322 which may be
1323 .Dv RPC_ANYSOCK ,
1324 in which case a new socket is created.
1325 If the socket is not bound to a local
1326 .Tn UDP
1327 port, then this routine binds it to an arbitrary port.
1328 Upon
1329 completion,
1330 .Fa xprt\->xp_sock
1331 is the transport's socket descriptor, and
1332 .Fa xprt\->xp_port
1333 is the transport's port number.
1334 This routine returns
1335 .Dv NULL
1336 if it fails.
1338 This allows the user to specify the maximum packet size for sending and
1339 receiving
1340 .Tn UDP Ns \-based
1341 .Tn RPC
1342 messages.
1344 .It Xo
1345 .Ft bool_t
1346 .Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar"
1349 Used for encoding
1350 .Tn RPC
1351 reply messages.
1352 This routine is useful for users who
1353 wish to generate
1354 .Tn RPC Ns \-style
1355 messages without using the
1356 .Tn RPC
1357 package.
1359 .It Xo
1360 .Ft bool_t
1361 .Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp"
1364 Used for describing
1366 credentials.
1367 This routine is useful for users
1368 who wish to generate these credentials without using the
1369 .Tn RPC
1370 authentication package.
1372 .It Xo
1373 .Ft void
1375 .It Xo
1376 .Ft bool_t
1377 .Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr"
1380 Used for describing
1381 .Tn RPC
1382 call header messages.
1383 This routine is useful for users who wish to generate
1384 .Tn RPC Ns \-style
1385 messages without using the
1386 .Tn RPC
1387 package.
1389 .It Xo
1390 .Ft bool_t
1391 .Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg"
1394 Used for describing
1395 .Tn RPC
1396 call messages.
1397 This routine is useful for users who wish to generate
1398 .Tn RPC Ns \-style
1399 messages without using the
1400 .Tn RPC
1401 package.
1403 .It Xo
1404 .Ft bool_t
1405 .Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap"
1408 Used for describing
1409 .Tn RPC
1410 authentication information messages.
1411 This routine is useful for users who wish to generate
1412 .Tn RPC Ns \-style
1413 messages without using the
1414 .Tn RPC
1415 package.
1417 .It Xo
1418 .Vt struct pmap ;
1420 .It Xo
1421 .Ft bool_t
1422 .Fn xdr_pmap "XDR *xdrs" "struct pmap *regs"
1425 Used for describing parameters to various
1426 .Xr portmap 8
1427 procedures, externally.
1428 This routine is useful for users who wish to generate
1429 these parameters without using the
1430 .Fn pmap_*
1431 interface.
1433 .It Xo
1434 .Ft bool_t
1435 .Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp"
1438 Used for describing a list of port mappings, externally.
1439 This routine is useful for users who wish to generate
1440 these parameters without using the
1441 .Fn pmap_*
1442 interface.
1444 .It Xo
1445 .Ft bool_t
1446 .Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr"
1449 Used for describing
1450 .Tn RPC
1451 reply messages.
1452 This routine is useful for users who wish to generate
1453 .Tn RPC Ns \-style
1454 messages without using the
1455 .Tn RPC
1456 package.
1458 .It Xo
1459 .Ft bool_t
1460 .Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg"
1463 Used for describing
1464 .Tn RPC
1465 reply messages.
1466 This routine is useful for users who wish to generate
1467 .Tn RPC
1468 style messages without using the
1469 .Tn RPC
1470 package.
1472 .It Xo
1473 .Ft void
1475 .It Xo
1476 .Fn xprt_register "SVCXPRT *xprt"
1479 After
1480 .Tn RPC
1481 service transport handles are created,
1482 they should register themselves with the
1483 .Tn RPC
1484 service package.
1485 This routine modifies the global variable
1486 .Va svc_fds .
1487 Service implementors usually do not need this routine.
1489 .It Xo
1490 .Ft void
1492 .It Xo
1493 .Fn xprt_unregister "SVCXPRT *xprt"
1496 Before an
1497 .Tn RPC
1498 service transport handle is destroyed,
1499 it should unregister itself with the
1500 .Tn RPC
1501 service package.
1502 This routine modifies the global variable
1503 .Va svc_fds .
1504 Service implementors usually do not need this routine.
1506 .Sh SEE ALSO
1507 .Xr rpc_secure 3 ,
1508 .Xr xdr 3
1510 .%T "Remote Procedure Calls: Protocol Specification"
1513 .%T "Remote Procedure Call Programming Guide"
1516 .%T "rpcgen Programming Guide"
1519 .%T "RPC: Remote Procedure Call Protocol Specification"
1520 .%O RFC 1050
1521 .%Q "Sun Microsystems, Inc., USC-ISI"