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