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