rpc_clnt_create(3R)rpc_clnt_create(3R)NAME
rpc_clnt_create: clnt_control, clnt_create, clnt_create_vers,
clnt_destroy, clnt_dg_create, clnt_pcreateerror, clntraw_create,
clnt_raw_create, clnt_spcreateerror, clnttcp_create, clnt_tli_create,
clnt_tp_create, clntudp_create, clntudp_bufcreate, clnt_vc_create -
library routines for dealing with creation and manipulation of CLIENT
handles
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 data packet to the server.
Upon receipt of the packet, the server calls a dispatch routine to
perform the requested service, and then sends back a reply.
This page describes functions in the IRIX standard C library (libc).
Some of these functions are part of the new Transport Independent RPC
(TI-RPC) functionality added to the IRIX standard C library in IRIX
release 6.5.20 (known as BSD TI-RPC) and should not be confused with the
older TI-RPC functionality in the UNIX System V Networking Library (known
as System V TI-RPC, see intro(3N)). In particular, the BSD TI-RPC
functions use the BSD socket network API instead of the System V TLI
network API.
BSD TI-RPC functions are marked in this page as BSD TI-RPC only. To use
them code must be compiled with:
cc -D_BSD_TIRPC prog.c
The BSD TI-RPC functions in this page did not exist in IRIX before
release 6.5.20. Applications using them should use the
_MIPS_SYMBOL_PRESENT macro to provide a graceful failure mode when run on
older IRIX releases.
Routines
#include <rpc/rpc.h>
#ifdef _BSD_TIRPC
#include <netconfig.h>
#endif
bool_t
clnt_control(CLIENT *clnt, int req, void *info);
A function macro used 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 (UDP)
and connection-oriented (TCP) transports, the supported values of
req and their argument types and what they do are:
CLSET_TIMEOUT struct timeval set total timeout
Page 1
rpc_clnt_create(3R)rpc_clnt_create(3R)
CLGET_TIMEOUT struct timeval get total timeout
CLGET_SERVER_ADDR struct sockaddr_in get server's address
CLGET_SVC_ADDR struct netbuf get server's address (fills in netbuf to point to internal storage)
CLGET_FD int get connection's file descriptor
CLSET_FD_CLOSE (ignored) let clnt_destroy close fd
CLSET_FD_NCLOSE (ignored) don't let clnt_destroy close fd
CLGET_XID uint32_t get transaction id
CLSET_XID uint32_t set transaction id
CLGET_VERS rpcvers_t get program version
CLSET_VERS rpcvers_t set program version
CLGET_PROG rpcprog_t get program number
CLSET_PROG rpcprog_t set program number
Note: if you set the timeout using clnt_control, the timeout
parameter passed to clnt_call will be ignored in all future calls.
The following operations are valid for connectionless (UDP)
transports only:
CLSET_RETRY_TIMEOUT struct timeval set the retry timeout
CLGET_RETRY_TIMEOUT struct timeval get the retry timeout
CLSET_SVC_ADDR struct netbuf set server's address
The retry timeout is the time that RPC waits for the server to reply
before retransmitting the request.
The following operations are valid for connection-oriented (TCP)
transports only:
CLSET_EINTR_RETURN bool_t set parameter to 1 to return on EINTR
CLGET_EINTR_RETURN bool_t get return on EINTR flag
clnt_control returns 1 on success and 0 on failure.
CLIENT *
clnt_create(const char *host, u_long prognum,
u_long versnum, const char *nettype);
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 which kind of transport
protocol to use. The currently supported values for this field are
"udp" and "tcp".
Default timeouts are set, but can be modified using clnt_control.
Warning: Using UDP has its shortcomings. Since UDP-based RPC
messages can only hold up to a few kilobytes of encoded data, this
transport cannot be used for procedures that take large arguments or
return huge results.
Page 2
rpc_clnt_create(3R)rpc_clnt_create(3R)
CLIENT *
clnt_create_vers(const char *host, u_long prognum,
u_long *vers_out, u_long vers_low,
u_long vers_high, const char *proto);
Generic client creation with version checking. The server must
support a version between vers_low and vers_high, inclusive. An
error results if this can not be done. The value of *vers_out is
set to the highest server-supported value.
void
clnt_destroy(CLIENT *clnt);
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 socket, or CLSET_FD_CLOSE
was set using clnt_control, it will be closed. Otherwise, the
socket remains open and it is the responsibility of the caller to
close the socket.
CLIENT *
clnt_dg_create(int sock, const struct netbuf *svcaddr,
u_long prognum, u_long versnum,
u_int sendsz, u_int recvsz);
BSD TI-RPC only. This routine creates an RPC client for the remote
program prognum and version versnum; the client uses a
connectionless (e.g. UDP) transport. The remote program is located
at address svcaddr. The parameter sock is an open socket of type
SOCK_DGRAM. This routine returns NULL if it fails. This routine
will set the resend timeout to 15 seconds; 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.
void
clnt_pcreateerror(const char *s);
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. Should be used when a
client creation function call (e.g. clnt_create, clntraw_create,
clnttcp_create, etc) fails.
CLIENT *
clntraw_create(u_long prognum, u_long versnum);
This routine creates a toy RPC client 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
Page 3
rpc_clnt_create(3R)rpc_clnt_create(3R)
svcraw_create in rpc(3R)). This allows simulation of RPC and
acquisition of RPC overheads, such as round trip times, without any
kernel interference. This routine returns NULL if it fails.
clntraw_create should be called after svcraw_create.
CLIENT *
clnt_raw_create(u_long prognum, u_long versnum);
BSD TI-RPC only. Same as clntraw_create.
char *
clnt_spcreateerror(const char *s);
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.
Note: returns a pointer to static data that is overwritten on each
call.
CLIENT *
clnttcp_create(struct sockaddr_in *addr,
u_long prognum, u_long versnum,
int *sockp, u_int sendsize, u_int recvsize);
This routine creates an RPC client for the remote program prognum,
version versnum; the client uses TCP/IPv4 as a transport. The remote
program is located at Internet address *addr. If addr->sin_port is
0, then it is set to the actual port that the remote program is
listening on (the remote portmap service is consulted for this
information). The parameter sockp is a socket; if it is RPC_ANYSOCK,
then this routine opens a new one and sets *sockp. Since TCP-based
RPC uses buffered I/O, the user may specify the size of the send and
receive buffers with the parameters sendsize and recvsize; values of
0 choose suitable defaults. This routine returns NULL if it fails.
CLIENT *
clnt_tli_create(int sock, const struct netconfig *netconf,
const struct netbuf *svcaddr, u_long prognum,
u_long versnum, u_int sendsz,
u_int recvsz);
BSD TI-RPC only. 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 if netconf
describes a connection-oriented transport, it is assumed that the
socket is connected. For connectionless transports, if svcaddr is
NULL, RPC_UNKNOWNADDR error is set. sock is a socket which may be
open and connected. If it is RPC_ANYSOCK, the function creates a
socket on the transport specified by netconf. If netconf is NULL, a
RPC_UNKNOWNPROTO error is set. For connection-oriented transports,
if sock is unconnected, and svcaddr is not NULL, the function will
Page 4
rpc_clnt_create(3R)rpc_clnt_create(3R)
attempt to connect. 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_pcreaterror routine can be used to print the reason for
failure. The remote portmap service [see portmap(1M)] will not be
consulted for the address of the remote service.
CLIENT *
clnt_tp_create(const char *host, u_long prognum,
u_long versnum, const struct netconfig *netconf);
BSD TI-RPC only. clnt_tp_create creates a client handle for the
transport specified by netconf. Default options are set, which can
be changed using clnt_control calls. The remote portmap service on
the host host is consulted for the address of the remote service.
This routine returns NULL if it fails. The clnt_pcreaterror routine
can be used to print the reason for failure.
CLIENT *
clntudp_create(struct sockaddr_in *addr,
u_long prognum, u_long versnum,
struct timeval wait, int *sockp)
This routine creates an RPC client for the remote program prognum,
version versnum; the client uses use UDP/IPv4 as a transport. The
remote program is located at Internet address addr. If
addr->sin_port is 0, then it is set to actual port that the remote
program is listening on (the remote portmap service is consulted for
this information). The parameter *sockp is a socket; if it is
RPC_ANYSOCK, then this routine opens a new one and sets *sockp. The
UDP transport resends the call message in intervals of wait time
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 and
clnt_control.
Warning: since UDP-based RPC messages can only hold up to a few
kilobytes of encoded data, this transport cannot be used for
procedures that take large arguments or return huge results.
CLIENT *
clntudp_bufcreate(struct sockaddr_in *addr,
u_long prognum, u_long versnum,
struct timeval wait, int *sockp,
u_int sendsize, u_int recvsize)
Like clntudp_create, except this call allows the user to specify the
maximum packet size for sending and receiving UDP-based RPC
messages.
Page 5
rpc_clnt_create(3R)rpc_clnt_create(3R)
CLIENT *
clnt_vc_create(int sock, const struct netbuf *svcaddr,
u_long prognum, u_long versnum,
u_int sendsz, u_int recvsz);
BSD TI-RPC only. 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 sock is an open socket of type SOCK_STREAM.
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 will not
consult the remote portmap service for this information.
struct rpc_createerr rpc_createerr
A global variable whose value is set by any RPC client creation
routine that does not succeed. Use the routine clnt_pcreateerror()
to print the reason why.
SEE ALSOgetnetconfigent(3N), portmap(1M), rpc_clnt_calls(3R). rpc(3R).
Page 6