clnt_sperror man page on DigitalUNIX

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

rpc_clnt(3)							   rpc_clnt(3)

NAME
       rpc_clnt,  callrpc,  clnt_broadcast,  clnt_call, clnt_create, clnt_con‐
       trol,  clnt_destroy,  clnt_freeres,   clnt_geterr,   clnt_pcreateerror,
       clnt_perrno,  clnt_perror, clnt_spcreateerror, clnt_sperrno, clnt_sper‐
       ror, clntraw_create, clnttcp_create, clntudp_bufcreate,	clntudp_create
       - library routines for client ONC remote procedure calls

SYNOPSIS
       #include <rpc/rpc.h>

       callrpc(
	       char *host,
	       u_int prognum,
	       u_int versnum,
	       u_int procnum,
	       xdrproc_t inproc,
	       char *in,
	       xdrproc_t outproc,
	       char *out ); enum clnt_stat clnt_broadcast(
	       u_int prognum,
	       u_int versnum,
	       u_int procnum,
	       xdrproc_t inproc,
	       char *in,
	       xdrproc_t outproc,
	       char *out,
	       resultproc_t eachresult ); eachresult(
	       char *out,
	       struct sockaddr_in *addr ); enum clnt_stat clnt_call(
	       CLIENT *clnt,
	       u_int procnum,
	       xdrproc_t inproc,
	       char *in,
	       xdrproc_t outproc,
	       char *out,
	       struct timeval tout ); clnt_destroy(
	       CLIENT *clnt ); CLIENT * clnt_create(
	       char *host,
	       u_int prog,
	       u_int vers,
	       char *proto ); bool_t clnt_control(
	       CLIENT *cl,
	       int req,
	       char *info ); clnt_freeres(
	       CLIENT *clnt,
	       xdrproc_t outproc,
	       char *out ); void clnt_geterr(
	       CLIENT *clnt,
	       struct rpc_err *errp ); void clnt_pcreateerror(
	       char *s ); void clnt_perrno(
	       enum clnt_stat stat ); clnt_perror(
	       CLIENT *clnt,
	       char *s ); char * clnt_spcreateerror(
	       char *s ); char * clnt_sperrno(
	       enum clnt_stat stat ); char * clnt_sperror(
	       CLIENT *rpch,
	       char *s ); CLIENT * clntraw_create(
	       u_int prognum,
	       u_int versnum ); CLIENT * clnttcp_create(
	       struct sockaddr_in *addr,
	       u_int prognum,
	       u_int versnum,
	       int *sockp,
	       u_int sendsz,
	       u_int recvsz ); CLIENT * clntudp_bufcreate(
	       struct sockaddr_in *addr,
	       u_int prognum,
	       u_int versnum,
	       struct timeval wait,
	       int *sockp,
	       u_int sendsz,
	       u_int recvsz ); CLIENT * clntudp_create(
	       struct sockaddr_in *addr,
	       u_int prognum,
	       u_int versnum,
	       struct timeval wait,
	       int *sockp );

