xref: /dragonfly/lib/libc/rpc/rpc_soc.3 (revision 33311965) 
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
398.Vt "struct timeval" Ta "set total timeout"
399.It Dv CLGET_TIMEOUT Ta
400.Vt "struct timeval" Ta "get total timeout"
401.El
402.Pp
403Note: if you set the timeout using
404.Fn clnt_control ,
405the timeout argument passed to
406.Fn clnt_call
407will be ignored in all future calls.
408.Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
409.It Dv CLGET_SERVER_ADDR Ta
410.Vt "struct sockaddr_in" Ta "get server's address"
411.El
412.Pp
413The following operations are valid for
414.Tn UDP
415only:
416.Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
417.It Dv CLSET_RETRY_TIMEOUT Ta
418.Vt "struct timeval" Ta "set the retry timeout"
419.It Dv CLGET_RETRY_TIMEOUT Ta
420.Vt "struct timeval" Ta "get the retry timeout"
421.El
422.Pp
423The retry timeout is the time that
424.Tn "UDP RPC"
425waits for the server to reply before
426retransmitting the request.
427.Pp
428.It Xo
429.Ft bool_t
430.Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out"
431.Xc
432.Pp
433A macro that frees any data allocated by the
434.Tn RPC/XDR
435system when it decoded the results of an
436.Tn RPC
437call.
438The
439.Fa out
440argument
441is the address of the results, and
442.Fa outproc
443is the
444.Tn XDR
445routine describing the results.
446This routine returns one if the results were successfully
447freed,
448and zero otherwise.
449.Pp
450.It Xo
451.Ft void
452.Xc
453.It Xo
454.Fn clnt_geterr "CLIENT *clnt" "struct rpc_err *errp"
455.Xc
456.Pp
457A macro that copies the error structure out of the client
458handle
459to the structure at address
460.Fa errp .
461.Pp
462.It Xo
463.Ft void
464.Xc
465.It Xo
466.Fn clnt_pcreateerror "const char *s"
467.Xc
468.Pp
469prints a message to standard error indicating
470why a client
471.Tn RPC
472handle could not be created.
473The message is prepended with string
474.Fa s
475and a colon.
476A newline is appended at the end of the message.
477Used when a
478.Fn clnt_create ,
479.Fn clntraw_create ,
480.Fn clnttcp_create ,
481or
482.Fn clntudp_create
483call fails.
484.Pp
485.It Xo
486.Ft void
487.Xc
488.It Xo
489.Fn clnt_perrno "enum clnt_stat stat"
490.Xc
491.Pp
492Print a message to standard error corresponding
493to the condition indicated by
494.Fa stat .
495A newline is appended at the end of the message.
496Used after
497.Fn callrpc .
498.Pp
499.It Xo
500.Ft void
501.Fn clnt_perror "CLIENT *clnt" "const char *s"
502.Xc
503.Pp
504Print a message to standard error indicating why an
505.Tn RPC
506call failed;
507.Fa clnt
508is the handle used to do the call.
509The message is prepended with string
510.Fa s
511and a colon.
512A newline is appended at the end of the message.
513Used after
514.Fn clnt_call .
515.Pp
516.It Xo
517.Ft "char *"
518.Xc
519.It Xo
520.Fn clnt_spcreateerror "const char *s"
521.Xc
522.Pp
523Like
524.Fn clnt_pcreateerror ,
525except that it returns a string
526instead of printing to the standard error.
527.Pp
528Bugs: returns pointer to static data that is overwritten
529on each call.
530.Pp
531.It Xo
532.Ft "char *"
533.Xc
534.It Xo
535.Fn clnt_sperrno "enum clnt_stat stat"
536.Xc
537.Pp
538Take the same arguments as
539.Fn clnt_perrno ,
540but instead of sending a message to the standard error
541indicating why an
542.Tn RPC
543call failed, return a pointer to a string which contains
544the message.
545.Pp
546The
547.Fn clnt_sperrno
548function
549is used instead of
550.Fn clnt_perrno
551if the program does not have a standard error (as a program
552running as a server quite likely does not), or if the
553programmer
554does not want the message to be output with
555.Fn printf ,
556or if a message format different from that supported by
557.Fn clnt_perrno
558is to be used.
559.Pp
560Note: unlike
561.Fn clnt_sperror
562and
563.Fn clnt_spcreateerror ,
564.Fn clnt_sperrno
565returns pointer to static data, but the
566result will not get overwritten on each call.
567.Pp
568.It Xo
569.Ft "char *"
570.Xc
571.It Xo
572.Fn clnt_sperror "CLIENT *rpch" "const char *s"
573.Xc
574.Pp
575Like
576.Fn clnt_perror ,
577except that (like
578.Fn clnt_sperrno )
579it returns a string instead of printing to standard error.
580.Pp
581Bugs: returns pointer to static data that is overwritten
582on each call.
583.Pp
584.It Xo
585.Ft "CLIENT *"
586.Xc
587.It Xo
588.Fn clntraw_create "u_long prognum" "u_long versnum"
589.Xc
590.Pp
591This routine creates a toy
592.Tn RPC
593client for the remote program
594.Fa prognum ,
595version
596.Fa versnum .
597The transport used to pass messages to the service is
598actually a buffer within the process's address space, so the
599corresponding
600.Tn RPC
601server should live in the same address space; see
602.Fn svcraw_create .
603This allows simulation of
604.Tn RPC
605and acquisition of
606.Tn RPC
607overheads, such as round trip times, without any
608kernel interference.
609This routine returns
610.Dv NULL
611if it fails.
612.Pp
613.It Xo
614.Ft "CLIENT *"
615.Xc
616.It Xo
617.Fo clnttcp_create
618.Fa "struct sockaddr_in *addr"
619.Fa "u_long prognum"
620.Fa "u_long versnum"
621.Fa "int *sockp"
622.Fa "u_int sendsz"
623.Fa "u_int recvsz"
624.Fc
625.Xc
626.Pp
627This routine creates an
628.Tn RPC
629client for the remote program
630.Fa prognum ,
631version
632.Fa versnum ;
633the client uses
634.Tn TCP/IP
635as a transport.
636The remote program is located at Internet
637address
638.Fa addr .
639If
640.Fa addr\->sin_port
641is zero, then it is set to the actual port that the remote
642program is listening on (the remote
643.Xr rpcbind 8
644service is consulted for this information).
645The
646.Fa sockp
647argument
648is a socket; if it is
649.Dv RPC_ANYSOCK ,
650then this routine opens a new one and sets
651.Fa sockp .
652Since
653.Tn TCP Ns \-based
654.Tn RPC
655uses buffered
656.Tn I/O ,
657the user may specify the size of the send and receive buffers
658with the
659.Fa sendsz
660and
661.Fa recvsz
662arguments;
663values of zero choose suitable defaults.
664This routine returns
665.Dv NULL
666if it fails.
667.Pp
668.It Xo
669.Ft "CLIENT *"
670.Xc
671.It Xo
672.Fo clntudp_create
673.Fa "struct sockaddr_in *addr"
674.Fa "u_long prognum"
675.Fa "u_long versnum"
676.Fa "struct timeval wait"
677.Fa "int *sockp"
678.Fc
679.Xc
680.Pp
681This routine creates an
682.Tn RPC
683client for the remote program
684.Fa prognum ,
685version
686.Fa versnum ;
687the client uses
688.Tn UDP/IP
689as a transport.
690The remote program is located at Internet
691address
692.Fa addr .
693If
694.Fa addr\->sin_port
695is zero, then it is set to actual port that the remote
696program is listening on (the remote
697.Xr rpcbind 8
698service is consulted for this information).
699The
700.Fa sockp
701argument
702is a socket; if it is
703.Dv RPC_ANYSOCK ,
704then this routine opens a new one and sets
705.Fa sockp .
706The
707.Tn UDP
708transport resends the call message in intervals of
709.Fa wait
710time until a response is received or until the call times
711out.
712The total time for the call to time out is specified by
713.Fn clnt_call .
714.Pp
715Warning: since
716.Tn UDP Ns \-based
717.Tn RPC
718messages can only hold up to 8 Kbytes
719of encoded data, this transport cannot be used for procedures
720that take large arguments or return huge results.
721.Pp
722.It Xo
723.Ft "CLIENT *"
724.Xc
725.It Xo
726.Fo clntudp_bufcreate
727.Fa "struct sockaddr_in *addr"
728.Fa "u_long prognum"
729.Fa "u_long versnum"
730.Fa "struct timeval wait"
731.Fa "int *sockp"
732.Fa "unsigned int sendsize"
733.Fa "unsigned int recosize"
734.Fc
735.Xc
736.Pp
737This routine creates an
738.Tn RPC
739client for the remote program
740.Fa prognum ,
741on
742.Fa versnum ;
743the client uses
744.Tn UDP/IP
745as a transport.
746The remote program is located at Internet
747address
748.Fa addr .
749If
750.Fa addr\->sin_port
751is zero, then it is set to actual port that the remote
752program is listening on (the remote
753.Xr rpcbind 8
754service is consulted for this information).
755The
756.Fa sockp
757argument
758is a socket; if it is
759.Dv RPC_ANYSOCK ,
760then this routine opens a new one and sets
761.Fa sockp .
762The
763.Tn UDP
764transport resends the call message in intervals of
765.Fa wait
766time until a response is received or until the call times
767out.
768The total time for the call to time out is specified by
769.Fn clnt_call .
770.Pp
771This allows the user to specify the maximum packet size
772for sending and receiving
773.Tn UDP Ns \-based
774.Tn RPC
775messages.
776.Pp
777.It Xo
778.Ft "CLIENT *"
779.Xc
780.It Xo
781.Fo clntunix_create
782.Fa "struct sockaddr_un *raddr"
783.Fa "u_long prognum"
784.Fa "u_long versnum"
785.Fa "int *sockp"
786.Fa "u_int sendsz"
787.Fa "u_int recvsz"
788.Fc
789.Xc
790.Pp
791This routine creates an
792.Tn RPC
793client for the local
794program
795.Fa prognum ,
796version
797.Fa versnum ;
798the client uses
799.Ux Ns -domain
800sockets as a transport.
801The local program is located at the
802.Fa *raddr .
803The
804.Fa sockp
805argument
806is a socket; if it is
807.Dv RPC_ANYSOCK ,
808then this routine opens a new one and sets
809.Fa sockp .
810Since
811.Ux Ns -based
812.Tn RPC
813uses buffered
814.Tn I/O ,
815the user may specify the size of the send and receive buffers
816with the
817.Fa sendsz
818and
819.Fa recvsz
820arguments;
821values of zero choose suitable defaults.
822This routine returns
823.Dv NULL
824if it fails.
825.Pp
826.It Xo
827.Ft int
828.Xc
829.It Xo
830.Fn get_myaddress "struct sockaddr_in *addr"
831.Xc
832.Pp
833Stuff the machine's
834.Tn IP
835address into
836.Fa addr ,
837without consulting the library routines that deal with
838.Pa /etc/hosts .
839The port number is always set to
840.Fn htons PMAPPORT .
841Returns zero on success, non-zero on failure.
842.Pp
843.It Xo
844.Ft "struct pmaplist *"
845.Xc
846.It Xo
847.Fn pmap_getmaps "struct sockaddr_in *addr"
848.Xc
849.Pp
850A user interface to the
851.Xr rpcbind 8
852service, which returns a list of the current
853.Tn RPC
854program\-to\-port mappings
855on the host located at
856.Tn IP
857address
858.Fa addr .
859This routine can return
860.Dv NULL .
861The command
862.Dq Nm rpcinfo Fl p
863uses this routine.
864.Pp
865.It Xo
866.Ft u_short
867.Xc
868.It Xo
869.Fo pmap_getport
870.Fa "struct sockaddr_in *addr"
871.Fa "u_long prognum"
872.Fa "u_long versnum"
873.Fa "u_long protocol"
874.Fc
875.Xc
876.Pp
877A user interface to the
878.Xr rpcbind 8
879service, which returns the port number
880on which waits a service that supports program number
881.Fa prognum ,
882version
883.Fa versnum ,
884and speaks the transport protocol associated with
885.Fa protocol .
886The value of
887.Fa protocol
888is most likely
889.Dv IPPROTO_UDP
890or
891.Dv IPPROTO_TCP .
892A return value of zero means that the mapping does not exist
893or that
894the
895.Tn RPC
896system failed to contact the remote
897.Xr rpcbind 8
898service.
899In the latter case, the global variable
900.Va rpc_createerr
901contains the
902.Tn RPC
903status.
904.Pp
905.It Xo
906.Ft "enum clnt_stat"
907.Xc
908.It Xo
909.Fo pmap_rmtcall
910.Fa "struct sockaddr_in *addr"
911.Fa "u_long prognum"
912.Fa "u_long versnum"
913.Fa "u_long procnum"
914.Fa "xdrproc_t inproc"
915.Fa "char *in"
916.Fa "xdrproc_t outproc"
917.Fa "char *out"
918.Fa "struct timeval tout"
919.Fa "u_long *portp"
920.Fc
921.Xc
922.Pp
923A user interface to the
924.Xr rpcbind 8
925service, which instructs
926.Xr rpcbind 8
927on the host at
928.Tn IP
929address
930.Fa addr
931to make an
932.Tn RPC
933call on your behalf to a procedure on that host.
934The
935.Fa portp
936argument
937will be modified to the program's port number if the
938procedure
939succeeds.
940The definitions of other arguments are discussed
941in
942.Fn callrpc
943and
944.Fn clnt_call .
945This procedure should be used for a
946.Dq ping
947and nothing
948else.
949See also
950.Fn clnt_broadcast .
951.Pp
952.It Xo
953.Ft bool_t
954.Fn pmap_set "u_long prognum" "u_long versnum" "u_long protocol" "u_short port"
955.Xc
956.Pp
957A user interface to the
958.Xr rpcbind 8
959service, which establishes a mapping between the triple
960.Pq Fa prognum , versnum , protocol
961and
962.Fa port
963on the machine's
964.Xr rpcbind 8
965service.
966The value of
967.Fa protocol
968is most likely
969.Dv IPPROTO_UDP
970or
971.Dv IPPROTO_TCP .
972This routine returns one if it succeeds, zero otherwise.
973Automatically done by
974.Fn svc_register .
975.Pp
976.It Xo
977.Ft bool_t
978.Fn pmap_unset "u_long prognum" "u_long versnum"
979.Xc
980.Pp
981A user interface to the
982.Xr rpcbind 8
983service, which destroys all mapping between the triple
984.Pq Fa prognum , versnum , *
985and
986.Fa ports
987on the machine's
988.Xr rpcbind 8
989service.
990This routine returns one if it succeeds, zero
991otherwise.
992.Pp
993.It Xo
994.Ft bool_t
995.Fo registerrpc
996.Fa "u_long prognum"
997.Fa "u_long versnum"
998.Fa "u_long procnum"
999.Fa "char *(*procname)(void)"
1000.Fa "xdrproc_t inproc"
1001.Fa "xdrproc_t outproc"
1002.Fc
1003.Xc
1004.Pp
1005Register procedure
1006.Fa procname
1007with the
1008.Tn RPC
1009service package.
1010If a request arrives for program
1011.Fa prognum ,
1012version
1013.Fa versnum ,
1014and procedure
1015.Fa procnum ,
1016.Fa procname
1017is called with a pointer to its argument(s);
1018.Fa progname
1019should return a pointer to its static result(s);
1020.Fa inproc
1021is used to decode the arguments while
1022.Fa outproc
1023is used to encode the results.
1024This routine returns zero if the registration succeeded, \-1
1025otherwise.
1026.Pp
1027Warning: remote procedures registered in this form
1028are accessed using the
1029.Tn UDP/IP
1030transport; see
1031.Fn svcudp_create
1032for restrictions.
1033.Pp
1034.It Xo
1035.Vt "struct rpc_createerr" rpc_createerr ;
1036.Xc
1037.Pp
1038A global variable whose value is set by any
1039.Tn RPC
1040client creation routine
1041that does not succeed.
1042Use the routine
1043.Fn clnt_pcreateerror
1044to print the reason why.
1045.Pp
1046.It Xo
1047.Ft bool_t
1048.Fn svc_destroy "SVCXPRT * xprt"
1049.Xc
1050.Pp
1051A macro that destroys the
1052.Tn RPC
1053service transport handle,
1054.Fa xprt .
1055Destruction usually involves deallocation
1056of private data structures, including
1057.Fa xprt
1058itself.
1059Use of
1060.Fa xprt
1061is undefined after calling this routine.
1062.Pp
1063.It Xo
1064.Vt fd_set svc_fdset ;
1065.Xc
1066.Pp
1067A global variable reflecting the
1068.Tn RPC
1069service side's
1070read file descriptor bit mask; it is suitable as a template argument
1071to the
1072.Xr select 2
1073system call.
1074This is only of interest
1075if a service implementor does not call
1076.Fn svc_run ,
1077but rather does his own asynchronous event processing.
1078This variable is read\-only (do not pass its address to
1079.Xr select 2 ! ) ,
1080yet it may change after calls to
1081.Fn svc_getreqset
1082or any creation routines.
1083As well, note that if the process has descriptor limits
1084which are extended beyond
1085.Dv FD_SETSIZE ,
1086this variable will only be usable for the first
1087.Dv FD_SETSIZE
1088descriptors.
1089.Pp
1090.It Xo
1091.Vt int svc_fds ;
1092.Xc
1093.Pp
1094Similar to
1095.Va svc_fdset ,
1096but limited to 32 descriptors.
1097This
1098interface is obsoleted by
1099.Va svc_fdset .
1100.Pp
1101.It Xo
1102.Ft bool_t
1103.Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
1104.Xc
1105.Pp
1106A macro that frees any data allocated by the
1107.Tn RPC/XDR
1108system when it decoded the arguments to a service procedure
1109using
1110.Fn svc_getargs .
1111This routine returns 1 if the results were successfully
1112freed,
1113and zero otherwise.
1114.Pp
1115.It Xo
1116.Ft bool_t
1117.Fn svc_getargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
1118.Xc
1119.Pp
1120A macro that decodes the arguments of an
1121.Tn RPC
1122request
1123associated with the
1124.Tn RPC
1125service transport handle,
1126.Fa xprt .
1127The
1128.Fa in
1129argument
1130is the address where the arguments will be placed;
1131.Fa inproc
1132is the
1133.Tn XDR
1134routine used to decode the arguments.
1135This routine returns one if decoding succeeds, and zero
1136otherwise.
1137.Pp
1138.It Xo
1139.Ft "struct sockaddr_in *"
1140.Xc
1141.It Xo
1142.Fn svc_getcaller "SVCXPRT *xprt"
1143.Xc
1144.Pp
1145The approved way of getting the network address of the caller
1146of a procedure associated with the
1147.Tn RPC
1148service transport handle,
1149.Fa xprt .
1150.Pp
1151.It Xo
1152.Ft void
1153.Fn svc_getreqset "fd_set *rdfds"
1154.Xc
1155.Pp
1156This routine is only of interest if a service implementor
1157does not call
1158.Fn svc_run ,
1159but instead implements custom asynchronous event processing.
1160It is called when the
1161.Xr select 2
1162system call has determined that an
1163.Tn RPC
1164request has arrived on some
1165.Tn RPC
1166socket(s);
1167.Fa rdfds
1168is the resultant read file descriptor bit mask.
1169The routine returns when all sockets associated with the
1170value of
1171.Fa rdfds
1172have been serviced.
1173.Pp
1174.It Xo
1175.Ft void
1176.Fn svc_getreq "int rdfds"
1177.Xc
1178.Pp
1179Similar to
1180.Fn svc_getreqset ,
1181but limited to 32 descriptors.
1182This interface is obsoleted by
1183.Fn svc_getreqset .
1184.Pp
1185.It Xo
1186.Ft bool_t
1187.Fo svc_register
1188.Fa "SVCXPRT *xprt"
1189.Fa "u_long prognum"
1190.Fa "u_long versnum"
1191.Fa "void (*dispatch)(struct svc_req *, SVCXPRT *)"
1192.Fa "int protocol"
1193.Fc
1194.Xc
1195.Pp
1196Associates
1197.Fa prognum
1198and
1199.Fa versnum
1200with the service dispatch procedure,
1201.Fn dispatch .
1202If
1203.Fa protocol
1204is zero, the service is not registered with the
1205.Xr rpcbind 8
1206service.
1207If
1208.Fa protocol
1209is non-zero, then a mapping of the triple
1210.Pq Fa prognum , versnum , protocol
1211to
1212.Fa xprt\->xp_port
1213is established with the local
1214.Xr rpcbind 8
1215service (generally
1216.Fa protocol
1217is zero,
1218.Dv IPPROTO_UDP
1219or
1220.Dv IPPROTO_TCP ) .
1221The procedure
1222.Fn dispatch
1223has the following form:
1224.Bd -ragged -offset indent
1225.Ft bool_t
1226.Fn dispatch "struct svc_req *request" "SVCXPRT *xprt"
1227.Ed
1228.Pp
1229The
1230.Fn svc_register
1231routine returns one if it succeeds, and zero otherwise.
1232.Pp
1233.It Xo
1234.Fn svc_run
1235.Xc
1236.Pp
1237This routine never returns.
1238It waits for
1239.Tn RPC
1240requests to arrive, and calls the appropriate service
1241procedure using
1242.Fn svc_getreq
1243when one arrives.
1244This procedure is usually waiting for a
1245.Xr select 2
1246system call to return.
1247.Pp
1248.It Xo
1249.Ft bool_t
1250.Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "char *out"
1251.Xc
1252.Pp
1253Called by an
1254.Tn RPC
1255service's dispatch routine to send the results of a
1256remote procedure call.
1257The
1258.Fa xprt
1259argument
1260is the request's associated transport handle;
1261.Fa outproc
1262is the
1263.Tn XDR
1264routine which is used to encode the results; and
1265.Fa out
1266is the address of the results.
1267This routine returns one if it succeeds, zero otherwise.
1268.Pp
1269.It Xo
1270.Ft void
1271.Xc
1272.It Xo
1273.Fn svc_unregister "u_long prognum" "u_long versnum"
1274.Xc
1275.Pp
1276Remove all mapping of the double
1277.Pq Fa prognum , versnum
1278to dispatch routines, and of the triple
1279.Pq Fa prognum , versnum , *
1280to port number.
1281.Pp
1282.It Xo
1283.Ft void
1284.Xc
1285.It Xo
1286.Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why"
1287.Xc
1288.Pp
1289Called by a service dispatch routine that refuses to perform
1290a remote procedure call due to an authentication error.
1291.Pp
1292.It Xo
1293.Ft void
1294.Xc
1295.It Xo
1296.Fn svcerr_decode "SVCXPRT *xprt"
1297.Xc
1298.Pp
1299Called by a service dispatch routine that cannot successfully
1300decode its arguments.
1301See also
1302.Fn svc_getargs .
1303.Pp
1304.It Xo
1305.Ft void
1306.Xc
1307.It Xo
1308.Fn svcerr_noproc "SVCXPRT *xprt"
1309.Xc
1310.Pp
1311Called by a service dispatch routine that does not implement
1312the procedure number that the caller requests.
1313.Pp
1314.It Xo
1315.Ft void
1316.Xc
1317.It Xo
1318.Fn svcerr_noprog "SVCXPRT *xprt"
1319.Xc
1320.Pp
1321Called when the desired program is not registered with the
1322.Tn RPC
1323package.
1324Service implementors usually do not need this routine.
1325.Pp
1326.It Xo
1327.Ft void
1328.Xc
1329.It Xo
1330.Fn svcerr_progvers "SVCXPRT *xprt" "u_long low_vers" "u_long high_vers"
1331.Xc
1332.Pp
1333Called when the desired version of a program is not registered
1334with the
1335.Tn RPC
1336package.
1337Service implementors usually do not need this routine.
1338.Pp
1339.It Xo
1340.Ft void
1341.Xc
1342.It Xo
1343.Fn svcerr_systemerr "SVCXPRT *xprt"
1344.Xc
1345.Pp
1346Called by a service dispatch routine when it detects a system
1347error
1348not covered by any particular protocol.
1349For example, if a service can no longer allocate storage,
1350it may call this routine.
1351.Pp
1352.It Xo
1353.Ft void
1354.Xc
1355.It Xo
1356.Fn svcerr_weakauth "SVCXPRT *xprt"
1357.Xc
1358.Pp
1359Called by a service dispatch routine that refuses to perform
1360a remote procedure call due to insufficient
1361authentication arguments.
1362The routine calls
1363.Fn svcerr_auth xprt AUTH_TOOWEAK .
1364.Pp
1365.It Xo
1366.Ft "SVCXPRT *"
1367.Xc
1368.It Xo
1369.Fn svcraw_create void
1370.Xc
1371.Pp
1372This routine creates a toy
1373.Tn RPC
1374service transport, to which it returns a pointer.
1375The transport
1376is really a buffer within the process's address space,
1377so the corresponding
1378.Tn RPC
1379client should live in the same
1380address space;
1381see
1382.Fn clntraw_create .
1383This routine allows simulation of
1384.Tn RPC
1385and acquisition of
1386.Tn RPC
1387overheads (such as round trip times), without any kernel
1388interference.
1389This routine returns
1390.Dv NULL
1391if it fails.
1392.Pp
1393.It Xo
1394.Ft "SVCXPRT *"
1395.Xc
1396.It Xo
1397.Fn svctcp_create "int sock" "u_int send_buf_size" "u_int recv_buf_size"
1398.Xc
1399.Pp
1400This routine creates a
1401.Tn TCP/IP Ns \-based
1402.Tn RPC
1403service transport, to which it returns a pointer.
1404The transport is associated with the socket
1405.Fa sock ,
1406which may be
1407.Dv RPC_ANYSOCK ,
1408in which case a new socket is created.
1409If the socket is not bound to a local
1410.Tn TCP
1411port, then this routine binds it to an arbitrary port.
1412Upon completion,
1413.Fa xprt\->xp_fd
1414is the transport's socket descriptor, and
1415.Fa xprt\->xp_port
1416is the transport's port number.
1417This routine returns
1418.Dv NULL
1419if it fails.
1420Since
1421.Tn TCP Ns \-based
1422.Tn RPC
1423uses buffered
1424.Tn I/O ,
1425users may specify the size of buffers; values of zero
1426choose suitable defaults.
1427.Pp
1428.It Xo
1429.Ft "SVCXPRT *"
1430.Xc
1431.It Xo
1432.Fn svcunix_create "int sock" "u_int send_buf_size" "u_int recv_buf_size" "char *path"
1433.Xc
1434.Pp
1435This routine creates a
1436.Ux Ns -based
1437.Tn RPC
1438service transport, to which it returns a pointer.
1439The transport is associated with the socket
1440.Fa sock ,
1441which may be
1442.Dv RPC_ANYSOCK ,
1443in which case a new socket is created.
1444The
1445.Fa *path
1446argument
1447is a variable-length file system pathname of
1448at most 104 characters.
1449This file is
1450.Em not
1451removed when the socket is closed.
1452The
1453.Xr unlink 2
1454system call must be used to remove the file.
1455Upon completion,
1456.Fa xprt\->xp_fd
1457is the transport's socket descriptor.
1458This routine returns
1459.Dv NULL
1460if it fails.
1461Since
1462.Ux Ns -based
1463.Tn RPC
1464uses buffered
1465.Tn I/O ,
1466users may specify the size of buffers; values of zero
1467choose suitable defaults.
1468.Pp
1469.It Xo
1470.Ft "SVCXPRT *"
1471.Xc
1472.It Xo
1473.Fn svcunixfd_create "int fd" "u_int sendsize" "u_int recvsize"
1474.Xc
1475.Pp
1476Create a service on top of any open descriptor.
1477The
1478.Fa sendsize
1479and
1480.Fa recvsize
1481arguments
1482indicate sizes for the send and receive buffers.
1483If they are
1484zero, a reasonable default is chosen.
1485.Pp
1486.It Xo
1487.Ft "SVCXPRT *"
1488.Xc
1489.It Xo
1490.Fn svcfd_create "int fd" "u_int sendsize" "u_int recvsize"
1491.Xc
1492.Pp
1493Create a service on top of any open descriptor.
1494Typically,
1495this
1496descriptor is a connected socket for a stream protocol such
1497as
1498.Tn TCP .
1499The
1500.Fa sendsize
1501and
1502.Fa recvsize
1503arguments
1504indicate sizes for the send and receive buffers.
1505If they are
1506zero, a reasonable default is chosen.
1507.Pp
1508.It Xo
1509.Ft "SVCXPRT *"
1510.Xc
1511.It Xo
1512.Fn svcudp_bufcreate "int sock" "u_int sendsize" "u_int recvsize"
1513.Xc
1514.Pp
1515This routine creates a
1516.Tn UDP/IP Ns \-based
1517.Tn RPC
1518service transport, to which it returns a pointer.
1519The transport is associated with the socket
1520.Fa sock ,
1521which may be
1522.Dv RPC_ANYSOCK ,
1523in which case a new socket is created.
1524If the socket is not bound to a local
1525.Tn UDP
1526port, then this routine binds it to an arbitrary port.
1527Upon
1528completion,
1529.Fa xprt\->xp_fd
1530is the transport's socket descriptor, and
1531.Fa xprt\->xp_port
1532is the transport's port number.
1533This routine returns
1534.Dv NULL
1535if it fails.
1536.Pp
1537This allows the user to specify the maximum packet size for sending and
1538receiving
1539.Tn UDP Ns \-based
1540.Tn RPC
1541messages.
1542.Pp
1543.It Xo
1544.Ft bool_t
1545.Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar"
1546.Xc
1547.Pp
1548Used for encoding
1549.Tn RPC
1550reply messages.
1551This routine is useful for users who
1552wish to generate
1553.Tn RPC Ns \-style
1554messages without using the
1555.Tn RPC
1556package.
1557.Pp
1558.It Xo
1559.Ft bool_t
1560.Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp"
1561.Xc
1562.Pp
1563Used for describing
1564.Ux
1565credentials.
1566This routine is useful for users
1567who wish to generate these credentials without using the
1568.Tn RPC
1569authentication package.
1570.Pp
1571.It Xo
1572.Ft void
1573.Xc
1574.It Xo
1575.Ft bool_t
1576.Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr"
1577.Xc
1578.Pp
1579Used for describing
1580.Tn RPC
1581call header messages.
1582This routine is useful for users who wish to generate
1583.Tn RPC Ns \-style
1584messages without using the
1585.Tn RPC
1586package.
1587.Pp
1588.It Xo
1589.Ft bool_t
1590.Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg"
1591.Xc
1592.Pp
1593Used for describing
1594.Tn RPC
1595call messages.
1596This routine is useful for users who wish to generate
1597.Tn RPC Ns \-style
1598messages without using the
1599.Tn RPC
1600package.
1601.Pp
1602.It Xo
1603.Ft bool_t
1604.Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap"
1605.Xc
1606.Pp
1607Used for describing
1608.Tn RPC
1609authentication information messages.
1610This routine is useful for users who wish to generate
1611.Tn RPC Ns \-style
1612messages without using the
1613.Tn RPC
1614package.
1615.Pp
1616.It Xo
1617.Vt struct pmap ;
1618.Xc
1619.It Xo
1620.Ft bool_t
1621.Fn xdr_pmap "XDR *xdrs" "struct pmap *regs"
1622.Xc
1623.Pp
1624Used for describing arguments to various
1625.Xr rpcbind 8
1626procedures, externally.
1627This routine is useful for users who wish to generate
1628these arguments without using the
1629.Fn pmap_*
1630interface.
1631.Pp
1632.It Xo
1633.Ft bool_t
1634.Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp"
1635.Xc
1636.Pp
1637Used for describing a list of port mappings, externally.
1638This routine is useful for users who wish to generate
1639these arguments without using the
1640.Fn pmap_*
1641interface.
1642.Pp
1643.It Xo
1644.Ft bool_t
1645.Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr"
1646.Xc
1647.Pp
1648Used for describing
1649.Tn RPC
1650reply messages.
1651This routine is useful for users who wish to generate
1652.Tn RPC Ns \-style
1653messages without using the
1654.Tn RPC
1655package.
1656.Pp
1657.It Xo
1658.Ft bool_t
1659.Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg"
1660.Xc
1661.Pp
1662Used for describing
1663.Tn RPC
1664reply messages.
1665This routine is useful for users who wish to generate
1666.Tn RPC
1667style messages without using the
1668.Tn RPC
1669package.
1670.Pp
1671.It Xo
1672.Ft void
1673.Xc
1674.It Xo
1675.Fn xprt_register "SVCXPRT *xprt"
1676.Xc
1677.Pp
1678After
1679.Tn RPC
1680service transport handles are created,
1681they should register themselves with the
1682.Tn RPC
1683service package.
1684This routine modifies the global variable
1685.Va svc_fds .
1686Service implementors usually do not need this routine.
1687.Pp
1688.It Xo
1689.Ft void
1690.Xc
1691.It Xo
1692.Fn xprt_unregister "SVCXPRT *xprt"
1693.Xc
1694.Pp
1695Before an
1696.Tn RPC
1697service transport handle is destroyed,
1698it should unregister itself with the
1699.Tn RPC
1700service package.
1701This routine modifies the global variable
1702.Va svc_fds .
1703Service implementors usually do not need this routine.
1704.El
1705.Sh SEE ALSO
1706.Xr rpc_secure 3 ,
1707.Xr xdr 3
1708.Rs
1709.%T "Remote Procedure Calls: Protocol Specification"
1710.Re
1711.Rs
1712.%T "Remote Procedure Call Programming Guide"
1713.Re
1714.Rs
1715.%T "rpcgen Programming Guide"
1716.Re
1717.Rs
1718.%T "RPC: Remote Procedure Call Protocol Specification"
1719.%O RFC 1050
1720.%Q "Sun Microsystems, Inc., USC-ISI"
1721.Re
1722