source: rtems/cpukit/librpc/src/rpc/rpc.3 @ df49c60

4.104.114.84.95
Last change on this file since df49c60 was df49c60, checked in by Joel Sherrill <joel.sherrill@…>, on 06/12/00 at 15:00:15

Merged from 4.5.0-beta3a

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