 |
Index for Section 3 |
|
 |
Alphabetical listing for R |
|
rpc(3)
NAME
rpc, rpc_functions, auth_destroy, authnone_create, authunix_create,
authunix_create_default, callrpc,clnt_broadcast, clnt_call, clnt_create,
clnt_control, clnt_destroy, clnt_freeres, clnt_geterr, clnt_pcreateerror,
clnt_perrno, clnt_perror, clnt_spcreateerror, clnt_sperrno, clnt_sperror,
clntraw_create, clnttcp_create, clntudp_create, get_myaddress, getnetname,
host2netname, netname2host, netname2user, pmap_getmaps, pmap_getport,
pmap_rmtcall, pmap_set, pmap_unset, registerrpc, rpc_createrr, svc_destroy,
svc_fdset, svc_freeargs, svc_getargs, svc_getcaller, svc_getreq,
svc_getreqset, svc_register, svc_run, svc_sendreply, svc_unregister,
svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers,
svcerr_systemerr, svcerr_weakauth, svcfd_create, svcraw_create,
svctcp_create, svcudp_create, usr2netname, xprt_register, xprt_unregister -
Library routines for ONC remote procedure calls
SYNOPSIS
#include <rpc/rpc.h>
void
auth_destroy(auth)
AUTH *auth;
A macro that destroys the authentication information associated with
auth. Destruction usually involves deallocation of private data
structures. The use of auth is undefined after calling auth_destroy().
AUTH *
authnone_create()
Creates and returns an RPC authentication handle that passes nonusable
authentication information with each remote procedure call. This is
the default authentication used by ONC RPC.
AUTH *
authunix_create(host, uid, gid, len, aup_gids)
char *host;
int uid, gid, len, *aup.gids;
Creates and returns an ONC RPC authentication handle that contains
authentication information. The host parameter is the name of the
machine on which the information was created; uid is the user's user
ID ; gid is the user's current group ID ; len and aup_gids refer to a
counted array of groups to which the user belongs.
AUTH *
authunix_create_default()
Calls authunix_create() with the appropriate parameters.
callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out)
char *host;
u_int prognum, versnum, procnum;
char *in, *out;
xdrproc_t inproc, outproc;
Calls the remote procedure associated with prognum, versnum, and
procnum on the machine host. The in parameter is the address of the
procedure's argument(s), and out is the address of where to place the
result(s); inproc is used to encode the procedure's parameters, and
outproc is used to decode the procedure's results. This routine
returns zero if it succeeds, or the value of enum clnt_stat cast to an
integer if it fails. The clnt_perrno() routine is handy for
translating failure statuses into messages.
Warning: calling remote procedures with this routine uses UDP/IP as a
transport; see clntudp_create() for restrictions. You do not have
control of timeouts or authentication using this routine.
enum clnt_stat
clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out,
eachresult)
u_int prognum, versnum, procnum;
char *in, *out;
xdrproc_t inproc, outproc;
resultproc_t eachresult;
Like callrpc(), except the call message is broadcast to all locally
connected broadcast nets. Each time it receives a response, this
routine calls the eachresult() routine, which has the following form:
eachresult(out, addr)
char *out;
struct sockaddr_in *addr;
The out parameter is the same as the out parameter passed to
clnt_broadcast(), except that the remote procedure's output is decoded
there; addr points to the address of the machine that sent the
results.
If eachresult() returns zero, clnt_broadcast() waits for more replies;
otherwise it returns with appropriate status. If eachresult() is NULL
clnt_broadcast() returns without waiting for any replies.
Warning: broadcast sockets are limited in size to the maximum transfer
unit of the data link. For Ethernet, the caller's argument size should
not exceed 1400 bytes.
enum clnt_stat
clnt_call(clnt, procnum, inproc, in, outproc, out, tout)
CLIENT *clnt;
u_int
procnum;
xdrproc_t inproc, outproc;
char *in, *out;
struct timeval tout;
A macro that calls the remote procedure procnum associated with the
client handle, clnt, which is obtained with an RPC client creation
routine such as clnt_create(). The in parameter is the address of the
procedure's argument(s), and out is the address of where to place the
result(s); inproc is used to encode the procedure's parameters, and
outproc is used to decode the procedure's results; tout is the time
allowed for results to come back.
clnt_destroy(clnt)
CLIENT *clnt;
A macro that destroys the client's RPC handle. Destruction usually
involves deallocation of private data structures, including clnt
itself. Use of clnt is undefined after calling clnt_destroy(). If
the RPC library opened the associated socket, it will close it also.
Otherwise, the socket remains open.
CLIENT *
clnt_create(host, prog, vers, proto)
char *host;
u_int prog, vers;
char *proto;
Generic client creation routine. The host parameter identifies the
name of the remote host where the server is located. The proto
parameter indicates which kind of transport protocol to use. The
currently supported values for this field are udp and tcp. Default
timeouts are set, but can be modified using clnt_control().
Warning: Since UDP-based RPC messages can only hold up to 8 Kbytes of
encoded data, this transport cannot be used for procedures that take
large arguments or return huge results.
bool_t
clnt_control(cl, req, info)
CLIENT *cl;
int req;
char *info;
A macro that is used to change or retrieve various information about a
client object. The req parameter indicates the type of operation, and
info is a pointer to the information. For UDP and TCP, req has the
following supported values, argument types, and purposes:
CLSET_TIMEOUT struct timeval set total timeout
CLGET_TIMEOUT struct timeval get total timeout
CLGET_FD int get associated socket
CLSET_FD_CLOSE void
close socket on
clnt_destroy()
CLSET_FD_NOCLOSE void
leave socket open on
clnt_destroy()
Note: if you set the timeout using clnt_control(), the timeout
parameter passed to clnt_call() will be ignored in all future calls.
CLGET_SERVER_ADDR struct sockaddr
get server's
address
The following operations are valid for UDP only:
CLSET_RETRY_TIMEOUT struct timeval
set the retry
timeout
CLGET_RETRY_TIMEOUT struct timeval
get the retry
timeout
The retry timeout is the time that UDP RPC waits for the server to
reply before retransmitting the request.
clnt_freeres(clnt, outproc, out)
CLIENT *clnt;
xdrproc_t outproc;
char *out;
A macro that frees any data allocated by the RPC/XDR system when it
decoded the results of an RPC call. The out parameter is the address
of the results, and outproc is the XDR routine describing the results.
This routine returns one (1) if the results were successfully freed,
and zero (0) otherwise.
void
clnt_geterr(clnt, errp)
CLIENT *clnt;
struct rpc_err *errp;
A macro that copies the error structure out of the client handle to
the structure at address errp.
void
clnt_pcreateerror(s)
char *s;
Prints a message to standard error indicating why a client RPC handle
could not be created. The message is prepended with string s and a
colon. Used when a clnt_create(), clntraw_create(), clnttcp_create(),
or clntudp_create() call fails.
void
clnt_perrno(stat)
enum clnt_stat stat;
Prints a message to standard error corresponding to the condition
indicated by stat. Used after callrpc().
clnt_perror(clnt, s)
CLIENT *clnt;
char *s;
Prints a message to standard error indicating why an RPC call failed;
clnt is the handle used to do the call. The message is prepended with
string s and a colon. Used after clnt_call().
char *
clnt_spcreateerror
char *s;
Like clnt_pcreateerror(), except that it returns a string instead of
printing to the standard error.
Note: returns pointer to static data that is overwritten on each call.
char *
clnt_sperrno(stat)
enum clnt_stat stat;
Takes the same arguments as clnt_perrno(), but instead of sending a
message to the standard error indicating why an RPC call failed,
returns a pointer to a string which contains the message. The string
ends with a NEWLINE.
clnt_sperrno() is used instead of clnt_perrno() if the program does
not have a standard error (as a program running as a server quite
likely does not), or if the programmer does not want the message to be
output with printf, or if a message format different than that
supported by clnt_perrno() is to be used.
Note: unlike clnt_sperror() and clnt_spcreaterror(), clnt_sperrno()
does not return pointer to static data so the result will not be
overwritten on each call.
char *
clnt_sperror(rpch, s)
CLIENT *rpch;
char *s;
Like clnt_perror(), except that (like clnt_sperrno()) it returns a
string instead of printing to standard error.
Note: returns pointer to static data that is overwritten on each call.
CLIENT *
clntraw_create(prognum, versnum)
u_int prognum, versnum;
Creates a toy RPC client for the remote program prognum, version
versnum. The transport used to pass messages to the service is
actually a buffer within the process's address space, so the
corresponding RPC server should live in the same address space; see
svcraw_create(). 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.
CLIENT *
clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz)
struct sockaddr_in *addr;
u_int prognum, versnum;
int *sockp;
u_int sendsz, recvsz;
Creates an RPC client for the remote program prognum, version versnum;
the client uses TCP/IP as a transport. The remote program is located
at Internet address *addr. If addr->sin_port is zero, then it is set
to the actual port that the remote program is listening on (the remote
portmap service is consulted for this information). The parameter
sockp is a socket; if it is RPC_ANYSOCK, then this routine opens a new
socket and sets sockp. Since TCP-based RPC uses buffered I/O , the
user may specify the size of the send and receive buffers with the
sendsz and recvsz parameters; values of zero choose suitable defaults.
This routine returns NULL if it fails.
CLIENT *
clntudp_create(addr, prognum, versnum, wait, sockp)
struct sockaddr_in *addr;
u_int prognum, versnum;
struct timeval wait;
int *sockp;
Creates an RPC client for the remote program prognum, version versnum;
the client uses use UDP/IP as a transport. The remote program is
located at Internet address addr. If addr->sin_port is zero, then it
is set to actual port that the remote program is listening on (the
remote portmap service is consulted for this information). The
parameter sockp is a socket; if it is RPC_ANYSOCK, then this routine
opens a new socket and sets sockp. The UDP transport resends the call
message in intervals of wait time until a response is received or
until the call times out. The total time for the call to time out is
specified by clnt_call().
Warning: since UDP-based RPC messages can only hold up to 8 Kbytes of
encoded data, this transport cannot be used for procedures that take
large arguments or return huge results.
void
get_myaddress(addr)
struct sockaddr_in *addr;
Places the machine's IP address into *addr, without consulting the
library routines that deal with /etc/hosts. The port number is always
set to htons(PMAPPORT).
getnetname(name)
char name[MAXNETNAMELEN];
Installs the unique, operating-system independent network name of the
caller in the fixed-length array name. Returns TRUE if it succeeds
and FALSE if it fails.
host2netname(name, host, domain)
char *name;
char *host;
char *domain;
Converts from a domain-specific host name to an operating-system
independent network name. Return TRUE if it succeeds and FALSE if it
fails. Inverse of netname2host().
netname2host(name, host, hostlen)
char *name;
char *host;
int hostlen;
Converts from an operating-system independent network name to a
domain-specific host name. Returns TRUE if it succeeds and FALSE if it
fails. Inverse of host2netname().
netname2user(name, uidp, gidp, gidlenp, gidlist)
char *name;
int *uidp;
int *gidp;
int *gidlenp;
int *gidlist;
Converts from an operating-system independent network name to a
domain-specific user ID. Returns TRUE if it succeeds and FALSE if it
fails. Inverse of user2netname().
struct pmaplist *
pmap_getmaps(addr)
struct sockaddr_in *addr;
A user interface to the portmap service, which returns a list of the
current RPC program-to-port mappings on the host located at IP address
*addr. This routine can return NULL . The rpcinfo -p command uses
this routine.
u_short
pmap_getport(addr, prognum, versnum, protocol)
struct sockaddr_in *addr;
u_int prognum, versnum, protocol;
A user interface to the portmap service, which returns the port number
on which waits a service that supports program number prognum, version
versnum, and speaks the transport protocol associated with protocol.
The value of protocol is most likely IPPROTO_UDP or IPPROTO_TCP. A
return value of zero means that the mapping does not exist or that the
RPC system failed to contact the remote portmap service. In the
latter case, the global variable rpc_createerr() contains the RPC
status.
enum clnt_stat
pmap_rmtcall(addr, prognum, versnum, procnum, inproc, in, outproc,
out, tout, portp)
struct sockaddr_in *addr;
u_int prognum, versnum, procnum;
char *in, *out;
xdrproc_t inproc, outproc;
struct timeval tout;
u_int *portp;
A user interface to the portmap service, which instructs portmap on
the host at IP address *addr to make an RPC call on your behalf to a
procedure on that host. The *portp parameter will be modified to the
program's port number if the procedure succeeds. The definitions of
other parameters are discussed in callrpc() and clnt_call(). This
procedure should be used for a ping and nothing else. See also
clnt_broadcast().
pmap_set(prognum, versnum, protocol, port)
u_int prognum, versnum, protocol;
u_short port;
A user interface to the portmap service, which establishes a mapping
between the triple [prognum,versnum,protocol] and port on the
machine's portmap service. The value of protocol can be either
IPPROTO_UDP or IPPROTO_TCP. This routine returns one (1) if it
succeeds, zero (0) otherwise. Automatically done by svc_register().
pmap_unset(prognum, versnum)
u_int prognum, versnum;
A user interface to the portmap service, which destroys all mapping
between the triple [prognum,versnum,*] and ports on the machine's
portmap service. This routine returns one (1) if it succeeds, zero (0)
otherwise.
registerrpc(prognum, versnum, procnum, procname, inproc, outproc)
u_int prognum, versnum, procnum;
char *(*procname) () ;
xdrproc_t inproc, outproc;
[Not Thread Safe] Registers procname procedure with the RPC service
package. If a request arrives for prognum program, versnum version,
and procnum procedure, procname is called with a pointer to its
parameter(s); progname should return a pointer to its static
result(s); inproc is used to decode the parameters while outproc is
used to encode the results. This routine returns zero (0) if the
registration succeeded, -1 otherwise.
Warning: remote procedures registered in this form are accessed using
the UDP/IP transport; see svcudp_create() for restrictions.
struct rpc_createerr rpc_createerr;
A global variable whose value is set by any RPC client creation
routine that does not succeed. Use the clnt_pcreateerror() routine to
print the reason for the error.
svc_destroy(xprt)
SVCXPRT *
xprt;
[Not Thread Safe] A macro that destroys the RPC service transport
handle, xprt. Destruction usually involves deallocation of private
data structures, including xprt itself. Use of xprt is undefined
after calling this routine.
fd_set svc_fdset;
A global variable that reflects the RPC service side's read file
descriptor bit mask; it is suitable as a arameter to the select system
call. This is only of interest if a service implementor does not call
svc_run(), but rather does his own asynchronous event processing.
This variable is read-only (do not pass its address to select), yet it
may change after calls to svc_getreqset() or any creation routines.
int svc_fds;
Similar to svc_fdset(), but limited to 32 descriptors. This interface
is obsoleted by svc_fdset().
svc_freeargs(xprt, inproc, in)
SVCXPRT *xprt;
xdrproc_t inproc;
char *in;
[Not Thread Safe] A macro that frees any data allocated by the
RPC/XDR system when it decoded the arguments to a service procedure
using svc_getargs(). This routine returns 1 if the results were
successfully freed, and zero (0) otherwise.
svc_getargs(xprt, inproc, in)
SVCXPRT *xprt;
xdrproc_t inproc;
char *in;
[Not Thread Safe] A macro that decodes the arguments of an RPC
request associated with the RPC service transport handle, xprt. The
in parameter is the address where the arguments will be placed; inproc
is the XDR routine used to decode the arguments. This routine returns
one (1) if decoding succeeds, and zero (0) otherwise.
struct sockaddr_in *
svc_getcaller(xprt)
SVCXPRT *xprt;
[Not Thread Safe] The approved way of getting the network address of
the caller of a procedure associated with the RPC service transport
handle, xprt.
svc_getreq(rdfds)
int rdfds;
[Not Thread Safe] Similar to svc_getreqset(), but limited to 32
descriptors. This interface is obsoleted by svc_getreqset().
svc_getreqset(rdfds)
fd_set *rdfds;
[Not Thread Safe] This routine is only of interest if a service
implementor does not call svc_run(), but instead implements custom
asynchronous event processing. It is called when the select system
call has determined that an RPC request has arrived on some RPC
socket(s) ; rdfds is the resultant read file descriptor bit mask. The
routine returns when all sockets associated with the value of rdfds
have been serviced.
svc_register(xprt, prognum, versnum, dispatch, protocol)
SVCXPRT *xprt;
u_int prognum, versnum;
void (*dispatch) ();
int protocol;
[Not Thread Safe] Associates prognum and versnum with the service
dispatch procedure, dispatch. If protocol is zero, the service is not
registered with the portmap service. If protocol is non-zero, then a
mapping of the triple [prognum, versnum, protocol] to xprt->xp_port is
established with the local portmap service (generally protocol is
zero, IPPROTO_UDP or IPPROTO_TCP ). The dispatch procedure has the
following form:
dispatch(request, xprt)
struct svc_req *request;
SVCXPRT *xprt;
The svc_register() routine returns one (1) if it succeeds, and zero
(0) otherwise.
svc_run()
[Not Thread Safe] This routine waits for RPC requests to arrive, and
calls the appropriate service procedure using svc_getreq() when one
arrives. This procedure is usually waiting for a select() system call
to return.
svc_sendreply(xprt, outproc, out)
SVCXPRT *xprt;
xdrproc_t outproc;
char *out;
[Not Thread Safe] Called by an RPC service's dispatch routine to
send the results of a remote procedure call. The xprt parameter is
the request's associated transport handle; outproc is the XDR routine
which is used to encode the results; and out is the address of the
results. This routine returns one (1) if it succeeds, zero (0)
otherwise.
void
svc_unregister(prognum, versnum)
u_int prognum, versnum;
[Not Thread Safe] Removes all mapping of the double
[prognum,versnum] to dispatch routines, and of the triple
[prognum,versnum,*] to port number.
void
svcerr_auth(xprt, why)
SVCXPRT *xprt;
enum auth_stat why;
[Not Thread Safe] Called by a service dispatch routine that refuses
to perform a remote procedure call due to an authentication error.
void
svcerr_decode(xprt)
SVCXPRT *xprt;
[Not Thread Safe] Called by a service dispatch routine that cannot
successfully decode its parameters. See also svc_getargs().
void
svcerr_noproc(xprt)
SVCXPRT *xprt;
[Not Thread Safe] Called by a service dispatch routine that does not
implement the procedure number that the caller requests.
void
svcerr_noprog(xprt)
SVCXPRT *xprt;
[Not Thread Safe] Called when the desired program is not registered
with the RPC package. Service implementors usually do not need this
routine.
void
svcerr_progvers(xprt)
SVCXPRT *xprt;
[Not Thread Safe] Called when the desired version of a program is not
registered with the RPC package. Service implementors usually do not
need this routine.
void
svcerr_systemerr(xprt)
SVCXPRT *xprt;
[Not Thread Safe] 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.
void
svcerr_weakauth(xprt)
SVCXPRT *xprt;
[Not Thread Safe] Called by a service dispatch routine that refuses
to perform a remote procedure call due to insufficient (but correct)
authentication parameters. The routine calls svcerr_auth(xprt,
AUTH_TOOWEAK).
void
svcfd_create(fd, sendsize, recvsize)
int fd;
u_int sendsize;
u_int recvsize;
[Not Thread Safe] Creates a service on top of any open descriptor.
Typically, this descriptor is a connected socket for a stream protocol
such as TCP. The sendsize and recvsize parameters indicate sizes for
the send and receive buffers. If they are zero (0), a reasonable
default is chosen.
SVCXPRT *
svcraw_create()
[Not Thread Safe] Creates a toy RPC service transport, to which it
returns a pointer. The transport is really a buffer within the
process's address space, so the corresponding RPC client should live
in the same address space; see clntraw_create(). 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.
SVCXPRT *
svctcp_create(sock, send_buf_size, recv_buf_size)
int sock;
u_int send_buf_size, recv_buf_size;
[Not Thread Safe] Creates a TCP/IP-based RPC service transport, to
which it returns a pointer. The transport is associated with the sock
socket, which may be RPC_ANYSOCK, in which case a new socket is
created. If the socket is not bound to a local TCP port, then this
routine binds it to an arbitrary port. Upon completion, xprt->xp_sock
is the transport's socket descriptor, and xprt->xp_port is the
transport's port number. 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 (0) choose suitable defaults.
SVCXPRT *
svcudp_create(sock)
int sock;
[Not Thread Safe] Creates a UDP/IP-based RPC service transport, to
which it returns a pointer. The transport is associated with the sock
socket, which may be RPC_ANYSOCK , in which case a new socket is
created. If the socket is not bound to a local UDP port, then this
routine binds it to an arbitrary port. Upon completion, xprt->xp_sock
is the transport's socket descriptor, and xprt->xp_port is the
transport's port number. This routine returns NULL if it fails.
Warning: since UDP-based RPC messages can only hold up to 8 Kbytes of
encoded data, this transport cannot be used for procedures that take
large arguments or return huge results.
user2netname(name, uid, domain)
char *name;
int uid;
char *domain;
Converts from a domain-specific user name to an operating-system
independent network name. Returns TRUE if it succeeds and FALSE if it
fails. Inverse of netname2user().
void
xprt_register(xprt)
SVCXPRT *xprt;
[Not Thread Safe] After RPC service transport handles are created,
they should register themselves with the RPC service package. This
routine modifies the global variable svc_fds(). Service implementors
usually do not need this routine.
void
xprt_unregister(xprt)
SVCXPRT *xprt;
[Not Thread Safe] Before an RPC service transport handle is
destroyed, it should unregister itself with the RPC service package.
This routine modifies the global variable svc_fds(). Service
implementors usually do not need this routine.
DESCRIPTION
These routines allow C programs to make procedure calls on other machines
across the network. 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.
Unless otherwise indicated, the routines described in this reference page
are thread safe (that is, they can be used safely in a multithreaded
environment). Routines that are not thread safe are flagged as such.
RELATED INFORMATION
xdr(3)
Remote Procedure Calls: Protocol Specification-RFC 1050