clnt_dg_create Subroutine

Purpose

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

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>

CLIENT * clnt_dg_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

The clnt_dg_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_dg_create subroutine creates and returns a generic client handle for the specified program and version. The subroutine uses a connectionless 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 connectionless transport and the specified address of the remote program to call the remote program. If you set the sizes of the send and receive buffers that can be specified by the sendsize and recvsize parameter to 0, the default sizes of the buffers are used. This subroutine resends the call message after an interval of 15 seconds until the subroutine receives a response, or the call times out. The clnt_call subroutine specifies the timeout value. You can use the clnt_control subroutine to modify the retry time and timeout values.

Note: If you set the value of the fd parameter to RPC_ANYFD or set the value of the svcaddr parameter to a null value, the subroutine fails and returns a null value.

Parameters

Item	Description
fd	Specifies the open and bound file descriptor on a connectionless 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_dg_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 NULL.
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 */

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

    if (!rpcb_getaddr(PROGNUM, PROGVER, nconf,&svcaddr, hostname))
    {
        fprintf(stderr, "rpcb_getaddr failed!!\n");
        exit(1);
    }
    /* Get the file descriptor for connection oriented transport */
    fd = . . .     

    if ((cl = clnt_dg_create(fd, &svcaddr, 
                            PROGNUM, PROGVER, 0, 0))==NULL);
    {
        fprintf(stdout, "clnt_dg_create : failed.\n");
        exit(1);
    }

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

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

    return 0;
}