Networking Services Library Functions rpcclntcreate(3NSL)
NAME
rpcclntcreate, clntcontrol, clntcreate,
clntcreatetimed, clntcreatevers, clntcreateverstimed,
clntdestroy, clntdgcreate, clntpcreateerror,
clntrawcreate, clntspcreateerror, clnttlicreate,
clnttpcreate, clnttpcreatetimed, clntvccreate,
rpccreateerr, clntdoorcreate - library routines for deal-
ing with creation and manipulation of CLIENT handles
SYNOPSIS
#include
boolt clntcontrol(CLIENT *clnt, const uintt req, char *info);
CLIENT *clntcreate(const char *host, const rpcprogt prognum,
const rpcverst versnum, const char *nettype);
CLIENT *clntcreatetimed(const char *host, const rpcprogt prognum,
const rpcverst versnum, const nettype,
const struct timeval *timetout);
CLIENT *clntcreatevers (const char *host,
rpcverst *const rpcprogt prognum, versoutp,
const rpcverst verslow,const rpcverst vershigh,
char *nettype);
CLIENT *clntcreateverstimed(const char *host,
const rpcprogt prognum, rpcverst *versoutp,
const rpcverst verslow, const rpcverst vershigh,
char *nettype, const struct timeval *timeout);
void clntdestroy(CLIENT *clnt);
CLIENT *clntdgcreate(const int fildes,
const struct netbuf *svcaddr, const rpcprogt prognum,
const rpcverst versnum, const uintt sendsz,
const uintt recsz);
void clntpcreateerror(const char *s);
CLIENT *clntrawcreate(const rpcprogt prognum,
const rpcverst versnum);
SunOS 5.11 Last change: 1 Aug 2001 1
Networking Services Library Functions rpcclntcreate(3NSL)
char *clntspcreateerror(const char *s);
CLIENT *clnttlicreate(const int fildes,
const struct netconfig *netconf, const struct netbuf *svcaddr,
const rpcprogt prognum, const rpcverst versnum,
const uintt sendsz, const uintt recsz);
CLIENT *clnttpcreate(const char *host,
const rpcprogt prognum, const rpcverst versnum,
const struct netconfig *netconf);
CLIENT *clnttpcreatetimed(const char *host,
const rpcprogt prognum, const rpcverst versnum,
const struct netconfig *netconf, const struct timeval *timeout);
CLIENT *clntvccreate(const int fildes,
const struct netbuf *svcaddr, const rpcprogt prognum,
const rpcverst versnum, const uintt sendsz,
const uintt recsz);
struct rpccreateerr rpccreateerr
CLIENT *clntdoorcreate(const rpcprogt prognum,
const rpcverst versnum, const uintt sendsz);
DESCRIPTION
RPC library routines allow C language programs to make pro-
cedure calls on other machines across the network. First a
CLIENT handle is created and then the client calls a pro-
cedure 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.
These routines are MT-Safe. In the case of multithreaded
applications, the -mt option must be specified on the com-
mand line at compilation time. When the -mt option is speci-
fied, rpccreateerr() becomes a macro that enables each
thread to have its own rpccreateerr(). See threads(5).
Routines
See rpc(3NSL) for the definition of the CLIENT data struc-
ture.
SunOS 5.11 Last change: 1 Aug 2001 2
Networking Services Library Functions rpcclntcreate(3NSL)
clntcontrol() A function macro to change or
retrieve various information
about a client object. req indi-
cates the type of operation, and
info is a pointer to the infor-
mation. For both connectionless
and connection-oriented tran-
sports, the supported values of
req and their argument types and
what they do are:
CLSETIMEOUT struct timeval * set total timeout
CLGETIMEOUT struct timeval * get total timeout
If the timeout is set using
clntcontrol(), the timeout
argument passed by clntcall()
is ignored in all subsequent
calls. If the timeout value is
set to 0, clntcontrol()
immediately returns
RPCTIMEDOUT. Set the timeout
parameter to 0 for batching
calls.
CLGETSERVERADR struct netbuf * get server's address
CLGETSVCADR struct netbuf * get server's address
CLGETFD int * get associated file descriptor
CLSETFDCLOSE void close the file descriptor when
destroying the client handle
(see clntdestroy())
CLSETFDNCLOSE void do not close the file
descriptor when destroying the client handle
CLGETVERS rpcverst get the RPC program's version
number associated with the
client handle
CLSETVERS rpcverst set the RPC program's version
number associated with the
client handle. This assumes
that the RPC server for this
new version is still listening
at the address of the previous
version.
CLGETXID uint32t get the XID of the previous
remote procedure call
CLSETXID uint32t set the XID of the next
remote procedure call
CLGETPROG rpcprogt get program number
CLSETPROG rpcprogt set program number
The following operations are
valid for connection-oriented
SunOS 5.11 Last change: 1 Aug 2001 3
Networking Services Library Functions rpcclntcreate(3NSL)
transports only:
CLSETIOMODE rpciomodet* set the IO mode used
to send one-way requests. The argument for this operation
can be either:
- RPCLBLOCKING all sending operations block
until the underlying transport protocol has
accepted requests. If you specify this argument
you cannot use flush and getting and setting buffer
size is meaningless.
- RPCLNONBLOCKING sending operations do not
block and return as soon as requests enter the buffer.
You can now use non-blocking I/O. The requests in the
buffer are pending. The requests are sent to
the server as soon as a two-way request is sent
or a flush is done. You are responsible for flushing
the buffer. When you choose RPCLNONBLOCKING argument
you have a choice of flush modes as specified by
CLSETFLUSHMODE.
CLGETIOMODE rpciomodet* get the current IO mode
CLSETFLUSHMODE rpcflushmodet* set the flush mode.
The flush mode can only be used in non-blocking I/O mode.
The argument can be either of the following:
- RPCLBESTEFORTFLUSH: All flushes send requests
in the buffer until the transport end-point blocks.
If the transport connection is congested, the call
returns directly.
- RPCLBLOCKINGFLUSH: Flush blocks until the
underlying transport protocol accepts all pending
requests into the queue.
CLGETFLUSHMODE rpcflushmodet* get the current flush mode.
CLFLUSH rpcflushmodet flush the pending requests.
This command can only be used in non-blocking I/O mode.
The flush policy depends on which of the following
parameters is specified:
- RPCLDEFAULTFLUSH, or NUL: The flush is done
according to the current flush mode policy
(see CLSETFLUSHMODE option).
- RPCLBESTEFORTFLUSH: The flush tries
to send pending requests without blocking; the call
returns directly. If the transport connection is
congested, this call could return without the request
being sent.
- RPCLBLOCKINGFLUSH: The flush sends all pending
requests. This call will block until all the requests
have been accepted by the transport layer.
CLSETCONMAXRECSIZE int* set the buffer size.
It is not possible to dynamically
resize the buffer if it contains data.
The default size of the buffer is 16 kilobytes.
CLGETCONMAXRECSIZE int* get the current size of the
buffer
SunOS 5.11 Last change: 1 Aug 2001 4
Networking Services Library Functions rpcclntcreate(3NSL)
CLGETCURENTRECSIZE int* get the size of
the pending requests stored in the buffer. Use of this
command is only recommended when you are in non-blocking
I/O mode. The current size of the buffer is always zero
when the handle is in blocking mode as the buffer is not
used in this mode.
The following operations are
valid for connectionless tran-
sports only:
CLSETRETRYTIMEOUT struct timeval * set the retry timeout
CLGETRETRYTIMEOUT struct timeval * get the retry timeout
The retry timeout is the time
that RPC waits for the server to
reply before retransmitting the
request.
clntcontrol() returns TRUE on
success and FALSE on failure.
clntcreate() 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 variable or in top to
bottom order in the netconfig
database.
clntcreate() 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
clntcontrol(). This routine
returns NUL if it fails. The
clntpcreateerror() routine can
be used to print the reason for
failure.
Note that clntcreate() returns
a valid client handle even if
the particular version number
SunOS 5.11 Last change: 1 Aug 2001 5
Networking Services Library Functions rpcclntcreate(3NSL)
supplied to clntcreate() is not
registered with the rpcbind ser-
vice. This mismatch will be
discovered by a clntcall later
(see rpcclntcalls(3NSL)).
clntcreatetimed() Generic client creation routine
which is similar to
clntcreate() but which also has
the additional parameter timeout
that specifies the maximum
amount of time allowed for each
transport class tried. In all
other respects, the
clntcreatetimed() call behaves
exactly like the clntcreate()
call.
clntcreatevers() Generic client creation routine
which is similar to
clntcreate() but which also
checks for the version availa-
bility. host identifies the name
of the remote host where the
server is located. nettype indi-
cates the class transport proto-
cols to be used. If the routine
is successful it returns a
client handle created for the
highest version between verslow
and vershigh that is supported
by the server. versoutp is set
to this value. That is, after a
successful return verslow <=
*versoutp <= vershigh. If no
version between verslow and
vershigh is supported by the
server then the routine fails
and returns NUL. A default
timeout is set and can be modi-
fied using clntcontrol(). This
routine returns NUL if it
fails. The clntpcreateerror()
routine can be used to print the
reason for failure.
Note: clntcreate() returns a
valid client handle even if the
particular version number sup-
plied to clntcreate() is not
SunOS 5.11 Last change: 1 Aug 2001 6
Networking Services Library Functions rpcclntcreate(3NSL)
registered with the rpcbind ser-
vice. This mismatch will be
discovered by a clntcall later
(see rpcclntcalls(3NSL)). How-
ever, clntcreatevers() does
this for you and returns a valid
handle only if a version within
the range supplied is supported
by the server.
clntcreateverstimed() Generic client creation routine
similar to clntcreatevers()
but with the additional parame-
ter timeout, which specifies
the maximum amount of time
allowed for each transport class
tried. In all other respects,
the clntcreateverstimed()
call behaves exactly like the
clntcreatevers() call.
clntdestroy() A function macro that destroys
the client's RPC handle. Des-
truction usually involves deal-
location of private data struc-
tures, including clnt itself.
Use of clnt is undefined after
calling clntdestroy(). If the
RPC library opened the associ-
ated file descriptor, or
CLSETFDCLOSE was set using
clntcontrol(), the file
descriptor will be closed.
The caller should call
authdestroy(clnt->clauth)
(before calling clntdestroy())
to destroy the associated AUTH
structure (see
rpcclntauth(3NSL)).
clntdgcreate() 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
SunOS 5.11 Last change: 1 Aug 2001 7
Networking Services Library Functions rpcclntcreate(3NSL)
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
clntcall() (see clntcall() in
rpcclntcalls(3NSL)). The retry
time out and the total time out
periods can be changed using
clntcontrol(). 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 NUL if it
fails.
clntpcreateerror() 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.
clntrawcreate() 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 svcrawcreate() in
rpcsvccreate(3NSL)). This
allows simulation of RPC and
measurement of RPC overheads,
such as round trip times,
without any kernel or networking
interference. This routine
returns NUL if it fails.
clntrawcreate() should be
called after svcrawcreate().
clntspcreateerror() Like clntpcreateerror(), except
that it returns a string instead
of printing to the standard
error. A newline is not appended
SunOS 5.11 Last change: 1 Aug 2001 8
Networking Services Library Functions rpcclntcreate(3NSL)
to the message in this case.
Warning: returns a pointer to a
buffer that is overwritten on
each call. In multithread appli-
cations, this buffer is imple-
mented as thread-specific data.
clnttlicreate() 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 NUL and it is
connection-oriented, it is
assumed that the file descriptor
is connected. For connectionless
transports, if svcaddr is NUL,
RPCUNKNOWNADR error is set.
fildes is a file descriptor
which may be open, bound and
connected. If it is RPCANYFD,
it opens a file descriptor on
the transport specified by
netconf. If fildes is RPCANYFD
and netconf is NUL, a
RPCUNKNOWNPROTO 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 connec-
tionless), clnttlicreate()
calls appropriate client crea-
tion routines. This routine
returns NUL if it fails. The
clntpcreateerror() routine can
be used to print the reason for
failure. The remote rpcbind ser-
vice (see rpcbind(1M)) is not
consulted for the address of the
remote service.
clnttpcreate() Like clntcreate() except
clnttpcreate() tries only one
transport specified through
SunOS 5.11 Last change: 1 Aug 2001 9
Networking Services Library Functions rpcclntcreate(3NSL)
netconf.
clnttpcreate() 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
clntcontrol() calls. The remote
rpcbind service on the host host
is consulted for the address of
the remote service. This routine
returns NUL if it fails. The
clntpcreateerror() routine can
be used to print the reason for
failure.
clnttpcreatetimed() Like clnttpcreate() except
clnttpcreatetimed() has the
extra parameter timeout which
specifies the maximum time
allowed for the creation attempt
to succeed. In all other
respects, the
clnttpcreatetimed() call
behaves exactly like the
clnttpcreate() call.
clntvccreate() 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 descrip-
tor. 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 NUL if it
fails.
The address svcaddr should not
be NUL and should point to the
actual address of the remote
program. clntvccreate() does
not consult the remote rpcbind
service for this information.
SunOS 5.11 Last change: 1 Aug 2001 10
Networking Services Library Functions rpcclntcreate(3NSL)
rpccreateerr() A global variable whose value is
set by any RPC client handle
creation routine that fails. It
is used by the routine
clntpcreateerror() to print the
reason for the failure.
In multithreaded applications,
rpccreateerr becomes a macro
which enables each thread to
have its own rpccreateerr.
clntdoorcreate() This routine creates an RPC
client handle over doors for the
given program prognum and ver-
sion versnum. Doors is a tran-
sport mechanism that facilitates
fast data transfer between
processes on the same machine.
The user may set the size of the
send buffer with the parameter
sendsz. If sendsz is 0, the
corresponding default buffer
size is 16 Kbyte. The
clntdoorcreate() routine
returns NUL if it fails and
sets a value for rpccreateerr.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 1 Aug 2001 11
Networking Services Library Functions rpcclntcreate(3NSL)
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture All
Availability SUNWcsl (32-bit)
SUNWcslx (64-bit)
Interface Stability Evolving
MT-Level MT-Safe
SEE ALSO
rpcbind(1M), rpc(3NSL), rpcclntauth(3NSL),
rpcclntcalls(3NSL), rpcsvccreate(3NSL),
svcrawcreate(3NSL), threads(5), attributes(5)
SunOS 5.11 Last change: 1 Aug 2001 12
|
