# phpman > man > rpc_clnt_create(3t) [RPC_CLNT_CREATE(3)](https://www.chedong.com/phpMan.php/man/RPCCLNTCREATE/3/markdown) BSD Library Functions Manual [RPC_CLNT_CREATE(3)](https://www.chedong.com/phpMan.php/man/RPCCLNTCREATE/3/markdown) ## NAME **rpc**___**clnt**___**create**, **clnt**___**control**, **clnt**___**create**, **clnt**___**create**___**timed**, **clnt**___**create**___**vers**, **clnt**___**create**___**vers**___**timed**, **clnt**___**destroy**, **clnt**___**dg**___**create**, **clnt**___**pcreateerror**, **clnt**___**raw**___**create**, **clnt**___**spcreateerror**, **clnt**___**tli**___**create**, **clnt**___**tp**___**create**, **clnt**___**tp**___**create**___**timed**, **clnt**___**vc**___**create**, **rpc**___**createerr** — library routines for dealing with creation and manipulation of _CLIENT_ handles ## SYNOPSIS ### #include _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**___**timed**(_const_ _char_ _*_ _host_, _const_ _rpcprog_t_ _prognum_, _const_ _rpcvers_t_ _versnum_, _const_ _char_ _*nettype_, _const_ _struct_ _timeval_ _*timeout_); _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_, _const_ _char_ _*nettype_); _CLIENT_ _*_ **clnt**___**create**___**vers**___**timed**(_const_ _char_ _*_ _host_, _const_ _rpcprog_t_ _prognum_, _rpcvers_t_ _*vers_outp_, _const_ _rpcvers_t_ _vers_low_, _const_ _rpcvers_t_ _vers_high_, _char_ _*nettype_, _const_ _struct_ _timeval_ _*timeout_); _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**___**tp**___**create**___**timed**(_const_ _char_ _*_ _host_, _const_ _rpcprog_t_ _prognum_, _const_ _rpcvers_t_ _versnum_, _const_ _struct_ _netconfig_ _*netconf_, _const_ _struct_ _timeval_ _*timeout_); _CLIENT_ _*_ **clnt**___**vc**___**create**(_const_ _int_ _fildes_, _const_ _struct_ _netbuf_ _*svcaddr_, _const_ _rpcprog_t_ _prognum_, _const_ _rpcvers_t_ _versnum_, _u_int_ _sendsz_, _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 per‐ form the requested service, and then sends a reply. ## Routines **clnt**___**control**() A function macro to change or retrieve various information about a client object. The _req_ argument indicates the type of operation, and _info_ is a pointer to the informa‐ tion. For both connectionless and connection-oriented transports, the supported val‐ ues 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 argument 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 u_int32_t * get RPC program version CLSET_VERS u_int32_t * set RPC program version CLGET_XID u_int32_t * get XID of previous call CLSET_XID u_int32_t * 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 CLSET_CONNECT _int_ _*_ use [connect(2)](https://www.chedong.com/phpMan.php/man/connect/2/markdown) The retry timeout is the time that RPC waits for the server to reply before retrans‐ mitting the request. The **clnt**___**control**() function returns TRUE on success and FALSE on failure. **clnt**___**create**() Generic client creation routine for program _prognum_ and version _versnum_. The _host_ ar‐ gument identifies the name of the remote host where the server is located. The _nettype_ argument 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. The **clnt**___**create**() function tries all the transports of the _nettype_ class available from the NETPATH environment variable and the netconfig data‐ base, and chooses the first successful one. A default timeout is set and can be modi‐ fied 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 num‐ ber supplied to **clnt**___**create**() is not registered with the [rpcbind(8)](https://www.chedong.com/phpMan.php/man/rpcbind/8/markdown) service. This mismatch will be discovered by a **clnt**___**call**() later (see [rpc_clnt_calls(3)](https://www.chedong.com/phpMan.php/man/rpcclntcalls/3/markdown)). **clnt**___**create**___**timed**() Generic client creation routine which is similar to **clnt**___**create**() but which also has the additional argument _timeout_ that specifies the maximum amount of time allowed for each transport class tried. In all other respects, the **clnt**___**create**___**timed**() call be‐ haves exactly like the **clnt**___**create**() call. **clnt**___**create**___**vers**() Generic client creation routine which is similar to **clnt**___**create**() but which also checks for the version availability. The _host_ argument identifies the name of the re‐ mote host where the server is located. The _nettype_ argument indicates the class transport protocols to be used. If the routine is successful it returns a client han‐ dle created for the highest version between _vers_low_ and _vers_high_ that is supported by the server. The _vers_outp_ argument is set to this value. That is, after a suc‐ cessful 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)](https://www.chedong.com/phpMan.php/man/rpcbind/8/markdown) ser‐ vice. This mismatch will be discovered by a **clnt**___**call**() later (see [rpc_clnt_calls(3)](https://www.chedong.com/phpMan.php/man/rpcclntcalls/3/markdown)). 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**___**create**___**vers**___**timed**() Generic client creation routine which is similar to **clnt**___**create**___**vers**() but which also has the additional argument _timeout_ that specifies the maximum amount of time allowed for each transport class tried. In all other respects, the **clnt**___**create**___**vers**___**timed**() call behaves exactly like the **clnt**___**create**___**vers**() call. **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 unde‐ fined after calling **clnt**___**destroy**(). If the RPC library opened the associated file de‐ scriptor, 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)](https://www.chedong.com/phpMan.php/man/rpcclntauth/3/markdown)). **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 _fildes_ argument 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 un‐ til 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)](https://www.chedong.com/phpMan.php/man/rpcclntcalls/3/markdown)). 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 _sendsz_ and _recvsz_ arguments; 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 cre‐ ated. 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: re‐ turns 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 ad‐ dress space; (see **svc**___**raw**___**create**() in [rpc_svc_create(3)](https://www.chedong.com/phpMan.php/man/rpcsvccreate/3/markdown)). 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. The **clnt**___**raw**___**create**() function 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 con‐ nectionless transports, if _svcaddr_ is NULL, RPC_UNKNOWNADDR error is set. The _fildes_ argument 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 _sendsz_ and _recvsz_ arguments; values of 0 choose suitable defaults. Depending upon the type of the transport (connection-oriented or connec‐ tionless), **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)](https://www.chedong.com/phpMan.php/man/rpcbind/8/markdown)) 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_. The **clnt**___**tp**___**create**() function creates a client handle for the program _prognum_, the version _versnum_, and for the transport specified by _netconf_. Default op‐ tions 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**___**tp**___**create**___**timed**() Like **clnt**___**tp**___**create**() except **clnt**___**tp**___**create**___**timed**() has the extra argument _timeout_ which specifies the maximum time allowed for the creation attempt to succeed. In all other respects, the **clnt**___**tp**___**create**___**timed**() call behaves exactly like the **clnt**___**tp**___**create**() call. **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 ad‐ dress _svcaddr_. The _fildes_ argument is an open and bound file descriptor. The user may specify the size of the send and receive buffers with the _sendsz_ and _recvsz_ argu‐ ments; 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. The **clnt**___**vc**___**create**() function 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. ## AVAILABILITY These functions are part of libtirpc. ## SEE ALSO [rpc(3)](https://www.chedong.com/phpMan.php/man/rpc/3/markdown), [rpc_clnt_auth(3)](https://www.chedong.com/phpMan.php/man/rpcclntauth/3/markdown), [rpc_clnt_calls(3)](https://www.chedong.com/phpMan.php/man/rpcclntcalls/3/markdown), [rpcbind(8)](https://www.chedong.com/phpMan.php/man/rpcbind/8/markdown) BSD May 7, 1993 BSD