NAME

clnt_control, clnt_create, clnt_create_vers, clnt_destroy, clnt_pcreateerror, clntraw_create, clnt_spcreateerror, clnttcp_create, clntudp_bufcreate, clntudp_create, rpc_createrr − library routines for the creation and manipulation of client handles

SYNOPSIS

#include <rpc/rpc.h>

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

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

/* clnt_create_vers */
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;

/* clnt_destroy */
void
clnt_destroy(clnt)
CLIENT *clnt;

/* clnt_pcreateerror */
void
clnt_pcreateerror(str)
char *str;

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

/* clnt_spcreateerror */
char *
clnt_spcreateerror(str)
char *str;

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

/* clntudp_bufcreate */
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, recvsz;

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

/* rpc_createrr */
struct rpc_createerr rpc_createerr;

DESCRIPTION

The following rpc_clnt_create() routines support the creation and manipulation of client handles. 

These routines use the CLIENT data structure, which is defined in Power Programming with RPC.

To use these routines, the C client program must include the header file, <rpc.h>. 

clnt_control() Changes or retrieves information about a client object.  This routine returns TRUE on successful completion; otherwise, it returns FALSE.  The parameters for this routine are defined as follows:

clnt is the client object. 

request is the type of operation to be performed.  The following requests are valid for both UDP and TCP networks:

CLSET_TIMEOUT  - Sets the total timeout.  The argument type is struct timeval. 

CLGET_TIMEOUT  - Gets the total timeout.  The argument type is struct timeval. 

CLGET_FD  - Gets the associated socket.  The argument type is int. 

CLSET_FD_CLOSE  - Closes the socket on clnt_destroy().  The argument type is void. 

CLSET_FD_NCLOSE  - Leaves socket open on clnt_destroy().  The argument type is void. 

CLGET_SERVER_ADDR  - Gets server’s address.  The argument type is struct sockaddr_in. 

Note: If you set the timeout using clnt_control(), the timeout parameter passed to clnt_call() will be ignored in all future calls (see rpc_clnt_calls(3C)). 

The following requests are valid for UDP only:

CLSET_RETRY_TIMEOUT  - Sets the retry timeout.  The argument type is struct timeval. 

CLGET_RETRY_TIMEOUT  - Gets the retry timeout.  The argument type is struct timeval. 

Note: The retry timeout is the time that UDP RPC waits for the server to reply before retransmitting the request. 

info is a pointer to the information about the client object. 

clnt_create() Creates a client handle on a remote host.  The parameters for this routine are defined as follows:

host is the name of the remote host (where the server is located). 

prognum is the program number associated with the remote procedure. 

versnum is the version number associated with the remote procedure. 

protocol is the type of transport protocol to be used. 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, this routine 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 kilobytes of encoded data, this transport cannot be used for procedures that take arguments or return results larger than 8 kilobytes.  Use TCP whenever you need to exceed this message-data limit. 

Note: If a version number for the specified program is registered with the portmap(1M) service on host, clnt_create() returns a handle, even if the requested version number versnum is not registered.  The version mismatch will be discovered by a clnt_call() later (see rpc_clnt_calls(3C)). 

clnt_create_vers()
Creates a client handle on a remote host with the highest available version number.

Default timeouts are also set, but can be modified using clnt_control(). 

The parameters for this routine are defined as follows:

host is the name of the remote host (where the server is located). 

prognum is the program number associated with the remote procedure. 

vers_outp, vers_low, and vers_high are used to create and set the version number for the client handle.  If the routine is successful, it returns a client handle created for the highest version that is supported by the server, between vers_low and vers_high .  The vers_outp is set to this value after a successful return of 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. 

protocol is the type of transport protocol to be used. The currently supported values for this field are udp and tcp. 

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(3C)).  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. 

clnt_destroy() Destroys the client’s RPC handle and deallocates any private data structures, including the client object, clnt .  (Use of clnt is undefined after calling clnt_destroy().)  If the RPC library opened the associated socket, or if CLSET_FD_CLOSE was set using clnt_control(), the clnt_destroy() routine closes the socket. 

clnt_pcreateerror()
Prints a standard error message to indicate why a client handle could not be created. The message is prefixed with string s and a colon.  This routine is used when routines such as clnt_create(), clntraw_create(), clnttcp_create(), or clntudp_create() fail. 

clntraw_create() Creates an RPC client for a remote program. 

This routine allows for RPC simulation and the retrieval of RPC overheads, such as round trip times, without any kernel interference.  If the routine is successful it returns a client handle, otherwise it returns NULL. 

The parameters for this routine are defined as follows:

prognum is the program number associated with the remote procedure. 

versnum is the version number associated with the remote procedure. 

Since the transport used to pass messages to the service is actually a buffer within the process’s address space, the corresponding RPC server should live in the same address space: see the description for svcraw_create() in rpc_svc_create(3C) for more information.

clnt_spcreateerror()
Returns an error-message string indicating why a client handle could not be created; does not append the message with a newline.

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

clnttcp_create() Creates a client handle for a remote program that uses TCP/IP as the transport. 

If successful, this routine returns a client handle; otherwise it returns NULL. 

The parameters for this routine are defined as follows:

addr is the Internet address of the remote program.  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). 

prognum is the program number associated with the remote procedure. 

versnum is the version number associated with the remote procedure. 

sockp is a pointer to a socket. If it is RPC_ANYSOCK, then a new socket is opened and sockp is updated. 

sendsz , recvsz are send and receive buffers of a specified size.  Since TCP-based RPC uses buffered I/O, the user may specify the size of the send and receive buffers with these parameters, and can use values of zero to set defaults. 

Warning: If addr -> sin_port is zero and the requested 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(3C) for more details).

clntudp_bufcreate()
Creates a client handle for a remote program that uses UDP/IP as the transport; allows user to specify sizes of the send and receive buffers.

If this routine is successful it returns a client handle; otherwise it returns NULL. 

The parameters for this routine are defined as follows:

addr is the Internet address of the remote program.  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). 

prognum is the program number associated with the remote procedure. 

versnum is the version number associated with the remote procedure. 

wait is the intervals of time that the UDP transport resends the call message 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(3C) for more information).

sockp is the pointer to a socket. If it is RPC_ANYSOCK, then a new socket is opened and sockp is updated. 

sendsz , recvsz are the send and receive buffers of a specified size.  Since UDP-based RPC uses buffered I/O, the user may specify the maximum packet size for sending and receiving using these arguments. 

Warning: If addr -> sin_port is zero and the requested version number is not registered with the remote portmap service, this routine 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(3C)).

clntudp_create() Creates a client handle for a remote program; the client uses UDP/IP as the transport. 

If this routine is successful it returns a client handle; otherwise it returns NULL. 

The parameters for this routine are defined as follows:

addr is the Internet address of the remote program.  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). 

prognum is the program number associated with the remote procedure. 

versnum is the version number associated with the remote procedure. 

wait is the intervals of time that the UDP transport resends the call message 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(3C)).

sockp is the pointer to a  socket. If it is RPC_ANYSOCK, a new socket is opened and sockp is updated. 

Warning: Since UDP-based RPC messages can only hold up to 8 kilobytes of encoded data, this transport cannot be used for procedures that take arguments or results larger than 8 kilobytes.  TCP should be used instead. 

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

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

AUTHOR

rpc(3C) was developed by Sun Microsystems, Inc. 

SEE ALSO

portmap(3C), rpc(3C), rpc_clnt_auth(3C), rpc_clnt_calls(3C), rpc_svc_create(3C)

Hewlett-Packard Company  —  HP-UX Release 10.20:  July 1996