clnt_vc_create Subroutine

The clnt_vc_create subroutine is a bottom-level API for transport-independent remote procedure calls (TI_PRC). With the subroutine, applications can control all the options. The clnt_vc_create subroutine creates and returns a generic client handle for the specified program and version. The subroutine uses a connection-oriented transport. The generic client handle is returned from the remote host where the server is located. The subroutine uses an open and bound file descriptor through the connection-oriented transport and the specified address of the remote program to call the remote program. The can be specified by the sendsize and recvsize parameters. 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 fd parameter to RPC_ANYFD or set the svcaddr subroutine to a null value, the subroutine fails and returns a null value.

Purpose

Creates and returns a generic client handle for a remote program using a connection-oriented transport.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>

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

Description

Parameters

Item	Description
fd	Specifies the open and bound file descriptor on a connection-oriented transport.
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
a null value	unsuccessful

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

Error Codes

The clnt_vc_create subroutine returns failure if one or more of the following codes 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 a null value.
RPC_CANTENCODEARGS	The size of the send or receive buffer is less than that of the sent packet.

Examples

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

int main()
{
    CLIENT *cl ;
    int fd;
    rpcprog_t PROGNUM    =         0x3fffffffL;
    rpcvers_t PROGVER        =      0x1L ;
    struct netconfig *nconf ;
    struct netbuf svcaddr ;   
    char hostname[255] ;      /* The name of remote host */

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

    /* Get address of service on remote host */
    if (!rpcb_getaddr(PROGNUM, PROGVER, nconf,
                    &svcaddr, hostname))
    {
        fprintf(stderr, "rpcb_getaddr failed!!\n");
        exit(2);
     }
    /* Get the open and bound file descriptor for connection oriented transport */
    fd = . . . 
    if ((cl = clnt_vc_create(fd, &svcaddr,
             PROGNUM, PROGVER, 0, 0))==NULL);
     {
         fprintf(stdout, "clnt_vc_create : failed.\n");
         exit(EXIT_FAILURE);
     }

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

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

    return 0;
}