clnt_control man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

rpc_clnt_create(3NSL)Networking Services Library Functionrpc_clnt_create(3NSL)

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_cre‐
       ate,  clnt_tp_create,  clnt_tp_create_timed,  clnt_vc_create,  rpc_cre‐
       ateerr,	clnt_door_create  - library routines for dealing with creation
       and manipulation of CLIENT handles

SYNOPSIS
       #include <rpc/rpc.h>

       bool_t clnt_control(CLIENT *clnt, const uint_t 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   nettype,   const   struct   timeval
       *timetout);

       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);

       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 uint_t  sendsz,
       const uint_t recsz);

       void  clnt_pcreateerror(const char *s);

       CLIENT  *clnt_raw_create(const  rpcprog_t prognum, const rpcvers_t ver‐
       snum);

       char *clnt_spcreateerror(const char *s);

       CLIENT *clnt_tli_create(const int fildes, const struct netconfig	 *net‐
       conf,  const  struct  netbuf  *svcaddr,	const rpcprog_t prognum, const
       rpcvers_t versnum, const uint_t sendsz, const uint_t recsz);

       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, const uint_t  sendsz,
       const uint_t recsz);

       struct rpc_createerr rpc_createerr

       CLIENT  *clnt_door_create(const rpcprog_t prognum, const rpcvers_t ver‐
       snum, const uint_t sendsz);

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.

       These routines are MT-Safe. In the case of multithreaded	 applications,
       the  -mt	 option	 must  be specified on the command line at compilation
       time. When the -mt option is specified, rpc_createerr() becomes a macro
       that   enables  each  thread  to	 have  its  own	 rpc_createerr().  See
       threads(5).

   Routines
       See rpc(3NSL) for the definition of the CLIENT data structure.

       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

	    If the timeout is set using clnt_control(), the  timeout  argument
	   passed  by  clnt_call()  is ignored in all subsequent calls. If the
	   timeout value is set	 to   0,  clnt_control()  immediately  returns
	   RPC_TIMEDOUT.  Set the timeout parameter to	0 for batching calls.

	   CLGET_SERVER_ADDR struct netbuf * get server's address
	   CLGET_SVC_ADDR struct netbuf *     get server's address
	   CLGET_FD  int *     get associated file descriptor
	   CLSET_FD_CLOSE void close the file descriptor when
		     destroying the client handle
		     (see clnt_destroy())
	   CLSET_FD_NCLOSE     void do not close the file
		     descriptor when destroying the client handle
	   CLGET_VERS	rpcvers_t get the RPC program's version
		     number associated with the
		     client handle
	   CLSET_VERS	  rpcvers_t 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.
	   CLGET_XID uint32_t  get the XID of the previous
		     remote procedure call
	   CLSET_XID uint32_t  set the XID of the next
		     remote procedure call
	   CLGET_PROG	  rpcprog_t get program number
	   CLSET_PROG	  rpcprog_t set program number

	   The	following  operations are valid for connection-oriented trans‐
	   ports only:

	   CLSET_IO_MODE rpciomode_t*	 set the IO mode used
		     to send one-way requests. The argument for this operation
		     can be either:
	      - RPC_CL_BLOCKING	    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.
	      - RPC_CL_NONBLOCKING   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 RPC_CL_NONBLOCKING argument
		     you have a choice of flush modes as specified by
		     CLSET_FLUSH_MODE.
	   CLGET_IO_MODE rpciomode_t*	      get the current IO mode
	   CLSET_FLUSH_MODE rpcflushmode_t*	   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:
		- RPC_CL_BESTEFFORT_FLUSH: All flushes send requests
		     in the buffer until the transport end-point blocks.
		     If the transport connection is congested, the call
		     returns directly.
		- RPC_CL_BLOCKING_FLUSH: Flush blocks until the
		     underlying transport protocol accepts all pending
		     requests into the queue.
	   CLGET_FLUSH_MODE rpcflushmode_t*   get the current flush mode.
	   CLFLUSH rpcflushmode_t	 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:
		- RPC_CL_DEFAULT_FLUSH, or NULL:   The flush is done
		   according to the current flush mode policy
		     (see CLSET_FLUSH_MODE option).
		- RPC_CL_BESTEFFORT_FLUSH:	   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.
		- RPC_CL_BLOCKING_FLUSH:      The flush sends all pending
		     requests. This call will block until all the requests
		     have been accepted by the transport layer.
	   CLSET_CONNMAXREC_SIZE 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.
	   CLGET_CONNMAXREC_SIZE int*	      get the current size of the
		     buffer
	   CLGET_CURRENT_REC_SIZE 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  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	proto‐
	   col to use. The transports are tried in left to right order in NET‐
	   PATH variable or in top to bottom order in the netconfig database.

	   clnt_create() tries all the transports of the nettype class	avail‐
	   able	 from the NETPATH environment variable and the netconfig data‐
	   base, 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	 that  clnt_create() returns a valid client handle even if the
	   particular version number supplied to clnt_create() is  not	regis‐
	   tered with the rpcbind service. This mismatch will be discovered by
	   a clnt_call later (see rpc_clnt_calls(3NSL)).

       clnt_create_timed()

	   Generic client creation routine which is similar  to	 clnt_create()
	   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 clnt_create_timed() call behaves 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. 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 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  par‐
	   ticular  version number supplied to clnt_create() is not registered
	   with the rpcbind service. This mismatch will	 be  discovered	 by  a
	   clnt_call  later  (see  rpc_clnt_calls(3NSL)).  However,  clnt_cre‐
	   ate_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 similar to clnt_create_vers() but
	   with the additional parameter  timeout, which 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 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(3NSL)).

       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(3NSL)).  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 han‐
	   dle could not be created. The message is prepended with the	string
	   s and a colon, and appended with a newline.

       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(3NSL)). This allows simula‐
	   tion 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_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. In multithread applications, this buffer  is  implemented  as
	   thread-specific data.

       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  connec‐
	   tionless  transports,  if svcaddr is NULL, RPC_UNKNOWNADDR error is
	   set. fildes is a file descriptor which may be open, bound and  con‐
	   nected.  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; val‐
	   ues of 0 choose suitable defaults. Depending upon the type  of  the
	   transport  (connection-oriented  or	connectionless), clnt_tli_cre‐
	   ate() 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(1M))  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_tp_create_timed()

	   Like	 clnt_tp_create()  except clnt_tp_create_timed() has the extra
	   parameter 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_cre‐
	   ate() call.

       clnt_vc_create()

	   This	 routine  creates an RPC client for the remote program prognum
	   and version versnum; the client uses a  connection-oriented	trans‐
	   port. The remote program is located at address svcaddr. The parame‐
	   ter fildes is an open and bound file descriptor. The user may spec‐
	   ify	the  size  of the send and receive buffers with the parameters
	   sendsz and recvsz; values of 0 choose suitable defaults. This  rou‐
	   tine 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.

       rpc_createerr()

	   A  global variable whose value is set by any RPC client handle cre‐
	   ation routine that fails.  It is used  by  the  routine  clnt_pcre‐
	   ateerror() to print the reason for the failure.

	   In  multithreaded applications, rpc_createerr becomes a macro which
	   enables each thread to have its own rpc_createerr.

       clnt_door_create()

	   This routine creates an RPC client handle over doors for the	 given
	   program prognum and version versnum. Doors is a transport 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 clnt_door_create() routine returns NULL if it
	   fails and sets a value for rpc_createerr.

ATTRIBUTES
       See attributes(5)  for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Architecture		     │All			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Availability		     │SUNWcsl (32-bit)		   │
       ├─────────────────────────────┼─────────────────────────────┤
       │			     │SUNWcslx (64-bit)		   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Evolving			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       rpcbind(1M),  rpc(3NSL),	  rpc_clnt_auth(3NSL),	 rpc_clnt_calls(3NSL),
       rpc_svc_create(3NSL), svc_raw_create(3NSL), threads(5), attributes(5)

SunOS 5.10			  1 Aug 2001		 rpc_clnt_create(3NSL)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net