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