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_CALLS(3N)                                          RPC_CLNT_CALLS(3N)



NAME
       callrpc,    clnt_broadcast,   clnt_call,   clnt_freeres,   clnt_geterr,
       clnt_perrno, clnt_perror, clnt_sperrno, clnt_sperror - library routines
       for client side calls

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  clnt_call(),  callrpc()  and  clnt_broadcast() routines handle the
       client side of the procedure call.  The remaining  routines  deal  with
       error handling in the case of errors.

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

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

       int callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out)
       char *host;
       u_long prognum, versnum, procnum;
       char *in;
       xdrproc_t inproc;
       char *out;
       xdrproc_t outproc;

              Call the remote procedure associated with prognum, versnum,  and
              procnum  on  the machine, host.  The parameter in is the address
              of the procedure's argument, and out is the address of where  to
              place  the  result; inproc is an XDR function used to encode the
              procedure's parameters, and outproc is an XDR function  used  to
              decode  the  procedure's  results.  This routine returns 0 if it
              succeeds, or the value of enum clnt_stat cast to an  integer  if
              it  fails.  Use clnt_perrno() to translate failure statuses into
              messages.

              Warning: Calling remote procedures with this routine uses UDP/IP
              as  the  transport;  see clntudp_create() on rpc_clnt_create(3N)
              for restrictions.  You  do  not  have  control  of  timeouts  or
              authentication using this routine.

       enum clnt_stat clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresult)
       u_long prognum, versnum, procnum;
       char *in;
       xdrproc_t inproc;
       char *out;
       xdrproc_t outproc;
       bool_t eachresult;

              Like  callrpc(),  except  the  call  message is broadcast to all
              locally connected broadcast nets. Each time the caller  receives
              a response, this routine calls eachresult(), whose form is:
                 int eachresult(out, addr)
                 char *out;
                 struct sockaddr_in *addr;

              where  out is the same as out passed to clnt_broadcast(), except
              that the remote procedure's output is decoded there; addr points
              to the address of the machine that sent the results.  If eachre-
              sult() returns 0 clnt_broadcast() waits for more replies; other-
              wise  it  returns  with  appropriate status.  If eachresult() is
              NULL, clnt_broadcast() returns without waiting for any replies.

              Note: clnt_broadcast() uses AUTH_UNIX style of authentication.

              Warning: Broadcast packets are limited in size  to  the  maximum
              transfer unit of the data link.  For Ethernet, the callers argu-
              ment size should not exceed 1400 bytes.

       enum clnt_stat clnt_call(clnt, procnum, inproc, in, outproc, out, timeout)
       CLIENT *clnt;
       u_long procnum;
       xdrproc_t inproc, outproc;
       char *in, *out;
       struct timeval timeout;

              Call the remote procedure procnum  associated  with  the  client
              handle, clnt, which is obtained with an RPC client creation rou-
              tine such as clnt_create() (see rpc_clnt_create(3N).  The param-
              eter  in  is the address of the procedure's argument, and out is
              the address of where to place the result; inproc is an XDR func-
              tion  used to encode the procedure's parameters in XDR, and out-
              proc is used to decode the procedure's results; timeout  is  the
              time allowed for a response from the server.

       bool_t clnt_freeres(clnt, outproc, out)
       CLIENT *clnt;
       xdrproc_t outproc;
       char *out;

              Free  any  data  allocated by the RPC/XDR system when it decoded
              the results of an RPC call.  The parameter out is the address of
              the  results,  and  outproc  is  the  XDR routine describing the
              results.  This routine returns TRUE if the results were success-
              fully  freed,  and FALSE otherwise.  Note: This is equivalent to
              doing xdr_free(outproc, out) (see xdr_simple(3N)).

       void clnt_geterr(clnt, errp)
       CLIENT *clnt;
       struct rpc_err *errp;

              Copy the error structure out of the client handle to the  struc-
              ture at address errp.  errp should point to preallocated space.

       void clnt_perrno(stat)
       enum clnt_stat stat;

              Print  a message to the standard error corresponding to the con-
              dition indicated by stat.  A NEWLINE is appended at the  end  of
              the message.  Used after callrpc() or clnt_broadcast().

       void clnt_perror(clnt, str)
       CLIENT *clnt;
       char *str;

              Print a message to the 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.  A NEWLINE is appended at
              the end of the message.  Used after clnt_call().

       char *clnt_sperrno(stat)
       enum clnt_stat stat;

              Take the same arguments as clnt_perrno(), but instead of sending
              a  message  to  the standard error indicating why an RPC failed,
              return a  pointer  to  a  string  which  contains  the  message.
              clnt_sperrno()  does not append a NEWLINE at the end of the mes-
              sage.

              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(3V), or if a message format
              different than that supported by clnt_perrno() is to be used.

       char *clnt_sperror(clnt, str)
       CLIENT *clnt;
       char *str;

              Like clnt_perror(), except that (like clnt_sperrno()) it returns
              a  string  instead  of  printing  to the standard error.  Unlike
              clnt_perror(), it does not append the message with a NEWLINE.

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

SEE ALSO
       printf(3V),  rpc(3N),  rpc_clnt_auth(3N), rpc_clnt_create(3N), xdr_sim-
       ple(3N)



                                20 January 1990             RPC_CLNT_CALLS(3N)