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