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.
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.
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.
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 |
|
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;
}