clnt_create Subroutine

Important: The subroutine is exported from both the libc and the libnsl libraries.

clnt_create Subroutine Exported from the libc Library

Purpose

Creates and returns a generic client handle.

Library

C Library (libc.a)

Syntax

#include <rpc/rpc.h>

CLIENT *clnt_create (host, prognum, versnum, protocol)
char * host;
unsigned  prognum,  versnum;
char * protocol;

Description

Creates and returns a generic client handle.

Remote Procedure Calls (RPC) messages transported by User Datagram Protocol/Internet Protocol (UDP/IP) can hold up to 8KB of encoded data. Use this transport for procedures that take arguments or return results of less than 8KB.

Note: When the clnt_create subroutine is used to create a RPC client handle, the timeout value provided on subsequent calls to clnttcp_call are ignored. Using the clnt_create subroutine has the same effect as using clnttcp_create followed by a call to clnt_control to set the timeout value for the RPC client handle. If the timeout paramater is used on the clnttcp_call interface, use the clnttcp_create interface to create the client handle.

Parameters

Item Description
host Identifies the name of the remote host where the server is located.
prognum Specifies the program number of the remote program.
versnum Specifies the version number of the remote program.
protocol Identifies which data transport protocol the program is using, either UDP or Transmission Control Protocol (TCP).

Return Values

Upon successful completion, this subroutine returns a client handle.

clnt_create Subroutine Exported from the libnsl Library

Purpose

Creates and returns a generic client handle for a remote program.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>
CLIENT *clnt_create(host, prognum, versnum, nettype)
const char *host;
const rpcprog prognum;
const rpcvers_t versnum;
char *nettype;

Description

The clnt_create subroutine is a top-level API for transport independent remote procedure calls (TI_PRC). The subroutine creates and returns a generic client handle for the specified program and version. This generic client handle is returned from the remote host on which the server is running. This operation is done with the available transport service of the class that is specified by the nettype parameter. The clnt_create subroutine chooses the first successful transport from the NETPATH environment variable and then from the netconfig database in a top-to-bottom order. A default timeout value specifies the time for the clnt_create subroutine to return. If the timeout value expires, the subroutine returns NULL. You can modify the timeout value using the clnt_control macro subroutine.

Note:
  1. The clnt_pcreateerror subroutine can be used to obtain the reason for failure of the creation of an RPC-client handle.
  2. The clnt_create subroutine returns a valid client handle even if the specified version number is not supported by the server. The clnt_call subroutine will recognize the condition and return failure.

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.
nettype Defines a class of transports that can be used for a particular application.

Return Values

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

Error Codes

The clnt_create subroutine returns failure when one or more of the following codes are true.

Item Description
RPC_UNKNOWNPROTO
  • The value specified by the nettype parameter is not valid.
  • The value specified by the nettype 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_PROGNOTREGISTERED The program number is not valid.

Examples

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

int main()
{
  CLIENT *cl;
  rpcprog_t PROGNUM = 0x3fffffffL;
  rpcvers_t PROGVER = 0x1L;
  char *nettype = "visible";
  char hostname[255]; /* The name of remote host */

  /*
  * make the clnt_create call with this nettype and
  * observe the result
  */

  if ((cl=clnt_create( hostname, PROGNUM, PROGVER, nettype)) == NULL)
  {
    fprintf(stdout, "clnt_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;
}