clntudp_create man page on IRIX

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



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 ALSO
     getnetconfigent(3N), portmap(1M), rpc_clnt_calls(3R).  rpc(3R).

									Page 6

[top]

List of man pages available for IRIX

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