clnt_tp_create Subroutine

Purpose

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

Library

Network Services Library (libnsl.a)

Syntax

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

Description

The clnt_tp_create 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 a remote host where the server is located. The operation is done with a transport service that is specified by nconf parameter. The service can be a connection-oriented or a connectionless service.
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.

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 subroutine returns failure if one or more of the following are true.
Item Description
RPC_UNKNOWNPROTO
  • The transport service that is 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 the nconf member (nc_semantics = NC_TPI_COTS_ORD).
RPC_PROGNOTREGISTERED The program number is not valid.

Examples

In the following example, the clnt_tp_create subroutine returns a generic client handle using the tcp transport service on successful completion.

#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;

    /* 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);
     }

    /* Create client handle using clnt_tp_create() */
    client = clnt_tp_create(hostname, PROGNUM, PROGVER, nconf);
    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 ;
}