unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

RPC_CLNT_CREATE(3N)                                        RPC_CLNT_CREATE(3N)



NAME
       clnt_control,  clnt_create,  clnt_create_vers, clnt_destroy, clnt_pcre-
       ateerror,    clntraw_create,    clnt_spcreateerror,     clnttcp_create,
       clntudp_bufcreate,  rpc_createrr  -  library  routines for dealing with
       creation and manipulation of CLIENT handles

DESCRIPTION
       RPC routines allow C programs to make procedure calls on other machines
       across  the  network.   First,  the  client calls a procedure to send a
       request to the server.  Upon receipt of the request, 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.

       The CLIENT data structure is defined in the RPC/XDR Library  Definition
       of the

       #include <&lt;rpc/rpc.h>&gt;

       bool_t clnt_control(clnt, request, info)
       CLIENT *clnt;
       int request;
       char *info;

              Change  or  retrieve  various information about a client object.
              request indicates the type of operation, and info is  a  pointer
              to  the  information. For both UDP and TCP, the supported values
              of request and their argument types and what they do are:
              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_NCLOSE     void           leave socket open on clnt_destroy()

              Note: If you set the timeout using clnt_control(),  the  timeout
              parameter passed to clnt_call() (see rpc_clnt_calls(3N)) will be
              ignored in all future calls.
              CLGET_SERVER_ADDR   struct sockaddr_in                 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.

              This routine returns TRUE on success, and FALSE on failure.

       CLIENT * clnt_create(host, prognum, versnum, protocol)
       char *host;
       u_long prognum, versnum;
       char *protocol;

              Generic  client creation routine for program prognum and version
              versnum.  host identifies the name of the remote host where  the
              server  is  located.  protocol indicates which kind of transport
              protocol to use. The currently supported values for  this  field
              are  "udp" and "tcp".  Default timeouts are set, but they can be
              modified using  clnt_control().   If  successful  it  returns  a
              client handle, otherwise it returns NULL.

              Warning:  Using  UDP  has its shortcomings.  Since UDP-based RPC
              messages can only hold up to 8  Kbytes  of  encoded  data,  this
              transport  cannot  be used for procedures that take arguments or
              return results larger than 8 Kbytes.  Use TCP instead.

              Note: If the requested version number versnum is not  registered
              with  the  portmap(8C)  service  on host, but at least a version
              number for the given program number is registered, clnt_create()
              returns  a handle.  The version mismatch will be discovered by a
              clnt_call() later (see rpc_clnt_calls(3N)).

       CLIENT * clnt_create_vers(host, prognum, vers_outp, vers_low, vers_high, protocol)
       char *host;
       u_long prognum;
       u_long *vers_outp;
       u_long vers_low, vers_high;
       char *protocol;

              This is a generic client creation routine which also checks  for
              the  version  available.  host identifies the name of the remote
              host where the server is located.  protocol indicates which kind
              of transport protocol to use. The currently supported values for
              this field are "udp" and "tcp".  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.  Default timeouts  are  set,
              but can be modified using clnt_control().

              Note:  clnt_create()  returns  a valid client handle even if the
              particular version number supplied to clnt_create() is not  reg-
              istered with the portmap service.  This mismatch will be discov-
              ered by a clnt_call() later (see rpc_clnt_calls(3N)).   However,
              clnt_create_vers()  does this for you and returns a valid handle
              only if a version within the range supplied is supported by  the
              server.

       void clnt_destroy(clnt)
       CLIENT *clnt;

              Destroy  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().  clnt_destroy() closes the socket.

       void clnt_pcreateerror(str)
       char *str;

              Print  a  message  to the standard error indicating why a client
              handle could not be created.   The  message  is  prepended  with
              string s and a colon.  Used when routines such as clnt_create(),
              clntraw_create(), clnttcp_create(), or clntudp_create() fails.

       CLIENT * clntraw_create(prognum, versnum)
       u_long prognum, versnum;

              Create an 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;
              also see svcraw_create() (see rpc_svc_create(3N)).  This  allows
              simulation  of RPC and getting RPC overheads, such as round trip
              times,  without  any  kernel  interference.   If  successful  it
              returns a client handle, otherwise it returns NULL.

       char * clnt_spcreateerror(str)
       char *str;

              Like  clnt_pcreateerror(),  except  that  it  returns  a  string
              instead of printing to the standard error.   It,  however,  does
              not append the message with a NEWLINE.

              Note:  clnt_spcreateerror() returns a pointer to a static buffer
              that is overwritten on each call.

       CLIENT * clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz)
       struct sockaddr_in *addr;
       u_long prognum, versnum;
       int *sockp;
       u_int sendsz, recvsz;

              Create a client handle 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->&gt;sin_port  is
              zero, it is set to the  port on which the remote program is lis-
              tening (the remote portmap service is consulted for this  infor-
              mation).  The parameter sockp is a pointer to a socket; if it is
              RPC_ANYSOCK, then a new socket is opened and sockp  is  updated.
              Since  TCP-based RPC uses buffered I/O, the user may specify the
              size of the send and receive buffers with the parameters  sendsz
              and  recvsz;  values  of zero choose defaults.  If successful it
              returns a client handle, otherwise it returns NULL.

              Warning: If addr->&gt;sin_port is zero  and  the  requested  version
              number  versnum  is  not registered with the remote portmap ser-
              vice, it returns a handle if at least a version number  for  the
              given  program  number is registered.  The version mismatch will
              be discovered by a clnt_call( later (see rpc_clnt_calls(3N)).

       CLIENT * clntudp_bufcreate(addr, prognum, versnum, wait, sockp, sendsz, recvsz)
       struct sockaddr_in *addr;
       u_long prognum, versnum;
       struct timeval wait;
       int *sockp;
       u_int sendsz;
       u_int recvsz;

              Create a client handle for the remote program prognum,  on  ver-
              snum;  the  client uses UDP/IP as the transport. The remote pro-
              gram is located at the Internet address addr.  If addr->&gt;sin_port
              is  zero, it is set to  port on which the remote program is lis-
              tening on (the remote portmap  service  is  consulted  for  this
              information).  The  parameter sockp is a pointer to a socket; if
              it is RPC_ANYSOCK, then a new socket  is  opened  and  sockp  is
              updated.   The  UDP transport resends the call message in inter-
              vals 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()  (see  rpc_clnt_calls(3N)).   If  successful  it
              returns a client handle, otherwise it returns NULL.

              The  user  can  specify  the maximum packet size for sending and
              receiving by using sendsz and recvsz arguments for UDP-based RPC
              messages.

              Warning:  If  addr->&gt;sin_port  is  zero and the requested version
              number versnum is not registered with the  remote  portmap  ser-
              vice,  it  returns a handle if at least a version number for the
              given program number is registered.   The  version  mismatch  is
              discovered by a clnt_call() later (see rpc_clnt_calls(3N)).

       CLIENT * clntudp_create(addr, prognum, versnum, wait, sockp)
       struct sockaddr_in *addr;
       u_long prognum, versnum;
       struct timeval wait;
       int *sockp;

              Create  a  client handle for the remote program prognum, version
              versnum; the client uses UDP/IP as  the  transport.  The  remote
              program   is   located   at   the  Internet  address  addr.   If
              addr->&gt;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
              pointer  to  a   socket;  if  it is RPC_ANYSOCK, a new socket is
              opened and sockp is updated.  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() (see rpc_clnt_calls(3N)).
              If successful it returns a client handle, otherwise  it  returns
              NULL.

              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 arguments or results larger than 8 Kbytes.  TCP
              should be used instead.

              Warning: If addr->&gt;sin_port is zero  and  the  requested  version
              number  versnum  is  not registered with the remote portmap ser-
              vice, it returns a handle if any version number  for  the  given
              program  number  is registered.  The version mismatch is be dis-
              covered by a clnt_call() later (see rpc_clnt_calls(3N)).

       struct rpc_createerr rpc_createerr;

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

SEE ALSO
       portmap(3N),    rpc(3N),     rpc_clnt_auth(3N),     rpc_clnt_calls(3N),
       rpc_svc_create(3N)



                                20 January 1990            RPC_CLNT_CREATE(3N)