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