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