rpc(NS)

Syntax

#include <rpc/rpc.h>

void auth_destroy(auth)
AUTH auth;

AUTH authnone_create()

AUTH \(authunix_create(host, uid, gid, len, aup_gids)
char host;
int uid, gid, len, aup_gids;

AUTH authunix_create_default()

callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out)
char host;
ulong prognum, versnum, procnum;
char in, out;
xdrproc_t inproc, outproc;

enum clnt_stat
clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out,
	       eachresult)
ulong prognum, versnum, procnum;
char in, out;
xdrproc_t inproc, outproc;
resultproc_t eachresult;

enum clnt_stat
clnt_call(clnt, procnum, inproc, in, outproc, out, tout)
CLIENT clnt; ulong procnum;
xdrproc_t inproc, outproc;
char in, out;
struct timeval tout;

bool_t clnt_control(cl, req, info)
CLIENT cl;
char info;

CLIENT  clnt_create(host, prog, vers, proto)
char host;
ulong prog, vers;
char proto;

clnt_destroy(clnt)
CLIENT clnt;

clnt_freeres(clnt, outproc, out)
CLIENT clnt;
xdrproc_t outproc;
char out;

void clnt_geterr(clnt, errp)
CLIENT clnt;
struct rpc_err errp;

void clnt_pcreateerror(s)
char s;

void clnt_perrno(stat)
enum clnt_stat stat;

clnt_perror(clnt, s)
CLIENT clnt;
char s;

char clnt_spcreateerror(s)
char s;


char clnt_sperrno(stat)
enum clnt_stat stat;

char clnt_sperror(rpch, s)
CLIENT rpch;
char s;

CLIENT clntraw_create(prognum, versnum)
ulong prognum, versnum;

CLIENT clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz)
struct sockaddr_in *addr;
ulong prognum, versnum;
int sockp;
uint sendsz, recvsz;

CLIENT clntudp_bufcreate(addr, prognum, versnum, wait, \
                             sockp, sendsz, recvsz)
struct sockaddr_in *addr;
u_long prognum, versnum;
struct timeval wait;
int sockp;
u_int sendsz;
u_int recvsz;

CLIENT clntudp_create(addr, pronum, versnum, wait, sockp)
struct sockaddr_in addr;
ulong prognum, versnum;
struct timeval wait;
int sockp;

void get_myaddress(addr)
struct sockaddr_in addr;

struct pmaplist pmap_getmaps(addr)
struct sockaddr_in addr;

ushort pmap_getport(addr, prognum, versnum, protocol)
struct sockaddr_in addr;
ulong prognum, versnum, protocol;

enum clnt_stat
pmap_rmtcall(addr, prognum, versnum, procnum, inproc, in, outproc, out,
	     tout, portp)
struct sockaddr_in addr;
ulong prognum, versnum, procnum;
char in, out;
xdrproc_t inproc, outproc;
struct timeval tout;
ulong portp;

pmap_set(prognum, versnum, protocol, port)
ulong prognum, versnum, protocol;
ushort port;

pmap_unset(prognum, versnum)
ulong prognum, versnum;

registerrpc(prognum, versnum, procnum, procname, inproc, outproc)
ulong prognum, versnum, procnum;
char *(*procname) () ;
xdrproc_t inproc, outproc;

struct rpc_createerr     rpc_createerr;

svc_destroy(xprt)
SVCXPRT xprt;

fd_set svc_fdset;

svc_freeargs(xprt, inproc, in)
SVCXPRT xprt;
xdrproc_t inproc;
char in;

svc_getargs(xprt, inproc, in)
SVCXPRT xprt;
xdrproc_t inproc;
char in;

struct sockaddr_in svc_getcaller(xprt)
SVCXPRT xprt;

svc_getreqset(rdfds)
fd_set rdfds;

svc_register(xprt, prognum, versnum, dispatch, protocol)
SVCXPRT xprt;
ulong prognum, versnum;
void (dispatch) ();
ulong protocol;

svc_run()

svc_sendreply(xprt, outproc, out)
SVCXPRT xprt;
xdrproc_t outproc;
char out;

void svc_unregister(prognum, versnum)
ulong prognum, versnum;

void svcerr_auth(xprt, why)
SVCXPRT xprt;
enum auth_stat why;

void svcerr_decode(xprt)
SVCXPRT xprt;

