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