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