clnt_pcreateerror man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

rpc_clnt_create(3N)					   rpc_clnt_create(3N)

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_spcre‐
       ateerror(),    clnt_tli_create(),    clnt_tp_create(),	  clnt_tp_cre‐
       ate_timed(),  clnt_vc_create(),	rpc_createerr  -  library routines for
       dealing with creation and manipulation of CLIENT handles

SYNOPSIS

DESCRIPTION
       RPC library routines allow C language programs to make procedure	 calls
       on  other  machines  across the network.	 First a 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.

       These routines are thread-safe.	In the case of multithreaded  applica‐
       tions, the flag must be defined on the command line at compilation time
       When the flag is defined, becomes a macro which enables each thread  to
       have its own

       The  HP-UX  implementation  of  RPC  only supports the X/Open Transport
       Interface (XTI).	 Applications that are	written	 using	the  Transport
       Layer  Interface (TLI) and wish to use RPC, must convert their applica‐
       tion to XTI.

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

       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 the timeout argument passed by is
	      ignored in all subsequent calls.

	      If the timeout value is set to immediately returns Set the time‐
	      out parameter to 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 the 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		unsigned long *	 get the XID of the previous
						 remote procedure call
	      CLSET_XID		unsigned long *	 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
	      transports only:
	      CLSET_IO_MODE	     rpciomode_t *     set the IO mode used
						       to send one-way requests.

	      The argument for this operation can be either:

	      All sending operations block until the underlying transport pro‐
	      tocol
		     has  accepted requests.  If you specify this argument you
		     cannot use flush and getting and setting buffer  size  is
		     meaningless.

	      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 the argument you have  a	choice
		     of flush modes as specified by

	      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 for this operation can be either:

	      All flushes send requests in the buffer until the transport end-
	      point
		   blocks.  If the transport connection is congested, the call
		   returns directly.

	      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:

	      The flush is done according to the current flush mode policy
		   (see the option).

	      The flush tries to send pending requests without	blocking;  the
	      call
		   returns  directly.	If  the	 transport  connection is con‐
		   gested, this call could return without  the	request	 being
		   sent.

	      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
	      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.

	      returns on success and on failure.

       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 variable or in top to bottom order in the
	      netconfig database.

	      tries all the transports of the nettype class available from the
	      environment variable and the netconfig database, and chooses the
	      first successful one.  A default timeout is set and can be modi‐
	      fied  using  This routine returns NULL if it fails.  The routine
	      can be used to print the reason for failure.

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

       Generic client creation routine which is similar to
	      but  with	 the additional parameter timeout, which specifies the
	      maximum amount of time allowed for each transport	 class	tried.
	      In all other respects, the call behaves exactly like the call.

       Generic client creation routine which is similar to
	      but  which also checks for the version availability.  host iden‐
	      tifies 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 sup‐
	      ported 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 time‐
	      out is set and can be modified using This routine	 returns  NULL
	      if  it  fails.   The routine can be used to print the reason for
	      failure.

	      Note: returns a valid client handle even if the particular  ver‐
	      sion  number  supplied  to  is  not registered with the service.
	      This   mismatch	will   be   discovered	 by   a	  later	  (see
	      rpc_clnt_calls(3N)).   However,  does this for you and returns a
	      valid handle only if a version within the range supplied is sup‐
	      ported by the server.

       Generic client creation routine which is similar to
	      but  with	 the additional parameter timeout, which specifies the
	      maximum amount of time allowed for each transport	 class	tried.
	      In all other respects, the call behaves exactly like the call.

       A function macro that destroys the client's RPC handle.
	      Destruction usually involves deallocation of private data struc‐
	      tures, including clnt itself.  Use of clnt  is  undefined	 after
	      calling  If  the RPC library opened the associated file descrip‐
	      tor, or was set using the file descriptor will be closed.

	      The caller should call (before calling to destroy the associated
	      AUTH structure (see rpc_clnt_auth(3N)).

       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  (see  in
	      rpc_clnt_calls(3N)).   The  retry	 timeout and the total timeout
	      periods can be changed using The user may set the	 size  of  the
	      send  and receive buffers with the parameters sendsz and recvsz;
	      values of choose suitable defaults.  This routine	 returns  NULL
	      if it fails.

       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.

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

       Like   except that it returns a string instead of printing to the stan‐
	      dard  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 multithreaded applications, this buffer is imple‐
	      mented as thread-specific data.

       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-ori‐
	      ented, it is assumed that the file descriptor is connected.  For
	      connectionless  transports,  if  svcaddr	is NULL, error is set.
	      fildes is a file descriptor which may be open,  bound  and  con‐
	      nected.	If  it	is it opens a file descriptor on the transport
	      specified by netconf.  If fildes is and netconf is NULL, a 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 choose suitable
	      defaults.	 Depending upon the type of the transport (connection-
	      oriented	or  connectionless), calls appropriate client creation
	      routines.	 This routine returns NULL if it fails.	  The  routine
	      can be used to print the reason for failure.  The remote service
	      (see rpcbind(1M)) is not consulted for the address of the remote
	      service.

       Like   except tries only one transport specified through netconf.

	      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 calls.  The remote
	      service on the host host is consulted for	 the  address  of  the
	      remote  service.	 This  routine	returns NULL if it fails.  The
	      routine can be used to print the reason for failure.

       Like   except has the extra parameter timeout which specifies the maxi‐
	      mum  time	 allowed  for the creation attempt to succeed.	In all
	      other respects, the call behaves exactly like the call.

       This routine creates an RPC client for the remote program
	      prognum and version versnum; the client uses  a  connection-ori‐
	      ented  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
	      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.  does not consult the
	      remote service for this information.

       A global variable whose value is set by any RPC
	      client handle creation routine that fails.  It is	 used  by  the
	      routine to print the reason for the failure.

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

MULTITHREAD USAGE
       Thread Safe:	     Yes
       Cancel Safe:	     Yes
       Fork Safe:	     No
       Async-cancel Safe:    No
       Async-signal Safe:    No

       These functions can be called safely in	a  multithreaded  environment.
       They  may  be  cancellation points in that they call functions that are
       cancel points.

       In a multithreaded environment, these functions	are  not  safe	to  be
       called  by  a child process after and before These functions should not
       be called by a multithreaded  application  that	supports  asynchronous
       cancellation or asynchronous signals.

SEE ALSO
       rpc(3N), rpc_clnt_auth(3N), rpc_clnt_calls(3N), rpcbind(1M).

							   rpc_clnt_create(3N)
[top]

List of man pages available for HP-UX

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