clnt_tp_create_timed Subroutine

Purpose

Creates a client handle for a remote program using the specified class of transport within the specified timeout.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>
CLIENT * clnt_tp_create_timed(host, prognum, versnum, nconf, timeout)
const char *host;
const rpcprog_t prognum;
const rpcvers_t versnum;
const struct netconfig *nconf;
const struct timeval *timeout;

Description

The clnt_tp_create_timed subroutine is an intermediate level API. The subroutine enables the application to have a better control over the transport service to be used. The subroutine creates a client handle for the specified program and version. This client handle is created and returned from the remote host where server is located. The operation is done with a transport service specified by nconf parameter. The service can be a connection-oriented or connectionless service. The timeout parameter specifies the time duration within which the subroutine returns. If the timeout value expires, the subroutine fails and returns NULL.

Note: If you set the value of the nconf parameter to NULL, the subroutine fails.

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.
nconf Defines a specific transport service to use.
timeout Specifies the timeout value.

Return Values

Item Description
a generic client handle that is valid successful
NULL unsuccessful

You can use the clnt_pcreateerror subroutine to obtain the reason for failure.

Error Codes

The clnt_tp_create_timed subroutine returns failure if one or more of the following are true.
Item Description
RPC_UNKNOWNPROTO
  • The transport service specified by the nconf parameter is NULL.
  • The value of the nconf 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_TLIERROR The value of the nconf parameter is set to udp and a call to the clnt_tp_create subroutine is made from the client program with nconf member (nc_semantics = NC_TPI_COTS_ORD).
RPC_PROGNOTREGISTERED The program number is not valid.
RPC_TIMEDOUT The timeout value has expired.

Examples

In the following example, the clnt_tp_create_timed subroutine returns a generic client handle using the tcp transport service on successful completion. If the timeout value expires, the subroutine returns NULL.

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

int main()
{
    CLIENT *client;
    struct netconfig *nconf;
    char hostname[255]; /* The Remote host where server is located */
    rpcprog_t PROGNUM = 0x3fffffffL;
    rpcvers_t PROGVER = 0x1L;
    const struct timeval timeout = { 25 , 0 } ;

    /* getnetconfigent() returns a pointer to the struct  netconfig
     * structure  corresponding to tcp transport
     */
    if ((nconf = getnetconfigent("tcp")) == (struct netconfig *)NULL)
    {
        fprintf(stderr, "Cannot get netconfig entry for UDP\n");
        exit(2);
    }

    client = clnt_tp_create_timed(hostname, PROGNUM, PROGVER, nconf, &timeout);
    if (client == (CLIENT *)NULL)
    {
         fprintf(stderr,"Couldn't create client at inter lvl\n");
         clnt_pcreateerror("Inter lvl : ");
         exit(EXIT_FAILURE);
    }

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

    /* Destroy client handle in the end */
    clnt_destroy(client);

    return 0 ;
}