clnt_control Macro

Important: The macro is exported from both the libc and the libnsl libraries.

clnt_control Macro Exported from the libc Library

Purpose

Changes or retrieves various information about a client object.

Library

C Library (libc.a)

Syntax

#include <rpc/rpc.h>

bool_t clnt_control (cI, req, info) CLIENT * cl; int req; char * info;

Description

The clnt_control macro is used to change or retrieve various information about a client object.

User Datagram Protocol (UDP) and Transmission Control Protocol (TCP) have the following supported values for the req parameter's argument types and functions:

Values for the req Parameter	Argument Type	Function
CLSET_TIMEOUT	struct timeval	Sets total time out.
CLGET_TIMEOUT	struct timeval	Gets total time out.
CLGET_SERVER_ADDR	struct sockaddr	Gets server's address.

The following operations are valid for UDP only:

Values for the req Parameter	Argument Type	Function
CLSET_RETRY_TIMEOUT	struct timeval	Sets the retry time out.
CLGET_RETRY_TIMEOUT	struct timeval	Gets the retry time out.

Note:

If the time out is set using the clnt_control subroutine, the time-out parameter passed to the clnt_call subroutine will be ignored in all future calls.
The retry time out is the time that User Datagram Protocol/Remote Procedure Call (UDP/RPC) waits for the server to reply before retransmitting the request.

Parameters

Item	Description
cl	Points to the structure of the client handle.
req	Indicates the type of operation.
info	Points to the information for request type.

Return Values

Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a value of 0.

clnt_control Macro Exported from the libnsl Library

Purpose

Changes or retrieves information of the client handle.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>

bool_t clnt_control(cI, req, info)
CLIENT * cl;
int req;
char * info;

Description

The clnt_control macro subroutine is a simplified-level subroutine for transport-independent remote procedure calls (TI_PRC). You can use the subroutine to change or retrieve information about the client handle. The generic client handle that is obtained from various client create subroutines is supplied as the input parameter. You need to specify the type of operation along with the pointer to the information. For both connectionless and connection-oriented transports, we can either set or get various information about client objects. The data type of the info parameter changes according to the type of operation. For example, you can specify the req parameter with the following values:

CLGET_VERS: Gets the version number of the RPC program associated with the client.
CLSET_VERS: Sets the version number of the RPC program associated with the client.

For the req parameter in the example, the value of the info parameter is of the rpcvers_t type.

Values for the req Parameter	Argument Type	Function
CLSET_TIMEOUT	struct timeval *	Sets the total timeout.
CLGET_TIMEOUT	struct timeval *	Gets the total timeout.
CLGET_SVC_ADDR	struct netbuf *	Gets the address of the server.
CLGET_FD	int *	Gets associated file descriptor.
CLSET_RETRY_TIMEOUT	struct timeval *	Sets the retry timeout.
CLGET_RETRY_TIMEOUT	struct timeval *	Gets the retry timeout.
CLGET_VERS	rpcvers_t	Gets the version number of the RPC program.
CLSET_VERS	rpcvers_t	Sets the version number of the RPC program.
CLGET_XID	uint32_t	Gets XID of the previous RPC.
CLSET_XID	uint32_t	Sets XID of the previous RPC.
CLGET_PROG	rpcprog_t	Gets the program number.
CLSET_PROG	rpcprog_t	Sets the program number.

Parameters

Item	Description
cl	Points to the structure of the generic RPC-client handle .
req	Indicates the type of the operation.
info	Points to the information for request type. The info parameter is expected to be a pointer to an appropriate structure. The nature of the structure depends on the type of the operation.

Return Values

Item	Description
1	successful
0	unsuccessful

Examples

In the following example, the clnt_control macro subroutine returns the version number of the program that is specified by the versnum parameter.

#include <stdlib.h>
#include <rpc/rpc.h>

int main()
{
    struct timeval t;
    CLIENT *cl ;
    rpcprog_t PROG = 0x3fffffffL;
    rpcvers_t versnum,PROGVER = 0x1L;
    char hostname[255] /* The Remote Host */
    char *nettype = "visible" ;
    
    /* Create generic client handle */
    cl = clnt_create( hostname, PROG, PROGVER, nettype);
    if(cl==NULL)
    {
        fprintf(stderr,"Couldnot create client handle");
        exit(1);
    }
       
    if(!clnt_control(cl, CLGET_VERS, versnum))
    {
        fprintf(stderr,"Failed in clnt_control routine");
        exit(1);
    }    
    fprintf(stdout,"\n VERSION NUMBER = %lu \n", versnum);

    /* Destroy the client handle at the end */
    clnt_destroy(cl);
    return 0;
}