RPC (3)
library routines for remote procedure calls
SYNOPSIS AND 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.
Routines that are used for Secure RPC (DES authentication) are described in
rpc_secure (3N).
Secure RPC can be used only if DES encryption is available.
B
#include <rpc/rpc.h>
R
t .ne 8
B
void
auth_destroy(auth)
\s-1AUTH\s0 *auth;
R
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(\|) .
t .ne 6
B
\s-1AUTH\s0 *
authnone_create(\|)
R
Create and returns an
authentication handle that passes nonusable authentication
information with each remote procedure call. This is the
default authentication used by
t .ne 10
B
\s-1AUTH\s0 *
authunix_create(host, uid, gid, len, aup_gids)
char *host;
int uid, gid, len, *aup.gids;
R
Create and return an
authentication handle that contains
authentication information.
The parameter
host
is the name of the machine on which the information was
created;
uid
is the user's user
gid
is the user's current group
len
and
aup_gids
refer to a counted array of groups to which the user belongs.
It is easy to impersonate a user.
t .ne 5
B
\s-1AUTH\s0 *
authunix_create_default(\|)
R
Calls
authunix_create(\|)
with the appropriate parameters.
t .ne 13
B
callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out)
char *host;
u_long prognum, versnum, procnum;
char *in, *out;
xdrproc_t inproc, outproc;
R
Call the remote procedure associated with
prognum ,
versnum ,
and
procnum
on the machine,
host .
The parameter
in
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 routine
clnt_perrno(\|)
is handy for translating failure statuses into messages.
Warning: calling remote procedures with this routine
uses
as a transport; see
clntudp_create(\|)
for restrictions.
You do not have control of timeouts or authentication using
this routine.
t .ne 16
B
enum clnt_stat
clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresult)
u_long prognum, versnum, procnum;
char *in, *out;
xdrproc_t inproc, outproc;
resultproc_t eachresult;
R
Like
callrpc(\|) ,
except the call message is broadcast to all locally
connected broadcast nets. Each time it receives a
response, this routine calls
eachresult(\|) ,
whose form is:
eachresult(out, addr)
char *out;
struct sockaddr_in *addr;
R
where
out
is the same as
out
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.
Warning: broadcast sockets are limited in size to the
maximum transfer unit of the data link. For ethernet,
this value is 1500 bytes.
t .ne 13
B
enum clnt_stat
clnt_call(clnt, procnum, inproc, in, outproc, out, tout)
\s-1CLIENT\s0 *clnt;
u_long
procnum;
xdrproc_t inproc, outproc;
char *in, *out;
struct timeval tout;
R
A macro that calls the remote procedure
procnum
associated with the client handle,
clnt ,
which is obtained with an
client creation routine such as
clnt_create(\|) .
The parameter
in
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.
t .ne 7
B
clnt_destroy(clnt)
\s-1CLIENT\s0 *clnt;
R
A macro that destroys the client's
handle. Destruction usually involves deallocation
of private data structures, including
clnt
itself. Use of
clnt
is undefined after calling
clnt_destroy(\|) .
If the
library opened the associated socket, it will close it also.
Otherwise, the socket remains open.
t .ne 10
B
\s-1CLIENT\s0 *
clnt_create(host, prog, vers, proto)
char *host;
u_long prog, vers;
char *proto;
R
Generic client creation routine.
host
identifies the name of the remote host where the server
is located.
proto
indicates which kind of transport protocol to use. The
currently supported values for this field are \(lqudp\(rq
and \(lqtcp\(rq.
Default timeouts are set, but can be modified using
clnt_control(\|) .
Warning: Using
has its shortcomings. Since
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.
t .ne 10
B
bool_t
clnt_control(cl, req, info)
\s-1CLIENT\s0 *cl;
char *info;
R
A macro used to change or retrieve various information
about a client object.
req
indicates the type of operation, and
info
is a pointer to the information. For both
and
the supported values of
req
and their argument types and what they do are:
+2.0i +2.0i +2.0i
Note: if you set the timeout using
clnt_control(\|) ,
the timeout parameter passed to
clnt_call(\|)
will be ignored in all future calls.
The following operations are valid for
only:
+2.0i ; +2.0i ; +2.0i
The retry timeout is the time that
waits for the server to reply before
retransmitting the request.
t .ne 10
B
clnt_freeres(clnt, outproc, out)
\s-1CLIENT\s0 *clnt;
xdrproc_t outproc;
char *out;
R
A macro that frees any data allocated by the
system when it decoded the results of an
call. The
parameter
out
is the address of the results, and
outproc
is the
routine describing the results.
This routine returns one if the results were successfully
freed,
and zero otherwise.
t .ne 6
B
void
clnt_geterr(clnt, errp)
\s-1CLIENT\s0 *clnt;
struct rpc_err *errp;
R
A macro that copies the error structure out of the client
handle
to the structure at address
errp .
t .ne 8
B
void
clnt_pcreateerror(s)
char *s;
R
Print a message to standard error indicating
why a client
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.
t .ne 8
B
void
clnt_perrno(stat)
enum clnt_stat stat;
R
Print a message to standard error corresponding
to the condition indicated by
stat .
Used after
callrpc(\|) .
t .ne 8
B
clnt_perror(clnt, s)
\s-1CLIENT\s0 *clnt;
char *s;
R
Print a message to standard error indicating why an
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(\|) .
t .ne 9
B
char *
clnt_spcreateerror
char *s;
R
Like
clnt_pcreateerror(\|) ,
except that it returns a string
instead of printing to the standard error.
Bugs: returns pointer to static data that is overwritten
on each call.
t .ne 9
B
char *
clnt_sperrno(stat)
enum clnt_stat stat;
R
Take the same arguments as
clnt_perrno(\|) ,
but instead of sending a message to the standard error
indicating why an
call failed, return a pointer to a string which contains
the message. The string ends with a
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(\|)
returns pointer to static data, but the
result will not get overwritten on each call.
t .ne 7
B
char *
clnt_sperror(rpch, s)
\s-1CLIENT\s0 *rpch;
char *s;
R
Like
clnt_perror(\|) ,
except that (like
clnt_sperrno(\|) )
it returns a string instead of printing to standard error.
Bugs: returns pointer to static data that is overwritten
on each call.
t .ne 10
B
\s-1CLIENT\s0 *
clntraw_create(prognum, versnum)
u_long prognum, versnum;
R
This routine creates a toy
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
server should live in the same address space; see
svcraw_create(\|) .
This allows simulation of
and acquisition of
overheads, such as round trip times, without any
kernel interference. This routine returns
if it fails.
t .ne 15
B
\s-1CLIENT\s0 *
clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz)
struct sockaddr_in *addr;
u_long prognum, versnum;
int *sockp;
u_int sendsz, recvsz;
R
This routine creates an
client for the remote program
prognum ,
version
versnum ;
the client uses
as a transport. The remote program is located at Internet
address
*addr .
If
|