clnt_create_timed Subroutine

Purpose

Creates and returns a generic client handle for a remote program within the specified time.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>
clnt_create_timed(host, prognum, versnum, nettype, timeout)
const char *host;
const rpcprog_t prognum;
const rpcvers_t versnum;
const char *nettype;
const struct timeval *timeout;

Description

The clnt_create_timed subroutine is a top-level API for transport-independent remote procedure calls (TI_PRC). The subroutine creates and returns a generic client handle for the specified program and version specified. This generic client handle is returned from the remote host on which server is running. The operation is done using the available transport service of the class that is specified by the nettype parameter. The clnt_create_timed subroutine chooses the first successful transport from the NETPATH environment variable and then from the netconfig database in a top-to-bottom order. The value of the timeout parameter specifies the time for the clnt_create_timed subroutine to return. If the timeout value expires, the subroutine returns a null value.

Note: The subroutine returns a valid client handle even if the version number specified by the versnum parameter is not supported by the server. The clnt_call subroutine can recognize the error and return failure.

Parameters

Item Description
host Specifies the host name where the server resides.
prognum Specifies the program number of the remote program.
versnum Specifies the version number of the remote program.
nettype Defines a class of transports that can be used for a particular application.
timeout Specifies the maximum time spent for each transport class in the nettype class.

Return Values

Item Description
a generic client handle that is valid successful
a null value unsuccessful

Error Codes

The clnt_create_timed subroutine returns failure when one or more of the following codes are true.

Item Description
RPC_UNKNOWNPROTO
  • The value specified by the nettype parameter is not valid.
  • The value specified by the nettype parameter is set to netpath, and the NETPATH environment variable is set to a transport service that is not valid.
RPC_UNKNOWNHOST The host name is not valid.
RPC_TIMEDOUT The timeout value has expired.
RPC_PROGNOTREGISTERED The program number is not valid.

Examples

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

int main()
{
    CLIENT *cl;
    rpcprog_t PROGNUM  =  0x3fffffffL;
    rpcvers_t PROGVER  =  0x1L ;
    char *nettype   =  "visible";
    char hostname[255] ;   /* The name of remote host */
    struct timeval tv;

    tv.tv_sec = 5 ;
    tv.tv_usec = 0 ;

    /*
    * make the clnt_create_timed call with this nettype and
    * observe the result
    */

    if ((cl=clnt_create_timed( hostname, PROGNUM, PROGVER, nettype, &tv)) == NULL)
    {
        fprintf(stdout, "clnt_create_timed : failed.\n");
        exit(EXIT_FAILURE);
    }

    /*
    * Make a call to clnt_call() subroutine
    */

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

    return 0;
}