May 7, 1993 RPC_CLNT_CREATE 3

### NAME

rpc_clnt_create, clnt_control, clnt_create, clnt_create_vers, clnt_destroy, clnt_dg_create, clnt_pcreateerror, clnt_raw_create, clnt_spcreateerror, clnt_tli_create, clnt_tp_create, clnt_vc_create, rpc_createerr - library routines for dealing with creation and manipulation of CLIENT handles

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```bool_t` clnt_control(```CLIENT *clnt``, const u_int req``, char *info`)
```CLIENT *` clnt_create(```const char * host``, const rpcprog_t prognum``, const rpcvers_t versnum``, const char *nettype`)
```CLIENT *` clnt_create_vers(```const char * host``, const rpcprog_t prognum``, rpcvers_t *vers_outp``, const rpcvers_t vers_low``, const rpcvers_t vers_high``, char *nettype`)
```void` clnt_destroy(```CLIENT *``, clnt`)
```CLIENT *` clnt_dg_create(```const int fildes``, const struct netbuf *svcaddr``, const rpcprog_t prognum``, const rpcvers_t versnum``, const u_int sendsz``, const u_int recvsz`)
```void` clnt_pcreateerror(```const char *s`)
```char *` clnt_spcreateerror(```const char *s`)
```CLIENT *` clnt_raw_create(```const rpcprog_t prognum``, const rpcvers_t versnum`)
```CLIENT *` clnt_tli_create(```const int fildes``, const struct netconfig *netconf``, const struct netbuf *svcaddr``, const rpcprog_t prognum``, const rpcvers_t versnum``, const u_int sendsz``, const u_int recvsz`)
```CLIENT *` clnt_tp_create(```const char * host``, const rpcprog_t prognum``, const rpcvers_t versnum``, const struct netconfig *netconf`)
```CLIENT *` clnt_vc_create(```const int fildes``, const struct netbuf *svcaddr``, const rpcprog_t prognum``, const rpcvers_t versnum``, const u_int sendsz``, const u_int recvsz`)

### DESCRIPTION

RPC library routines allow C language programs to make procedure calls on other machines across the network. First a ```CLIENT` handle is created and then the client calls a procedure to send a request to the server. On receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends a reply.

### ROUTINES

clnt_control(``)
  A function macro to change or retrieve various information about a client object. ```req` indicates the type of operation, and ```info` is a pointer to the information. For both connectionless and connection-oriented transports, the supported values of ```req` and their argument types and what they do are:

  ```CLSET_TIMEOUT` | `struct timeval *` | `set total timeout`
  ```CLGET_TIMEOUT` | `struct timeval *` | `get total timeout`

  Note: if you set the timeout using clnt_control(``), the timeout argument passed by clnt_call(``) is ignored in all subsequent calls.

  Note: If you set the timeout value to 0 clnt_control(``) immediately returns an error ( ```RPC_TIMEDOUT`). Set the timeout parameter to 0 for batching calls.

  ```CLGET_SVC_ADDR` | `struct netbuf *` | `get servers address`
  ```CLGET_FD` | `int *` | `get fd from handle`
  ```CLSET_FD_CLOSE` | `void` | `close fd on destroy`
  ```CLSET_FD_NCLOSE` | `void` | `don't close fd on destroy`
  ```CLGET_VERS` | `unsigned long *` | `get RPC program version`
  ```CLSET_VERS` | `unsigned long *` | `set RPC program version`
  ```CLGET_XID` | `unsigned long *` | `get XID of previous call`
  ```CLSET_XID` | `unsigned long *` | `set XID of next call`

  The following operations are valid for connectionless transports only:

  ```CLSET_RETRY_TIMEOUT` | `struct timeval *` | `set the retry timeout`
  ```CLGET_RETRY_TIMEOUT` | `struct timeval *` | `get the retry timeout`

  The retry timeout is the time that RPC waits for the server to reply before retransmitting the request. clnt_control(``) returns ```TRUE` on success and ```FALSE` on failure.

clnt_create(``)
  Generic client creation routine for program ```prognum` and version ```versnum`. ```host` identifies the name of the remote host where the server is located. ```nettype` indicates the class of transport protocol to use. The transports are tried in left to right order in ```NETPATH` environment variable or in top to bottom order in the netconfig database. clnt_create(``) tries all the transports of the ```nettype` class available from the ```NETPATH` environment variable and the netconfig database, and chooses the first successful one. A default timeout is set and can be modified using clnt_control(``). This routine returns ```NULL` if it fails. The clnt_pcreateerror(``) routine can be used to print the reason for failure.

  Note: clnt_create(``) returns a valid client handle even if the particular version number supplied to clnt_create(``) is not registered with the rpcbind(8) service. This mismatch will be discovered by a clnt_call(``) later (see rpc_clnt_calls(3)).