DESCRIPTION
       These  routines	allow  C  programs  to	make  procedure calls on other
       machines across the network.  First, 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. Finally, the procedure call returns to the
       client.

       Unless otherwise indicated, the routines described  in  this  reference
       page  are  thread  safe	(that  is, they can be used safely in a multi‐
       threaded environment). Routines that are not thread safe are flagged as
       such.

       Calls  the remote procedure associated with prognum, versnum, and proc‐
       num on the machine host. The in parameter is the address of the	proce‐
       dure's  argument(s),  and  out  is  the	address	 of where to place the
       result(s); inproc is used to encode  the	 procedure's  parameters,  and
       outproc is used to decode the procedure's results. This routine returns
       zero if it succeeds, or the value of enum clnt_stat cast to an  integer
       if it fails. The clnt_perrno() routine is handy for translating failure
       statuses into messages.

	      Warning: Calling remote procedures with this routine uses UDP/IP
	      as  a  transport;	 see clntudp_create() for restrictions. You do
	      not have control of timeouts or authentication using  this  rou‐
	      tine.   Like  callrpc(), except the call message is broadcast to
	      all locally connected broadcast nets. Each time  it  receives  a
	      response,	 this routine calls the eachresult() routine.  The out
	      parameter is the same as the out parameter passed to clnt_broad‐
	      cast(),  except  that  the  remote procedure's output is decoded
	      there; addr points to the address of the machine that  sent  the
	      results.

	      If  eachresult()	returns	 zero, clnt_broadcast() waits for more
	      replies; otherwise,  it  returns	with  appropriate  status.  If
	      eachresult()  is	NULL, clnt_broadcast() returns without waiting
	      for any replies.

	      Warning: Broadcast sockets are limited in size  to  the  maximum
	      transfer unit of the data link. For Ethernet, the caller's argu‐
	      ment size should not exceed 1400 bytes.  A macro that calls  the
	      remote  procedure	 procnum  associated  with  the client handle,
	      clnt, which is obtained with an RPC client creation routine such
	      as  clnt_create(). The in parameter is the address of the proce‐
	      dure's argument(s), and out is the address of where to place the
	      result(s);  inproc is used to encode the procedure's parameters,
	      and outproc is used to decode the procedure's results;  tout  is
	      the  time	 allowed  for  results	to  come  back.	  A 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, it will close it also.
	      Otherwise, the socket remains  open.   Generic  client  creation
	      routine.	The  host  parameter identifies the name of the remote
	      host where the server is located. The proto parameter  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:	Since  UDP-based  RPC  messages	 can only hold up to 8
	      Kbytes of encoded data, this transport cannot be used for proce‐
	      dures that take large arguments or return huge results.  A macro
	      that is used to change or retrieve various information  about  a
	      client  object.  The  req parameter indicates the type of opera‐
	      tion, and info is a pointer to the  information.	 For  UDP  and
	      TCP, req has the following supported values, argument types, and
	      purposes:

	      CLSET_TIMEOUT	 struct timeval	  Set total timeout
	      CLGET_TIMEOUT	 struct timeval	  Get total timeout
	      CLGET_FD		 int		  Get associated socket
	      CLSET_FD_CLOSE	 void		  Close	   socket    on
						  clnt_destroy()
	      CLSET_FD_NOCLOSE	 void		  Leave	 socket open on
						  clnt_destroy()

					    Note

	      If you set the timeout using clnt_control(), the timeout parame‐
	      ter passed to clnt_call() will be ignored in all future calls.

	      CLGET_SERVER_ADDR	  struct sockaddr   Get server's address

	      The following operations are valid for UDP 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 UDP RPC waits for the server
	      to reply before retransmitting the request.  A macro that	 frees
	      any  data	 allocated  by	the RPC/XDR system when it decoded the
	      results of an RPC call. The out parameter is the address of  the
	      results,	and outproc is the XDR routine describing the results.
	      This routine returns one (1) if the  results  were  successfully
	      freed,  and  zero	 (0) otherwise.	 A macro that copies the error
	      structure out of the client handle to the structure  at  address
	      errp.   Prints  a	 message  to  standard	error indicating why a
	      client RPC handle could not be created. The message is prepended
	      with   string   s	 and  a	 colon.	 Used  when  a	clnt_create(),
	      clntraw_create(),	 clnttcp_create(),  or	clntudp_create()  call
	      fails.   Prints a message to standard error corresponding to the
	      condition indicated by stat. Used	 after	callrpc().   Prints  a
	      message  to  standard  error  indicating why an RPC call failed;
	      clnt is the handle used to do the call. The message is prepended
	      with  string  s  and  a  colon.  Used  after  clnt_call().  Like
	      clnt_pcreateerror(), except that it returns a string instead  of
	      printing to the standard error.

					    Note

	      Returns pointer to static data that is overwritten on each call.
	      Takes the same arguments as clnt_perrno(), but instead of	 send‐
	      ing  a  message to the standard error indicating why an RPC call
	      failed, returns a pointer to a string that contains the message.
	      The string ends with a NEWLINE.

	      clnt_sperrno()  is  used instead of clnt_perrno() if the program
	      does not have a standard error (as a program running as a server
	      quite  likely  does not), or if the programmer does not want the
	      message to be output with printf, or if a message format differ‐
	      ent than that supported by clnt_perrno() is to be used.

					    Note

	      Unlike  clnt_sperror()  and  clnt_spcreaterror(), clnt_sperrno()
	      does not return pointer to static data so the result will not be
	      overwritten on each call.	 Like clnt_perror(), except that, like
	      clnt_sperrno(), it returns a string instead of printing to stan‐
	      dard error.

					    Note

	      Returns pointer to static data that is overwritten on each call.
	      Creates a toy RPC client for the remote program prognum, version
	      versnum.	The  transport used to pass messages to the service is
	      actually a buffer within the process's  address  space,  so  the
	      corresponding  RPC server should live in the same address space;
	      see svcraw_create(). This allows simulation of RPC and  acquisi‐
	      tion  of	RPC  overheads,	 such as round-trip times, without any
	      kernel interference. This routine	 returns  NULL	if  it	fails.
	      Creates  an  RPC	client for the remote program prognum, version
	      versnum; the client uses TCP/IP as a transport.  The remote pro‐
	      gram  is located at Internet address addr.  If addr->sin_port is
	      zero, 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,  this  routine  opens  a new socket 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 sendsz and recvsz
	      parameters; values of zero choose suitable defaults.  This  rou‐
	      tine  returns  NULL  if it fails.	 Like clntudp_create(), except
	      that this routine allows the size of the maximum UDP packet that
	      can  be sent or received to be specified.	 If sendz or recvsz is
	      set to 0, a default maximum size is used.	 Creates an RPC client
	      for the remote program prognum, version versnum; the client uses
	      use UDP/IP as a transport. The  remote  program  is  located  at
	      Internet address addr. If addr->sin_port is zero, 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, this  routine
	      opens a new socket 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().

	      Warning: Since UDP-based RPC messages can	 only  hold  up	 to  8
	      Kbytes of encoded data, this transport cannot be used for proce‐
	      dures that take large arguments or return huge results.

SEE ALSO
       rpc_misc(3), rpc_svc(3), rpc_xdr(3), xdr(3)

       Remote Procedure Calls: Protocol Specifications -- RFC 1050

								   rpc_clnt(3)
[top]

List of man pages available for DigitalUNIX

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