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