void svcerr_noproc(xprt)
SVCXPRT xprt;

void svcerr_noprog(xprt)
SVCXPRT xprt;

void svcerr_progvers(xprt)
SVCXPRT xprt;

void svcerr_systemerr(xprt)
SVCXPRT xprt;

void svcerr_weakauth(xprt)
SVCXPRT xprt;

void svcfd_create(fd, sendsize, recvsize)
int fd;
uint sendsize;
uint recvsize;

SVCXPRT svcraw_create()

SVCXPRT svctcp_create(sock, send_buf_size, recv_buf_size)
int sock;
uint send_buf_size, recv_buf_size;

SVCXPRT svcudp_bufcreate(sock, sendsz, recvsz)
int sock;
u_int sendsz, recvsz;

SVCXPRT svcudp_create(sock)
int sock;

svcudp_enablecache(transp, size)
SVCXPRT transp;
ulong size;

void xprt_register(xprt)
SVCXPRT xprt;

void xprt_unregister(xprt)
SVCXPRT xprt;

Description

auth_destroy is 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.

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 RPC.

authunix_create creates and returns an RPC 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 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. It is easy to impersonate a user.

authunix_create_default calls authunix_create with the appropriate parameters: the current host name, and the user ID, group ID, and groups to which the current user belongs.

callrpc calls 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 0 if it succeeds; if it fails, it returns the value of enum clnt_stat cast to an integer. The routine clnt_perrno is useful for translating failure status data into messages.

clnt_broadcast is similar to 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;

clnt_call is 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 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.

clnt_control is a macro that is 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 UDP and TCP, the supported values of req and their argument types and what they do are:

CLSET_TIMEOUT struct timeval set total timeout
CLGET_TIMEOUT struct timeval get total timeout

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_create is a 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 udp and tcp. Default timeouts are set, but can be modified using clnt_control.

clnt_destroy is 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 also close it. Otherwise, the socket remains open.

clnt_freeres is a macro that frees any data allocated by the RPC/XDR system when it decoded the results of an RPC call. The parameter out is the address of the results and outproc is the XDR routine describing the results in simple primitives. This routine returns 1 if the results were successfully freed, 0 otherwise.

clnt_geterr is a macro that copies the error structure out of the client handle to the structure at address errp.

clnt_pcreateerror prints a message to the standard error indicating why a client RPC handle could not be created. The message is prepended with string s and a colon, however it is not terminated with an ERLF. This is used when a clnt_create, clntraw_create, clnttcp_create, or clntudp_create call fails.

clnt_perrno prints a message to the standard error corresponding to the condition indicated by stat. This is used after callrpc.

clnt_perror 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. This is used after clnt_call.

clnt_spcreateerror is like clnt_pcreateerror, except that it returns a string instead of printing to the standard error. The string is not terminated by an ERLF.

clnt_sperrno takes the same arguments as clnt_perrno, but instead of sending a message to the standard error to indicate why an RPC call failed, it returns a pointer to a string which contains the message. The string is not terminated with an ERLF.

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.

clnt_sperror is like clnt_perror, except that (like clnt_sperrno) it returns a string instead of printing to standard error. The string is not terminated with an ERLF.

clntraw_create creates a memory-based 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.

clnttcp_create 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 0, 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 one 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 parameters sendsz and recvsz; zero values of these parameters choose suitable defaults. This routine returns NULL if it fails.

clntudp_bufcreate creates a client handle for the remote program prognum on versnum; the client uses UDP/IP as the transport. The remote program is located at the Internet address addr. If addr->sin_port is zero, it is set to port on which the remote program is listening on (the remote portmap service is consulted for this information). The parameter sockp is a pointer to a socket; if it is RPC_ANYSOCK, then a new socket is opened and sockp is updated. 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(). If successful it returns a client handle, otherwise it returns NULL.

The user can specify the maximum packet size for sending and receiving by using sendsz and recvsz arguments for UDP-based RPC messages.

clntudp_create creates an RPC client for the remote program prognum, version versnum; the client uses UDP/IP as a transport. The remote program is located at Internet address addr. If addr->sin_port is 0, 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 one 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.

get_myaddress writes 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).

pmaplist is 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 command rpcinfo -p uses this routine.

pmap_getport is a user interface to the portmap service, pmap_getport 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 IPPROTO_UDP or IPPROTO_TCP. A return value of 0 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.

