.\" @(#)rpc.3n 2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI
.TH RPC 3N "16 February 1988"
rpc \- library routines for remote procedure calls
.SH 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
Finally, the procedure call returns to the client.
Routines that are used for Secure RPC (DES authentication) are described in
Secure RPC can be used only if DES encryption is available.
A macro that destroys the authentication information associated with
Destruction usually involves deallocation of private data
is undefined after calling
authentication handle that passes nonusable authentication
information with each remote procedure call. This is the
default authentication used by
authunix_create(host, uid, gid, len, aup_gids)
int uid, gid, len, *aup.gids;
authentication handle that contains
authentication information.
is the name of the machine on which the information was
is the user's current group
refer to a counted array of groups to which the user belongs.
It is easy to impersonate a user.
authunix_create_default(\|)
with the appropriate parameters.
callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out)
u_long prognum, versnum, procnum;
xdrproc_t inproc, outproc;
Call the remote procedure associated with
is the address of the procedure's argument(s), and
is the address of where to place the result(s);
is used to encode the procedure's parameters, and
is used to decode the procedure's results.
This routine returns zero if it succeeds, or the value of
cast to an integer if it fails.
is handy for translating failure statuses into messages.
Warning: calling remote procedures with this routine
You do not have control of timeouts or authentication using
clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresult)
u_long prognum, versnum, procnum;
xdrproc_t inproc, outproc;
except the call message is broadcast to all locally
connected broadcast nets. Each time it receives a
response, this routine calls
struct sockaddr_in *addr;
except that the remote procedure's output is decoded there;
points to the address of the machine that sent the results.
waits for more replies; otherwise it returns with appropriate
Warning: broadcast sockets are limited in size to the
maximum transfer unit of the data link. For ethernet,
this value is 1500 bytes.
clnt_call(clnt, procnum, inproc, in, outproc, out, tout)
xdrproc_t inproc, outproc;
A macro that calls the remote procedure
associated with the client handle,
which is obtained with an
client creation routine such as
is the address of the procedure's argument(s), and
is the address of where to place the result(s);
is used to encode the procedure's parameters, and
is used to decode the procedure's results;
is the time allowed for results to come back.
A macro that destroys the client's
handle. Destruction usually involves deallocation
of private data structures, including
is undefined after calling
library opened the associated socket, it will close it also.
Otherwise, the socket remains open.
clnt_create(host, prog, vers, proto)
Generic client creation routine.
identifies the name of the remote host where the server
indicates which kind of transport protocol to use. The
currently supported values for this field are \(lqudp\(rq
Default timeouts are set, but can be modified 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.
clnt_control(cl, req, info)
A macro used to change or retrieve various information
indicates the type of operation, and
is a pointer to the information. For both
and their argument types and what they do are:
.SM CLSET_TIMEOUT\s0 struct timeval set total timeout
.SM CLGET_TIMEOUT\s0 struct timeval get total timeout
Note: if you set the timeout using
the timeout parameter passed to
will be ignored in all future calls.
.SM CLGET_SERVER_ADDR\s0 struct sockaddr_in get server's address
The following operations are valid for
.ta +2.0i ; +2.0i ; +2.0i
.SM CLSET_RETRY_TIMEOUT\s0 struct timeval set the retry timeout
.SM CLGET_RETRY_TIMEOUT\s0 struct timeval get the retry timeout
The retry timeout is the time that
waits for the server to reply before
retransmitting the request.
clnt_freeres(clnt, outproc, out)
A macro that frees any data allocated by the
system when it decoded the results of an
is the address of the results, and
routine describing the results.
This routine returns one if the results were successfully
A macro that copies the error structure out of the client
to the structure at address
Print a message to standard error indicating
handle could not be created.
The message is prepended with string
Print a message to standard error corresponding
to the condition indicated by
Print a message to standard error indicating why an
is the handle used to do the call.
The message is prepended with string
.BR clnt_pcreateerror(\|) ,
except that it returns a string
instead of printing to the standard error.
Bugs: returns pointer to static data that is overwritten
Take the same arguments as
but instead of sending a message to the standard error
call failed, return a pointer to a string which contains
the message. The string ends with a
if the program does not have a standard error (as a program
running as a server quite likely does not), or if the
does not want the message to be output with
or if a message format different than that supported by
.BR clnt_spcreaterror(\|) ,
returns pointer to static data, but the
result will not get overwritten on each call.
it returns a string instead of printing to standard error.
Bugs: returns pointer to static data that is overwritten
clntraw_create(prognum, versnum)
This routine creates a toy
client for the remote program
The transport used to pass messages to the service is
actually a buffer within the process's address space, so the
server should live in the same address space; see
This allows simulation of
overheads, such as round trip times, without any
kernel interference. This routine returns
clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz)
struct sockaddr_in *addr;
client for the remote program
as a transport. The remote program is located at Internet
.\"The following in-line font conversion is necessary for the hyphen indicator
is zero, then it is set to the actual port that the remote
program is listening on (the remote
service is consulted for this information). The parameter
then this routine opens a new one and sets
the user may specify the size of the send and receive buffers
values of zero choose suitable defaults.
clntudp_create(addr, prognum, versnum, wait, sockp)
struct sockaddr_in *addr;
client for the remote program
as a transport. The remote program is located at Internet
is zero, then it is set to actual port that the remote
program is listening on (the remote
service is consulted for this information). The parameter
then this routine opens a new one and sets
transport resends the call message in intervals of
time until a response is received or until the call times
The total time for the call to time out is specified by
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.
clntudp_bufcreate(addr, prognum, versnum, wait, sockp, sendsize, recosize)
struct sockaddr_in *addr;
client for the remote program
as a transport. The remote program is located at Internet
is zero, then it is set to actual port that the remote
program is listening on (the remote
service is consulted for this information). The parameter
then this routine opens a new one and sets
transport resends the call message in intervals of
time until a response is received or until the call times
The total time for the call to time out is specified by
This allows the user to specify the maximun packet size for sending and receiving
struct sockaddr_in *addr;
without consulting the library routines that deal with
The port number is always set to
.BR htons(\s-1PMAPPORT\s0) .
struct sockaddr_in *addr;
service, which returns a list of the current
pmap_getport(addr, prognum, versnum, protocol)
struct sockaddr_in *addr;
u_long prognum, versnum, protocol;
service, which returns the port number
on which waits a service that supports program number
and speaks the transport protocol associated with
A return value of zero means that the mapping does not exist
system failured to contact the remote
service. In the latter case, the global variable
pmap_rmtcall(addr, prognum, versnum, procnum, inproc, in, outproc, out, tout, portp)
struct sockaddr_in *addr;
u_long prognum, versnum, procnum;
xdrproc_t inproc, outproc;
call on your behalf to a procedure on that host.
will be modified to the program's port number if the
succeeds. The definitions of other parameters are discussed
This procedure should be used for a \(lqping\(rq and nothing
pmap_set(prognum, versnum, protocol, port)
u_long prognum, versnum, protocol;
service, which establishes a mapping between the triple
.RI [ prognum , versnum , protocol\fR]
This routine returns one if it succeeds, zero otherwise.
pmap_unset(prognum, versnum)
service, which destroys all mapping between the triple
.RI [ prognum , versnum , *\fR]
service. This routine returns one if it succeeds, zero
registerrpc(prognum, versnum, procnum, procname, inproc, outproc)
u_long prognum, versnum, procnum;
xdrproc_t inproc, outproc;
service package. If a request arrives for program
is called with a pointer to its parameter(s);
should return a pointer to its static result(s);
is used to decode the parameters while
is used to encode the results.
This routine returns zero if the registration succeeded, \-1
Warning: remote procedures registered in this form
struct rpc_createerr rpc_createerr;
A global variable whose value is set by any
that does not succeed. Use the routine
A macro that destroys the
service transport handle,
Destruction usually involves deallocation
of private data structures, including
is undefined after calling this routine.
A global variable reflecting the
read file descriptor bit mask; it is suitable as a parameter
system call. This is only of interest
if a service implementor does not call
but rather does his own asynchronous event processing.
This variable is read-only (do not pass its address to
yet it may change after calls to
or any creation routines.
but limited to 32 descriptors. This
interface is obsoleted by
svc_freeargs(xprt, inproc, in)
A macro that frees any data allocated by the
system when it decoded the arguments to a service procedure
This routine returns 1 if the results were successfully
svc_getargs(xprt, inproc, in)
A macro that decodes the arguments of an
service transport handle,
is the address where the arguments will be placed;
routine used to decode the arguments.
This routine returns one if decoding succeeds, and zero
The approved way of getting the network address of the caller
of a procedure associated with the
service transport handle,
This routine is only of interest if a service implementor
but instead implements custom asynchronous event processing.
system call has determined that an
request has arrived on some
is the resultant read file descriptor bit mask.
The routine returns when all sockets associated with the
but limited to 32 descriptors. This interface is obsoleted by
svc_register(xprt, prognum, versnum, dispatch, protocol)
with the service dispatch procedure,
is zero, the service is not registered with the
is non-zero, then a mapping of the triple
.RI [ prognum , versnum , protocol\fR]
is established with the local
routine returns one if it succeeds, and zero otherwise.
This routine never returns. It waits for
requests to arrive, and calls the appropriate service
when one arrives. This procedure is usually waiting for a
svc_sendreply(xprt, outproc, out)
service's dispatch routine to send the results of a
remote procedure call. The parameter
is the request's associated transport handle;
routine which is used to encode the results; and
is the address of the results.
This routine returns one if it succeeds, zero otherwise.
svc_unregister(prognum, versnum)
Remove all mapping of the double
.RI [ prognum , versnum ]
to dispatch routines, and of the triple
.RI [ prognum , versnum , *\fR]
Called by a service dispatch routine that refuses to perform
a remote procedure call due to an authentication error.
Called by a service dispatch routine that cannot successfully
decode its parameters. See also
Called by a service dispatch routine that does not implement
the procedure number that the caller requests.
Called when the desired program is not registered with the
package. Service implementors usually do not need this routine.
Called when the desired version of a program is not registered
package. Service implementors usually do not need this routine.
Called by a service dispatch routine when it detects a system
not covered by any particular protocol.
For example, if a service can no longer allocate storage,
it may call this routine.
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, \s-1AUTH_TOOWEAK\s0)" .
This routine creates a toy
service transport, to which it returns a pointer. The
is really a buffer within the process's address space,
client should live in the same
This routine allows simulation of
overheads (such as round trip times), without any kernel
svctcp_create(sock, send_buf_size, recv_buf_size)
u_int send_buf_size, recv_buf_size;
service transport, to which it returns a pointer.
The transport is associated with the socket
in which case a new socket is created.
If the socket is not bound to a local
port, then this routine binds it to an arbitrary port. Upon
is the transport's socket descriptor, and
is the transport's port number.
users may specify the size of buffers; values of zero
choose suitable defaults.
svcfd_create(fd, sendsize, recvsize)
Create a service on top of any open descriptor. Typically,
descriptor is a connected socket for a stream protocol such
indicate sizes for the send and receive buffers. If they are
zero, a reasonable default is chosen.
svcudp_bufcreate(sock, sendsize, recosize)
service transport, to which it returns a pointer.
The transport is associated with the socket
in which case a new socket is created.
If the socket is not bound to a local
port, then this routine binds it to an arbitrary port. Upon
is the transport's socket descriptor, and
is the transport's port number.
This allows the user to specify the maximun packet size for sending and
xdr_accepted_reply(xdrs, ar)
struct accepted_reply *ar;
reply messages. This routine is useful for users who
messages without using the
xdr_authunix_parms(xdrs, aupp)
struct authunix_parms *aupp;
credentials. This routine is useful for users
who wish to generate these credentials without using the
This routine is useful for users who wish to generate
messages without using the
This routine is useful for users who wish to generate
messages without using the
xdr_opaque_auth(xdrs, ap)
authentication information messages.
This routine is useful for users who wish to generate
messages without using the
Used for describing parameters to various
This routine is useful for users who wish to generate
these parameters without using the
Used for describing a list of port mappings, externally.
This routine is useful for users who wish to generate
these parameters without using the
xdr_rejected_reply(xdrs, rr)
struct rejected_reply *rr;
This routine is useful for users who wish to generate
messages without using the
This routine is useful for users who wish to generate
style messages without using the
service transport handles are created,
they should register themselves with the
This routine modifies the global variable
Service implementors usually do not need this routine.
service transport handle is destroyed,
it should unregister itself with the
This routine modifies the global variable
Service implementors usually do not need this routine.
Remote Procedure Calls: Protocol Specification
Remote Procedure Call Programming Guide
.IR "\s-1RPC\s0: Remote Procedure Call Protocol Specification" ,
.SM RFC1050, Sun Microsystems, Inc.,