clnt_tli_create Subroutine

Purpose

Creates and returns a generic client handle for a remote program using the specified transport.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/clnt.h>

CLIENT * clnt_tli_create(fd, nconf, svcaddr, prognum, versnum, sendsize, recvsize)
const int fd;
const struct netconfig *nconf;
const struct netbuf *svcaddr ;
const rpcprog_t prognum;
const rpcvers_t versnum;
const uint_t sendsize;
const uint_t recvsize;

Description

The clnt_tli_create subroutine is an expert-level API for transport-independent remote procedure calls (TI_PRC). The subroutine specifies transport-related parameters. The clnt_tli_create subroutine creates and returns a generic client handle for the specified program and version. This generic client handle is returned from the remote host. The subroutine uses an open and bound file descriptor through the specified transport and the address of the remote program to call the remote program. If you set the sizes of the send and receive buffers that are specified by the sendsize and recvsize parameters to 0, the default sizes of the buffers are used.

Note: If you set the value of the nconf parameter to a connection-oriented transport and set the value of the svcaddr parameter to NULL, the file descriptor is assumed to be connected. If you set the value of the nconf parameter to a connectionless transport and set the value of the svcaddr parameter to NULL, an error is returned. If you set the value of the fd parameter to RPC_ANYFD, a suitable file descriptor is opened and bound on the specified transport. If you set the value of the fd parameter to RPC_ANYFD and set the value of the nconf parameter to NULL, an error is returned.

Parameters

Item	Description
fd	Specifies the file descriptor that is open, bound, and connected on the specified transport.
nconf	Specifies the transport to use.
svcaddr	Specifies the address of the remote program
prognum	Specifies the program number of the remote program.
versnum	Specifies the version number of the remote program.
sendsize	Specifies the size of the send buffer.
recvsize	Specifies the size of the receive buffer.

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_tli_create subroutine returns failure if one or more of the following are true.

Item	Description
RPC_TLIERROR	The file descriptor is not valid.
RPC_UNKNOWNADDR	The value of the svcaddr parameter that holds the address of the remote program is NULL.

Examples

In the following example, the clnt_tli_create subroutine returns a generic client handle for the remote program using the specified transport on successful completion.

int main()
{
    char hostname[255]; /* The Remote Host */
    rpcprog_t PROGNUM = 0x3fffffffL ;
    rpcvers_t PROGVER = 0x1L ;
    struct netconfig *nconf 
    struct netbuf svcaddr ;
    CLIENT *cl ; 
    char *transport ;            /* Can be set to TCP or UDP */

    if ((nconf = getnetconfigent(transport)) == (struct netconfig *)NULL)
    {
          fprintf(stderr, "Cannot get netconfig entry for UDP\n");
          exit(2);
    }

    if (!rpcb_getaddr(PROGNUM, PROGVER, nconf, &svcaddr, hostname))
    {
          fprintf(stderr, "rpcb_getaddr failed!!\n");
          exit(2);
    }

    /*
     * make the clnt_tli_create call with nconf and
     * observe the result
     */
    cl = clnt_tli_create(RPC_ANYFD, nconf, &svcaddr, PROGNUM, PROGVER, 0, 0);
    if( cl==NULL )        
    {
          fprintf(stdout, "clnt_tli_create : failed.\n");
          exit(EXIT_FAILURE);
    }

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

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

    return 0;
}