RPC_CLNT_CREATE(3N)

NAME
clnt_control, clnt_create, clnt_create_vers, clnt_destroy, clnt_pcreateerror, clntraw_create, clnt_spcreateerror, clnttcp_create, clntudp_bufcreate, rpc_createrr - library routines for dealing with creation and manipulation of CLIENT handles

DESCRIPTION

RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, 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.

The CLIENT data structure is defined in the RPC/XDR Library Definition of the

#include <rpc/rpc.h>

bool_t clnt_control(clnt, request, info)
CLIENT *clnt;
int request;
char *info;

    Change or retrieve various information about a client object. request indicates the type of operation, and info is a pointer to the information. For both UDP and TCP, the supported values of request and their argument types and what they do are:
    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_NCLOSE void leave socket open on clnt_destroy()

    Note: If you set the timeout using clnt_control(), the timeout parameter passed to clnt_call() (see rpc_clnt_calls(3N)) will be ignored in all future calls.
    CLGET_SERVER_ADDR struct sockaddr_in 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.

    This routine returns TRUE on success, and FALSE on failure.

CLIENT * clnt_create(host, prognum, versnum, protocol)
char *host;
u_long prognum, versnum;
char *protocol;

    Generic client creation routine for program prognum and version versnum. host identifies the name of the remote host where the server is located. protocol indicates which kind of transport protocol to use. The currently supported values for this field are “udp” and “tcp”. Default timeouts are set, but they can be modified using clnt_control(). If successful it returns a client handle, otherwise it returns NULL.

    Warning: Using UDP has its shortcomings. Since UDP-based RPC messages can only hold up to 8 Kbytes of encoded data, this transport cannot be used for procedures that take arguments or return results larger than 8 Kbytes. Use TCP instead.

    Note: If the requested version number versnum is not registered with the portmap(8C) service on host, but at least a version number for the given program number is registered, clnt_create() returns a handle. The version mismatch will be discovered by a clnt_call() later (see rpc_clnt_calls(3N)).

CLIENT * clnt_create_vers(host, prognum, vers_outp, vers_low, vers_high, protocol)
char *host;
u_long prognum;
u_long *vers_outp;
u_long vers_low, vers_high;
char *protocol;

    This is a generic client creation routine which also checks for the version available. host identifies the name of the remote host where the server is located. protocol indicates which kind of transport protocol to use. The currently supported values for this field are “udp” and “tcp”. If the routine is successful it returns a client handle created for the highest version between vers_low and vers_high that is supported by the server. vers_outp is set to this value. That is, after a successful return vers_low <= *vers_outp <= vers_high. If no version between vers_low and vers_high is supported by the server then the routine fails and returns NULL. Default timeouts are set, but can be modified using clnt_control().

    Note: clnt_create() returns a valid client handle even if the particular version number supplied to clnt_create() is not registered with the portmap service. This mismatch will be discovered by a clnt_call() later (see rpc_clnt_calls(3N)). However, clnt_create_vers() does this for you and returns a valid handle only if a version within the range supplied is supported by the server.

void clnt_destroy(clnt)
CLIENT *clnt;

    Destroy 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, or CLSET_FD_CLOSE was set using clnt_control(). clnt_destroy() closes the socket.

void clnt_pcreateerror(str)
char *str;

    Print a message to the standard error indicating why a client handle could not be created. The message is prepended with string s and a colon. Used when routines such as clnt_create(), clntraw_create(), clnttcp_create(), or clntudp_create() fails.

CLIENT * clntraw_create(prognum, versnum)
u_long prognum, versnum;

    Create an 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; also see svcraw_create() (see rpc_svc_create(3N)). This allows simulation of RPC and getting RPC overheads, such as round trip times, without any kernel interference. If successful it returns a client handle, otherwise it returns NULL.

char * clnt_spcreateerror(str)
char *str;

    Like clnt_pcreateerror(), except that it returns a string instead of printing to the standard error. It, however, does not append the message with a NEWLINE.

    Note: clnt_spcreateerror() returns a pointer to a static buffer that is overwritten on each call.

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

    Create a client handle 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, it is set to the port on which the remote program is listening (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. 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; values of zero choose defaults. If successful it returns a client handle, otherwise it returns NULL.

    Warning: If addr->sin_port is zero and the requested version number versnum is not registered with the remote portmap service, it returns a handle if at least a version number for the given program number is registered. The version mismatch will be discovered by a clnt_call( later (see rpc_clnt_calls(3N)).

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;

    Create 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() (see rpc_clnt_calls(3N)). 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.

    Warning: If addr->sin_port is zero and the requested version number versnum is not registered with the remote portmap service, it returns a handle if at least a version number for the given program number is registered. The version mismatch is discovered by a clnt_call() later (see rpc_clnt_calls(3N)).

CLIENT * clntudp_create(addr, prognum, versnum, wait, sockp)
struct sockaddr_in *addr;
u_long prognum, versnum;
struct timeval wait;
int *sockp;

    Create a client handle for the remote program prognum, version 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, 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 pointer to a socket; if it is RPC_ANYSOCK, 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() (see rpc_clnt_calls(3N)). If successful it returns a client handle, otherwise it returns NULL.

    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 arguments or results larger than 8 Kbytes. TCP should be used instead.

    Warning: If addr->sin_port is zero and the requested version number versnum is not registered with the remote portmap service, it returns a handle if any version number for the given program number is registered. The version mismatch is be discovered by a clnt_call() later (see rpc_clnt_calls(3N)).

struct rpc_createerr rpc_createerr;

    A global variable whose value is set by any RPC client handle creation routine that fails. It is used by the routine clnt_pcreateerror() to print the reason for the failure.

SEE ALSO
portmap(3N), rpc(3N), rpc_clnt_auth(3N), rpc_clnt_calls(3N), rpc_svc_create(3N)