summaryrefslogtreecommitdiffstats
path: root/man3/rpc.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/rpc.3')
-rw-r--r--man3/rpc.3151
1 files changed, 75 insertions, 76 deletions
diff --git a/man3/rpc.3 b/man3/rpc.3
index 4923e8a..b5d238c 100644
--- a/man3/rpc.3
+++ b/man3/rpc.3
@@ -9,7 +9,7 @@
.\"
.\" 2007-12-30, mtk, Convert function prototypes to modern C syntax
.\"
-.TH rpc 3 2023-07-20 "Linux man-pages 6.05.01"
+.TH rpc 3 2023-10-31 "Linux man-pages 6.7"
.SH NAME
rpc \- library routines for remote procedure calls
.SH LIBRARY
@@ -22,28 +22,28 @@ First, the client calls a procedure to send a data packet to the server.
Upon receipt of the packet, the server calls a dispatch routine
to perform the requested service, and then sends back a reply.
Finally, the procedure call returns to the client.
-.\" .LP
+.\" .P
.\" We don't have an rpc_secure.3 page at the moment -- MTK, 19 Sep 05
.\" Routines that are used for Secure RPC (DES authentication) are described in
.\" .BR rpc_secure (3).
.\" Secure RPC can be used only if DES encryption is available.
-.PP
+.P
To take use of these routines, include the header file
.IR "<rpc/rpc.h>" .
-.PP
+.P
The prototypes below make use of the following types:
-.PP
+.P
.RS 4
.EX
.BI "typedef int " bool_t ;
-.PP
+.P
.BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *, ...);"
-.PP
+.P
.BI "typedef bool_t (*" resultproc_t ")(caddr_t " resp ,
.BI " struct sockaddr_in *" raddr );
.EE
.RE
-.PP
+.P
See the header files for the declarations of the
.IR AUTH ,
.IR CLIENT ,
@@ -51,7 +51,7 @@ See the header files for the declarations of the
and
.I XDR
types.
-.PP
+.P
.nf
.BI "void auth_destroy(AUTH *" auth );
.fi
@@ -63,7 +63,7 @@ The use of
.I auth
is undefined after calling
.BR auth_destroy ().
-.PP
+.P
.nf
.B AUTH *authnone_create(void);
.fi
@@ -72,7 +72,7 @@ Create and return an RPC
authentication handle that passes nonusable authentication
information with each remote procedure call.
This is the default authentication used by RPC.
-.PP
+.P
.nf
.BI "AUTH *authunix_create(char *" host ", uid_t " uid ", gid_t " gid ,
.BI " int " len ", gid_t " aup_gids [. len ]);
@@ -92,7 +92,7 @@ and
.I aup_gids
refer to a counted array of groups to which the user belongs.
It is easy to impersonate a user.
-.PP
+.P
.nf
.B AUTH *authunix_create_default(void);
.fi
@@ -100,7 +100,7 @@ It is easy to impersonate a user.
Calls
.BR authunix_create ()
with the appropriate parameters.
-.PP
+.P
.nf
.BI "int callrpc(char *" host ", unsigned long " prognum ,
.BI " unsigned long " versnum ", unsigned long " procnum ,
@@ -136,7 +136,7 @@ uses UDP/IP as a transport; see
.BR clntudp_create ()
for restrictions.
You do not have control of timeouts or authentication using this routine.
-.PP
+.P
.nf
.BI "enum clnt_stat clnt_broadcast(unsigned long " prognum ,
.BI " unsigned long " versnum ", unsigned long " procnum ,
@@ -177,7 +177,7 @@ waits for more replies; otherwise it returns with appropriate status.
Warning: broadcast sockets are limited in size to the
maximum transfer unit of the data link.
For ethernet, this value is 1500 bytes.
-.PP
+.P
.nf
.BI "enum clnt_stat clnt_call(CLIENT *" clnt ", unsigned long " procnum ,
.BI " xdrproc_t " inproc ", char *" in ,
@@ -202,7 +202,7 @@ is used to encode the procedure's parameters, and
is used to decode the procedure's results;
.I tout
is the time allowed for results to come back.
-.PP
+.P
.nf
.BI "clnt_destroy(CLIENT *" clnt );
.fi
@@ -218,7 +218,7 @@ is undefined after calling
.BR clnt_destroy ().
If the RPC library opened the associated socket, it will close it also.
Otherwise, the socket remains open.
-.PP
+.P
.nf
.BI "CLIENT *clnt_create(const char *" host ", unsigned long " prog ,
.BI " unsigned long " vers ", const char *" proto );
@@ -238,7 +238,7 @@ Warning: using UDP has its shortcomings.
Since UDP-based RPC messages can hold only up to 8 Kbytes of encoded data,
this transport cannot be used for procedures that take
large arguments or return huge results.
-.PP
+.P
.nf
.BI "bool_t clnt_control(CLIENT *" cl ", int " req ", char *" info );
.fi
@@ -285,7 +285,7 @@ The following operations are valid for UDP only:
The retry timeout is the time that "UDP RPC"
waits for the server to reply before
retransmitting the request.
-.PP
+.P
.nf
.BI "clnt_freeres(CLIENT * " clnt ", xdrproc_t " outproc ", char *" out );
.fi
@@ -299,7 +299,7 @@ is the address of the results, and
is the XDR routine describing the results.
This routine returns one if the results were successfully freed,
and zero otherwise.
-.PP
+.P
.nf
.BI "void clnt_geterr(CLIENT *" clnt ", struct rpc_err *" errp );
.fi
@@ -307,7 +307,7 @@ and zero otherwise.
A macro that copies the error structure out of the client
handle to the structure at address
.IR errp .
-.PP
+.P
.nf
.BI "void clnt_pcreateerror(const char *" s );
.fi
@@ -324,7 +324,7 @@ Used when a
or
.BR clntudp_create ()
call fails.
-.PP
+.P
.nf
.BI "void clnt_perrno(enum clnt_stat " stat );
.fi
@@ -334,7 +334,7 @@ to the condition indicated by
.IR stat .
Used after
.BR callrpc ().
-.PP
+.P
.nf
.BI "clnt_perror(CLIENT *" clnt ", const char *" s );
.fi
@@ -347,7 +347,7 @@ The message is prepended with string
and a colon.
Used after
.BR clnt_call ().
-.PP
+.P
.nf
.BI "char *clnt_spcreateerror(const char *" s );
.fi
@@ -357,7 +357,7 @@ Like
except that it returns a string instead of printing to the standard error.
.IP
Bugs: returns pointer to static data that is overwritten on each call.
-.PP
+.P
.nf
.BI "char *clnt_sperrno(enum clnt_stat " stat );
.fi
@@ -385,7 +385,7 @@ and
.BR clnt_sperrno ()
returns pointer to static data, but the
result will not get overwritten on each call.
-.PP
+.P
.nf
.BI "char *clnt_sperror(CLIENT *" rpch ", const char *" s );
.fi
@@ -397,7 +397,7 @@ except that (like
it returns a string instead of printing to standard error.
.IP
Bugs: returns pointer to static data that is overwritten on each call.
-.PP
+.P
.nf
.BI "CLIENT *clntraw_create(unsigned long " prognum \
", unsigned long " versnum );
@@ -414,7 +414,7 @@ corresponding RPC server should live in the same address space; see
This allows simulation of RPC and acquisition of RPC
overheads, such as round trip times, without any kernel interference.
This routine returns NULL if it fails.
-.PP
+.P
.nf
.BI "CLIENT *clnttcp_create(struct sockaddr_in *" addr ,
.BI " unsigned long " prognum ", unsigned long " versnum ,
@@ -450,7 +450,7 @@ and
.IR recvsz ;
values of zero choose suitable defaults.
This routine returns NULL if it fails.
-.PP
+.P
.nf
.BI "CLIENT *clntudp_create(struct sockaddr_in *" addr ,
.BI " unsigned long " prognum ", unsigned long " versnum ,
@@ -485,7 +485,7 @@ The total time for the call to time out is specified by
Warning: since UDP-based RPC messages can hold only up to 8 Kbytes
of encoded data, this transport cannot be used for procedures
that take large arguments or return huge results.
-.PP
+.P
.nf
.BI "CLIENT *clntudp_bufcreate(struct sockaddr_in *" addr ,
.BI " unsigned long " prognum ", unsigned long " versnum ,
@@ -520,7 +520,7 @@ The total time for the call to time out is specified by
.IP
This allows the user to specify the maximum packet
size for sending and receiving UDP-based RPC messages.
-.PP
+.P
.nf
.BI "void get_myaddress(struct sockaddr_in *" addr );
.fi
@@ -531,7 +531,7 @@ without consulting the library routines that deal with
.IR /etc/hosts .
The port number is always set to
.BR htons(PMAPPORT) .
-.PP
+.P
.nf
.BI "struct pmaplist *pmap_getmaps(struct sockaddr_in *" addr );
.fi
@@ -545,7 +545,7 @@ This routine can return NULL.
The command
.I rpcinfo\~\-p
uses this routine.
-.PP
+.P
.nf
.BI "unsigned short pmap_getport(struct sockaddr_in *" addr ,
.BI " unsigned long " prognum ", unsigned long " versnum ,
@@ -574,7 +574,7 @@ service.
In the latter case, the global variable
.I rpc_createerr
contains the RPC status.
-.PP
+.P
.nf
.BI "enum clnt_stat pmap_rmtcall(struct sockaddr_in *" addr ,
.BI " unsigned long " prognum ", unsigned long " versnum ,
@@ -602,7 +602,7 @@ and
This procedure should be used for a \[lq]ping\[rq] and nothing else.
See also
.BR clnt_broadcast ().
-.PP
+.P
.nf
.BI "bool_t pmap_set(unsigned long " prognum ", unsigned long " versnum ,
.BI " int " protocol ", unsigned short " port );
@@ -626,7 +626,7 @@ or
This routine returns one if it succeeds, zero otherwise.
Automatically done by
.BR svc_register ().
-.PP
+.P
.nf
.BI "bool_t pmap_unset(unsigned long " prognum ", unsigned long " versnum );
.fi
@@ -641,7 +641,7 @@ on the machine's
.B portmap
service.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "int registerrpc(unsigned long " prognum ", unsigned long " versnum ,
.BI " unsigned long " procnum ", char *(*" procname ")(char *),"
@@ -671,7 +671,7 @@ Warning: remote procedures registered in this form
are accessed using the UDP/IP transport; see
.BR svcudp_create ()
for restrictions.
-.PP
+.P
.nf
.BI "struct rpc_createerr " rpc_createerr ;
.fi
@@ -681,7 +681,7 @@ that does not succeed.
Use the routine
.BR clnt_pcreateerror ()
to print the reason why.
-.PP
+.P
.nf
.BI "void svc_destroy(SVCXPRT *" xprt );
.fi
@@ -695,7 +695,7 @@ itself.
Use of
.I xprt
is undefined after calling this routine.
-.PP
+.P
.nf
.BI "fd_set " svc_fdset ;
.fi
@@ -712,7 +712,7 @@ This variable is read-only (do not pass its address to
yet it may change after calls to
.BR svc_getreqset ()
or any creation routines.
-.PP
+.P
.nf
.BI "int " svc_fds ;
.fi
@@ -722,7 +722,7 @@ Similar to
but limited to 32 file descriptors.
This interface is obsoleted by
.BR svc_fdset .
-.PP
+.P
.nf
.BI "svc_freeargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in );
.fi
@@ -732,7 +732,7 @@ system when it decoded the arguments to a service procedure using
.BR svc_getargs ().
This routine returns 1 if the results were successfully freed,
and zero otherwise.
-.PP
+.P
.nf
.BI "svc_getargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in );
.fi
@@ -746,7 +746,7 @@ is the address where the arguments will be placed;
.I inproc
is the XDR routine used to decode the arguments.
This routine returns one if decoding succeeds, and zero otherwise.
-.PP
+.P
.nf
.BI "struct sockaddr_in *svc_getcaller(SVCXPRT *" xprt );
.fi
@@ -754,7 +754,7 @@ This routine returns one if decoding succeeds, and zero otherwise.
The approved way of getting the network address of the caller
of a procedure associated with the RPC service transport handle,
.IR xprt .
-.PP
+.P
.nf
.BI "void svc_getreqset(fd_set *" rdfds );
.fi
@@ -771,7 +771,7 @@ is the resultant read file descriptor bit mask.
The routine returns when all sockets associated with the value of
.I rdfds
have been serviced.
-.PP
+.P
.nf
.BI "void svc_getreq(int " rdfds );
.fi
@@ -781,7 +781,7 @@ Similar to
but limited to 32 file descriptors.
This interface is obsoleted by
.BR svc_getreqset ().
-.PP
+.P
.nf
.BI "bool_t svc_register(SVCXPRT *" xprt ", unsigned long " prognum ,
.BI " unsigned long " versnum ,
@@ -827,7 +827,7 @@ dispatch(struct svc_req *request, SVCXPRT *xprt);
The
.BR svc_register ()
routine returns one if it succeeds, and zero otherwise.
-.PP
+.P
.nf
.B "void svc_run(void);"
.fi
@@ -840,7 +840,7 @@ when one arrives.
This procedure is usually waiting for a
.BR select (2)
system call to return.
-.PP
+.P
.nf
.BI "bool_t svc_sendreply(SVCXPRT *" xprt ", xdrproc_t " outproc \
", char *" out );
@@ -856,7 +856,7 @@ is the XDR routine which is used to encode the results; and
.I out
is the address of the results.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "void svc_unregister(unsigned long " prognum ", unsigned long " versnum );
.fi
@@ -866,14 +866,14 @@ Remove all mapping of the double
to dispatch routines, and of the triple
.RI [ prognum , versnum , * ]
to port number.
-.PP
+.P
.nf
.BI "void svcerr_auth(SVCXPRT *" xprt ", enum auth_stat " why );
.fi
.IP
Called by a service dispatch routine that refuses to perform
a remote procedure call due to an authentication error.
-.PP
+.P
.nf
.BI "void svcerr_decode(SVCXPRT *" xprt );
.fi
@@ -882,21 +882,21 @@ Called by a service dispatch routine that cannot successfully
decode its parameters.
See also
.BR svc_getargs ().
-.PP
+.P
.nf
.BI "void svcerr_noproc(SVCXPRT *" xprt );
.fi
.IP
Called by a service dispatch routine that does not implement
the procedure number that the caller requests.
-.PP
+.P
.nf
.BI "void svcerr_noprog(SVCXPRT *" xprt );
.fi
.IP
Called when the desired program is not registered with the RPC package.
Service implementors usually do not need this routine.
-.PP
+.P
.nf
.BI "void svcerr_progvers(SVCXPRT *" xprt ", unsigned long " low_vers ,
.BI " unsigned long " high_vers );
@@ -905,7 +905,7 @@ Service implementors usually do not need this routine.
Called when the desired version of a program is not registered
with the RPC package.
Service implementors usually do not need this routine.
-.PP
+.P
.nf
.BI "void svcerr_systemerr(SVCXPRT *" xprt );
.fi
@@ -914,7 +914,7 @@ Called by a service dispatch routine when it detects a system
error not covered by any particular protocol.
For example, if a service can no longer allocate storage,
it may call this routine.
-.PP
+.P
.nf
.BI "void svcerr_weakauth(SVCXPRT *" xprt );
.fi
@@ -923,7 +923,7 @@ Called by a service dispatch routine that refuses to perform
a remote procedure call due to insufficient authentication parameters.
The routine calls
.BR "svcerr_auth(xprt, AUTH_TOOWEAK)" .
-.PP
+.P
.nf
.BI "SVCXPRT *svcfd_create(int " fd ", unsigned int " sendsize ,
.BI " unsigned int " recvsize );
@@ -937,7 +937,7 @@ and
.I recvsize
indicate sizes for the send and receive buffers.
If they are zero, a reasonable default is chosen.
-.PP
+.P
.nf
.B SVCXPRT *svcraw_create(void);
.fi
@@ -950,7 +950,7 @@ so the corresponding RPC client should live in the same address space; see
This routine allows simulation of RPC and acquisition of RPC
overheads (such as round trip times), without any kernel interference.
This routine returns NULL if it fails.
-.PP
+.P
.nf
.BI "SVCXPRT *svctcp_create(int " sock ", unsigned int " send_buf_size ,
.BI " unsigned int " recv_buf_size );
@@ -974,7 +974,7 @@ This routine returns NULL if it fails.
Since TCP-based RPC uses buffered I/O,
users may specify the size of buffers; values of zero
choose suitable defaults.
-.PP
+.P
.nf
.BI "SVCXPRT *svcudp_bufcreate(int " sock ", unsigned int " sendsize ,
.BI " unsigned int " recosize );
@@ -998,7 +998,7 @@ This routine returns NULL if it fails.
.IP
This allows the user to specify the maximum packet size for sending and
receiving UDP-based RPC messages.
-.PP
+.P
.nf
.BI "SVCXPRT *svcudp_create(int " sock );
.fi
@@ -1007,7 +1007,7 @@ This call is equivalent to
.I svcudp_bufcreate(sock,SZ,SZ)
for some default size
.IR SZ .
-.PP
+.P
.nf
.BI "bool_t xdr_accepted_reply(XDR *" xdrs ", struct accepted_reply *" ar );
.fi
@@ -1015,7 +1015,7 @@ for some default size
Used for encoding RPC reply messages.
This routine is useful for users who wish to generate
RPC-style messages without using the RPC package.
-.PP
+.P
.nf
.BI "bool_t xdr_authunix_parms(XDR *" xdrs ", struct authunix_parms *" aupp );
.fi
@@ -1024,7 +1024,7 @@ Used for describing UNIX credentials.
This routine is useful for users
who wish to generate these credentials without using the RPC
authentication package.
-.PP
+.P
.nf
.BI "void xdr_callhdr(XDR *" xdrs ", struct rpc_msg *" chdr );
.fi
@@ -1032,7 +1032,7 @@ authentication package.
Used for describing RPC call header messages.
This routine is useful for users who wish to generate
RPC-style messages without using the RPC package.
-.PP
+.P
.nf
.BI "bool_t xdr_callmsg(XDR *" xdrs ", struct rpc_msg *" cmsg );
.fi
@@ -1040,7 +1040,7 @@ RPC-style messages without using the RPC package.
Used for describing RPC call messages.
This routine is useful for users who wish to generate RPC-style
messages without using the RPC package.
-.PP
+.P
.nf
.BI "bool_t xdr_opaque_auth(XDR *" xdrs ", struct opaque_auth *" ap );
.fi
@@ -1048,7 +1048,7 @@ messages without using the RPC package.
Used for describing RPC authentication information messages.
This routine is useful for users who wish to generate
RPC-style messages without using the RPC package.
-.PP
+.P
.nf
.BI "bool_t xdr_pmap(XDR *" xdrs ", struct pmap *" regs );
.fi
@@ -1060,7 +1060,7 @@ This routine is useful for users who wish to generate
these parameters without using the
.B pmap
interface.
-.PP
+.P
.nf
.BI "bool_t xdr_pmaplist(XDR *" xdrs ", struct pmaplist **" rp );
.fi
@@ -1070,7 +1070,7 @@ This routine is useful for users who wish to generate
these parameters without using the
.B pmap
interface.
-.PP
+.P
.nf
.BI "bool_t xdr_rejected_reply(XDR *" xdrs ", struct rejected_reply *" rr );
.fi
@@ -1078,7 +1078,7 @@ interface.
Used for describing RPC reply messages.
This routine is useful for users who wish to generate
RPC-style messages without using the RPC package.
-.PP
+.P
.nf
.BI "bool_t xdr_replymsg(XDR *" xdrs ", struct rpc_msg *" rmsg );
.fi
@@ -1086,7 +1086,7 @@ RPC-style messages without using the RPC package.
Used for describing RPC reply messages.
This routine is useful for users who wish to generate
RPC style messages without using the RPC package.
-.PP
+.P
.nf
.BI "void xprt_register(SVCXPRT *" xprt );
.fi
@@ -1096,7 +1096,7 @@ they should register themselves with the RPC service package.
This routine modifies the global variable
.IR svc_fds .
Service implementors usually do not need this routine.
-.PP
+.P
.nf
.BI "void xprt_unregister(SVCXPRT *" xprt );
.fi
@@ -1181,12 +1181,11 @@ T{
.BR xprt_unregister ()
T} Thread safety MT-Safe
.TE
-.sp 1
.SH SEE ALSO
.\" We don't have an rpc_secure.3 page in the set at the moment -- MTK, 19 Sep 05
.\" .BR rpc_secure (3),
.BR xdr (3)
-.PP
+.P
The following manuals:
.RS
Remote Procedure Calls: Protocol Specification
@@ -1196,7 +1195,7 @@ Remote Procedure Call Programming Guide
rpcgen Programming Guide
.br
.RE
-.PP
+.P
.IR "RPC: Remote Procedure Call Protocol Specification" ,
RFC\ 1050, Sun Microsystems, Inc.,
USC-ISI.