pmap_rmtcall is 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 parameter *portp 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 only for a ``ping''. See also clnt_broadcast.

pmap_set is a user interface to the portmap service, pmap_set establishes a mapping between the triple (prognum, versnum, protocol) and port on the machine's portmap service. The value of protocol is IPPROTO_UDP or IPPROTO_TCP. This routine returns 1 if it succeeds, 0 otherwise. This is done automatically by svc_register.

pmap_unset is 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 1 if it succeeds, 0 otherwise.

registerrpc registers procedure procname with the RPC service package. If a request arrives for program prognum, version versnum, and procedure procnum, 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 0 if the registration succeeded, -1 otherwise.

rpc_createerr is a global variable whose value is set by any RPC client creation routine that does not succeed. Use the routine clnt_pcreateerror to print the reason for the routine's failure.

svc_destroy is 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.

svc_fdset is a global variable that reflects the RPC service side's read file descriptor bit mask; it is suitable as a parameter to the select system call. This is needed only if a service implementor does not call svc_run, but rather does its own asynchronous event processing. This variable is read-only (do not pass its address to select), but it may change after calls to svc_getreqset or any creation routines.

svc_freeargs is 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, 0 otherwise.

svc_getargs is a macro that decodes the arguments of an RPC request associated with the RPC service transport handle, xprt. The parameter in is the address where the arguments will be placed; inproc is the XDR routine used to decode the arguments. This routine returns 1 if decoding succeeds, 0 otherwise.

svc_getcaller is the approved way of getting the network address of the caller of a procedure associated with the RPC service transport handle, xprt.

svc_getreqset is only needed 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 associates prognum and versnum with the service dispatch procedure, dispatch. If protocol is 0, 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 0, IPPROTO_UDP or IPPROTO_TCP). The procedure dispatch has the following form:

   dispatch(request, xprt)
   struct svc_req *request;
   SVCXPRT *xprt;

svc_run never returns. It 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 is called by an RPC service's dispatch routine to send the results of a remote procedure call. The parameter, xprt, 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 1 if it succeeds, 0 otherwise.

svc_unregister removes all mapping of the double (prognum, versnum) to the dispatch routines and of the triple (prognum, versnum, *) to the port number.

svcerr_auth is called by a service dispatch routine that refuses to perform a remote procedure call due to an authentication error.

svcerr_decode is called by a service dispatch routine that cannot decode its parameters successfully. See also svc_getargs.

svcerr_noproc is called by a service dispatch routine that does not implement the procedure number that the caller requests.

svcerr_noprog is called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine.

svcerr_progvers is called when the desired version of a program is not registered with the RPC package. Service implementors usually do not need this routine.

svcerr_systemerr is 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.

svcerr_weakauth is 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).

svcfd_create creates a service on top of any open descriptor. Typically, this descriptor is a connected socket for a stream protocol such as TCP. sendsize and recvsize indicate sizes for the send and receive buffers.

svcraw_create creates a memory-based RPC service transport and returns a pointer to it. 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.

svctcp_create creates a TCP/IP-based RPC service transport and returns a pointer to it. The transport is associated with the socket sock, 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 number 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; zero values for these parameters choose suitable defaults. If they are 0, reasonable defaults are chosen.

svcudp_bufcreate creates a UDP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket sock. If sock is RPC_ANYSOCK, then 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 service's socket descriptor, and xprt->xp_port is the service's port number. This routine returns NULL if it fails.

The user specifies the maximum packet size for sending and receiving UDP-based RPC messages by using the sendsz and recvsz parameters.

svcudp_create creates a UDP/IP-based RPC service transport and returns a pointer to it. The transport is associated with the socket, sock, 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, IPPORT_RESERVED. Upon completion, xprt->xp_sock is the transport's socket number and xprt->xp_port is the transport's port number. This routine returns NULL if it fails.

svcudp_enablecache allocates space for storing the last size replies sent for a given service RPC handle. This allows the RPC package to respond immediately to a retransmitted request without calling the service dispatch routine. Once the cache is enabled for a service handle, it cannot be disabled.

xprt_register modifies the global variable svc_fds. After RPC service transport handles are created, they should register themselves with the RPC service package. Service implementors usually do not need this routine.

xprt_unregister modifies the global variable svc_fds. Before an RPC service transport handle is destroyed, it should unregister itself with the RPC service package. Service implementors usually do not need this routine.

See also