clnt_create_vers(``)
  Generic client creation routine which is similar to clnt_create(``) but which also checks for the version availability. ```host` identifies the name of the remote host where the server is located. ```nettype` indicates the class transport protocols to be used. If the routine is successful it returns a client handle created for the highest version between ```vers_low` and ```vers_high` that is supported by the server. ```vers_outp` is set to this value. That is, after a successful return ```vers_low`

  ```*vers_outp`

  ```vers_high`. If no version between ```vers_low` and ```vers_high` is supported by the server then the routine fails and returns ```NULL`. A default timeout is set and can be modified using clnt_control(``). This routine returns ```NULL` if it fails. The clnt_pcreateerror(``) routine can be used to print the reason for failure. Note: clnt_create(``) returns a valid client handle even if the particular version number supplied to clnt_create(``) is not registered with the rpcbind(8) service. This mismatch will be discovered by a clnt_call(``) later (see rpc_clnt_calls(3)). However, clnt_create_vers(``) does this for you and returns a valid handle only if a version within the range supplied is supported by the server.

clnt_destroy(``)
  A function macro that destroys the client's RPC handle. Destruction usually involves deallocation of private data structures, including ```clnt` itself. Use of ```clnt` is undefined after calling clnt_destroy(``). If the RPC library opened the associated file descriptor, or ```CLSET_FD_CLOSE` was set using clnt_control(``), the file descriptor will be closed. The caller should call auth_destroy(```clnt->cl_auth`) (before calling clnt_destroy(``)) to destroy the associated ```AUTH` structure (see rpc_clnt_auth(3)).

clnt_dg_create(``)
  This routine creates an RPC client for the remote program ```prognum` and version ```versnum`; the client uses a connectionless transport. The remote program is located at address ```svcaddr`. The parameter ```fildes` is an open and bound file descriptor. This routine will resend the call message in intervals of 15 seconds until a response is received or until the call times out. The total time for the call to time out is specified by clnt_call(``) (see clnt_call(``) in rpc_clnt_calls(3)). The retry time out and the total time out periods can be changed using clnt_control(``). The user may set the size of the send and receive buffers with the parameters ```sendsz` and ```recvsz`; values of 0 choose suitable defaults. This routine returns ```NULL` if it fails.

clnt_pcreateerror(``)
  Print a message to standard error indicating why a client RPC handle could not be created. The message is prepended with the string ```s` and a colon, and appended with a newline.

clnt_spcreateerror(``)
  Like clnt_pcreateerror(``), except that it returns a string instead of printing to the standard error. A newline is not appended to the message in this case. Warning: returns a pointer to a buffer that is overwritten on each call.

clnt_raw_create(``)
  This routine creates an RPC client handle for the remote program ```prognum` and version ```versnum`. The transport used to pass messages to the service is a buffer within the process's address space, so the corresponding RPC server should live in the same address space; (see svc_raw_create(``) in rpc_svc_create(3)). This allows simulation of RPC and measurement of RPC overheads, such as round trip times, without any kernel or networking interference. This routine returns ```NULL` if it fails. clnt_raw_create(``) should be called after svc_raw_create(``).

clnt_tli_create(``)
  This routine creates an RPC client handle for the remote program ```prognum` and version ```versnum`. The remote program is located at address ```svcaddr`. If ```svcaddr` is ```NULL` and it is connection-oriented, it is assumed that the file descriptor is connected. For connectionless transports, if ```svcaddr` is ```NULL`, ```RPC_UNKNOWNADDR` error is set. ```fildes` is a file descriptor which may be open, bound and connected. If it is ```RPC_ANYFD`, it opens a file descriptor on the transport specified by ```netconf`. If ```fildes` is ```RPC_ANYFD` and ```netconf` is ```NULL`, a ```RPC_UNKNOWNPROTO` error is set. If ```fildes` is unbound, then it will attempt to bind the descriptor. The user may specify the size of the buffers with the parameters ```sendsz` and ```recvsz`; values of 0 choose suitable defaults. Depending upon the type of the transport (connection-oriented or connectionless), clnt_tli_create(``) calls appropriate client creation routines. This routine returns ```NULL` if it fails. The clnt_pcreateerror(``) routine can be used to print the reason for failure. The remote rpcbind service (see rpcbind(8)) is not consulted for the address of the remote service.

clnt_tp_create(``)
  Like clnt_create(``) except clnt_tp_create(``) tries only one transport specified through ```netconf`. clnt_tp_create(``) creates a client handle for the program ```prognum`, the version ```versnum`, and for the transport specified by ```netconf`. Default options are set, which can be changed using clnt_control(``) calls. The remote rpcbind service on the host ```host` is consulted for the address of the remote service. This routine returns ```NULL` if it fails. The clnt_pcreateerror(``) routine can be used to print the reason for failure.

clnt_vc_create(``)
  This routine creates an RPC client for the remote program ```prognum` and version ```versnum`; the client uses a connection-oriented transport. The remote program is located at address ```svcaddr`. The parameter ```fildes` is an open and bound file descriptor. The user may specify the size of the send and receive buffers with the parameters ```sendsz` and ```recvsz`; values of 0 choose suitable defaults. This routine returns ```NULL` if it fails. The address ```svcaddr` should not be ```NULL` and should point to the actual address of the remote program. clnt_vc_create(``) does not consult the remote rpcbind service for this information.

struct rpc_createerr rpc_createerr;
  A global variable whose value is set by any RPC client handle creation routine that fails. It is used by the routine clnt_pcreateerror(``) to print the reason for the failure.

### SEE ALSO

rpc(3), rpc_clnt_auth(3), rpc_clnt_calls(3), rpcbind(8)