[0m


RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



[1mNAME
     [0mrpc - library routines for remote procedure calls

[1mSYNOPSIS AND DESCRIPTION
     [0mThese 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.

     [1m#include <rpc/rpc.h>

     void
     auth_destroy(auth)
     AUTH *auth;

	  [0mA macro that destroys the authentication information
	  associated with _a_u_t_h.  Destruction usually involves
	  deallocation of private data structures. The use of
	  _a_u_t_h is undefined after calling [1mauth_destroy()[0m.

     [1mAUTH *
     authnone_create()

	  [0mCreate and returns an RPC authentication handle that
	  passes nonusable authentication information with each
	  remote procedure call. This is the default authentica-
	  tion used by RPC.

     [1mAUTH *
     authdes_create(name, window, syncaddr, ckey)
     char *name;
     unsigned window;
     struct sockaddr *addr;
     des_block *ckey;

	  authdes_create() [0mis the first of two routines which
	  interface to the RPC secure authentication system,
	  known as DES authentication.	The second is
	  [1mauthdes_getucred()[0m, below. Note: the keyserver daemon
	  [1mkeyserv[0m(8) must be running for the DES authentication
	  system to work.

	  [1mauthdes_create()[0m, used on the client side, returns an
	  authentication handle that will enable the use of the
	  secure authentication system.  The first parameter _n_a_m_e
	  is the network name, or _n_e_t_n_a_m_e, of the owner of the
	  server process. This field usually represents a _h_o_s_t_-
	  _n_a_m_e derived from the utility routine [1mhost2netname[0m, but
	  could also represent a user name using [1muser2netname[0m.
	  The second field is window on the validity of the



Printed 20/11/92    Revision 1.5 of 13/08/90			1






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  client credential, given in seconds.	A small window is
	  more secure than a large one, but choosing too small of
	  a window will increase the frequency of resynchroniza-
	  tions because of clock drift. The third parameter _s_y_n_-
	  _c_a_d_d_r is optional.  If it is NULL, then the authentica-
	  tion system will assume that the local clock is always
	  in sync with the server's clock, and will not attempt
	  resynchronizations. If an address is supplied, however,
	  then the system will use the address for consulting the
	  remote time service whenever resynchronization is
	  required. This parameter is usually the address of the
	  RPC server itself. The final parameter _c_k_e_y is also
	  optional.  If it is NULL, then the authentication sys-
	  tem will generate a random DES key to be used for the
	  encryption of credentials.  If it is supplied, however,
	  then it will be used instead.

     [1mauthdes_getucred(adc, uid, gid, grouplen, groups)
     struct authdes_cred *adc;
     short *uid;
     short *gid;
     short *grouplen;
     int *groups;

	  authdes_getucred()[0m, the second of the two DES authenti-
	  cation routines, is used on the server side for con-
	  verting a DES credential, which is operating system
	  independent, into a credential. This routine differs
	  from utility routine [1mnetname2user [0min that
	  [1mauthdes_getucred() [0mpulls its information from a cache,
	  and does not have to do a Network Information Service
	  lookup everytime it is called to get its information.

     [1mAUTH *
     authunix_create(host, uid, gid, len, aup_gids)
     char *host;
     int uid, gid, len, *aup.gids;

	  [0mCreate and return an RPC authentication handle that
	  contains authentication information.	The parameter
	  _h_o_s_t is the name of the machine on which the informa-
	  tion was created; _u_i_d is the user's user ID ; _g_i_d is
	  the user's current group ID ; _l_e_n and _a_u_p__g_i_d_s refer to
	  a counted array of groups to which the user belongs.
	  It is easy to impersonate a user.

     [1mAUTH *
     authunix_create_default()

	  [0mCalls [1mauthunix_create() [0mwith the appropriate parame-
	  ters.




Printed 20/11/92    Revision 1.5 of 13/08/90			2






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



     [1mcallrpc(host, prognum, versnum, procnum, inproc, in, outproc, out)
     char *host;
     u_long prognum, versnum, procnum;
     char *in, *out;
     xdrproc_t inproc, outproc;

	  [0mCall the remote procedure associated with _p_r_o_g_n_u_m,
	  _v_e_r_s_n_u_m, and _p_r_o_c_n_u_m on the machine, _h_o_s_t.  The parame-
	  ter _i_n is the address of the procedure's argument(s),
	  and _o_u_t is the address of where to place the result(s);
	  _i_n_p_r_o_c is used to encode the procedure's parameters,
	  and _o_u_t_p_r_o_c is used to decode the procedure's results.
	  This routine returns zero if it succeeds, or the value
	  of [1menum clnt_stat [0mcast to an integer if it fails.  The
	  routine [1mclnt_perrno() [0mis handy for translating failure
	  statuses into messages.

	  Warning: calling remote procedures with this routine
	  uses UDP/IP as a transport; see [1mclntudp_create() [0mfor
	  restrictions.  You do not have control of timeouts or
	  authentication using this routine.

     [1menum clnt_stat
     clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresult)
     u_long prognum, versnum, procnum;
     char *in, *out;
     xdrproc_t inproc, outproc;
     resultproc_t eachresult;

	  [0mLike [1mcallrpc()[0m, except the call message is broadcast to
	  all locally connected broadcast nets. Each time it
	  receives a response, this routine calls [1meachresult()[0m,
	  whose form is:


	       [1meachresult(out, addr)
	       char *out;
	       struct sockaddr_in *addr;

	  [0mwhere _o_u_t is the same as _o_u_t passed to
	  [1mclnt_broadcast()[0m, except that the remote procedure's
	  output is decoded there; _a_d_d_r points to the address of
	  the machine that sent the results.  If [1meachresult()
	  [0mreturns zero, [1mclnt_broadcast() [0mwaits for more replies;
	  otherwise it returns with appropriate status.

	  Warning: broadcast sockets are limited in size to the
	  maximum transfer unit of the data link. For ethernet,
	  this value is 1500 bytes.

     [1menum clnt_stat
     clnt_call(clnt, procnum, inproc, in, outproc, out, tout)



[0mPrinted 20/11/92    Revision 1.5 of 13/08/90			3






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



     [1mCLIENT *clnt;
     u_long
     procnum;
     xdrproc_t inproc, outproc;
     char *in, *out;
     struct timeval tout;

	  [0mA macro that calls the remote procedure _p_r_o_c_n_u_m associ-
	  ated with the client handle, _c_l_n_t, which is obtained
	  with an RPC client creation routine such as
	  [1mclnt_create()[0m.  The parameter _i_n is the address of the
	  procedure's argument(s), and _o_u_t is the address of
	  where to place the result(s); _i_n_p_r_o_c is used to encode
	  the procedure's parameters, and _o_u_t_p_r_o_c is used to
	  decode the procedure's results; _t_o_u_t is the time
	  allowed for results to come back.

     [1mclnt_destroy(clnt)
     CLIENT *clnt;

	  [0mA macro that destroys the client's RPC handle. Destruc-
	  tion usually involves deallocation of private data
	  structures, including _c_l_n_t itself.  Use of _c_l_n_t is
	  undefined after calling [1mclnt_destroy()[0m.  If the RPC
	  library opened the associated socket, it will close it
	  also.  Otherwise, the socket remains open.

     [1mCLIENT *
     clnt_create(host, prog, vers, proto)
     char *host;
     u_long prog, vers;
     char *proto;

	  [0mGeneric client creation routine.  _h_o_s_t identifies the
	  name of the remote host where the server is located.
	  _p_r_o_t_o 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 [1mclnt_control()[0m.

	  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 pro-
	  cedures that take large arguments or return huge
	  results.

     [1mbool_t
     clnt_control(cl, req, info)
     CLIENT *cl;
     char *info;

	  [0mA macro used to change or retrieve various information



Printed 20/11/92    Revision 1.5 of 13/08/90			4






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  about a client object.  _r_e_q indicates the type of
	  operation, and _i_n_f_o is a pointer to the information.
	  For both UDP and TCP, the supported values of _r_e_q and
	  their argument types and what they do are:


	  CLSET_TIMEOUT       struct timeval	  set total timeout
	  CLGET_TIMEOUT       struct timeval	  get total timeout

	  Note: if you set the timeout using [1mclnt_control()[0m, the
	  timeout parameter passed to [1mclnt_call() [0mwill 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 timevalset the retry timeout
	  CLGET_RETRY_TIMEOUT struct timevalget the retry timeout

	  The retry timeout is the time that UDP RPC waits for
	  the server to reply before retransmitting the request.

     [1mclnt_freeres(clnt, outproc, out)
     CLIENT *clnt;
     xdrproc_t outproc;
     char *out;

	  [0mA macro that frees any data allocated by the RPC/XDR
	  system when it decoded the results of an RPC call.  The
	  parameter _o_u_t is the address of the results, and
	  _o_u_t_p_r_o_c is the XDR routine describing the results.
	  This routine returns one if the results were success-
	  fully freed, and zero otherwise.

     [1mvoid
     clnt_geterr(clnt, errp)
     CLIENT *clnt;
     struct rpc_err *errp;

	  [0mA macro that copies the error structure out of the
	  client handle to the structure at address _e_r_r_p.

     [1mvoid
     clnt_pcreateerror(s)
     char *s;

	  [0mPrint 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



Printed 20/11/92    Revision 1.5 of 13/08/90			5






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  [1mclnt_create()[0m, [1mclntraw_create()[0m, [1mclnttcp_create()[0m, or
	  [1mclntudp_create() [0mcall fails.

     [1mvoid
     clnt_perrno(stat)
     enum clnt_stat stat;

	  [0mPrint a message to standard error corresponding to the
	  condition indicated by _s_t_a_t.	Used after [1mcallrpc()[0m.

     [1mclnt_perror(clnt, s)
     CLIENT *clnt;
     char *s;

	  [0mPrint a message to standard error indicating why an RPC
	  call failed; _c_l_n_t is the handle used to do the call.
	  The message is prepended with string _s and a colon.
	  Used after [1mclnt_call()[0m.

     [1mchar *
     clnt_spcreateerror
     char *s;

	  [0mLike [1mclnt_pcreateerror()[0m, except that it returns a
	  string instead of printing to the standard error.

	  Bugs: returns pointer to static data that is overwrit-
	  ten on each call.

     [1mchar *
     clnt_sperrno(stat)
     enum clnt_stat stat;

	  [0mTake the same arguments as [1mclnt_perrno()[0m, but instead
	  of sending a message to the standard error indicating
	  why an RPC call failed, return a pointer to a string
	  which contains the message.  The string ends with a
	  NEWLINE.

	  [1mclnt_sperrno() [0mis used instead of [1mclnt_perrno() [0mif 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
	  [1mprintf[0m, or if a message format different than that sup-
	  ported by [1mclnt_perrno() [0mis to be used.  Note: unlike
	  [1mclnt_sperror() [0mand [1mclnt_spcreaterror()[0m, [1mclnt_sperrno()
	  [0mdoes not return pointer to static data so the result
	  will not get overwritten on each call.

     [1mchar *
     clnt_sperror(rpch, s)
     CLIENT *rpch;



[0mPrinted 20/11/92    Revision 1.5 of 13/08/90			6






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



     [1mchar *s;

	  [0mLike [1mclnt_perror()[0m, except that (like [1mclnt_sperrno()[0m)
	  it returns a string instead of printing to standard
	  error.

	  Bugs: returns pointer to static data that is overwrit-
	  ten on each call.

     [1mCLIENT *
     clntraw_create(prognum, versnum)
     u_long prognum, versnum;

	  [0mThis routine creates a toy RPC client for the remote
	  program _p_r_o_g_n_u_m, version _v_e_r_s_n_u_m.  The transport used
	  to pass messages to the service is actually a buffer
	  within the process's address space, so the correspond-
	  ing RPC server should live in the same address space;
	  see [1msvcraw_create()[0m.	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.

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

	  [0mThis routine creates an RPC client for the remote pro-
	  gram _p_r_o_g_n_u_m, version _v_e_r_s_n_u_m; the client uses TCP/IP
	  as a transport. The remote program is located at Inter-
	  net address *_a_d_d_r.  If [1maddr->sin_port [0mis zero, then it
	  is set to the actual port that the remote program is
	  listening on (the remote [1mportmap [0mservice is consulted
	  for this information). The parameter _s_o_c_k_p is a socket;
	  if it is [1mRPC_ANYSOCK[0m, then this routine opens a new one
	  and sets _s_o_c_k_p.  Since TCP-based RPC uses buffered I/O
	  , the user may specify the size of the send and receive
	  buffers with the parameters _s_e_n_d_s_z and _r_e_c_v_s_z; values
	  of zero choose suitable defaults.  This routine returns
	  NULL if it fails.

     [1mCLIENT *
     clntudp_create(addr, pronum, versnum, wait, sockp)
     struct sockaddr_in *addr;
     u_long prognum, versnum;
     struct timeval wait;
     int *sockp;

	  [0mThis routine creates an RPC client for the remote



Printed 20/11/92    Revision 1.5 of 13/08/90			7






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  program _p_r_o_g_n_u_m, version _v_e_r_s_n_u_m; the client uses use
	  UDP/IP as a transport. The remote program is located at
	  Internet address _a_d_d_r.  If [1maddr->sin_port [0mis zero, then
	  it is set to actual port that the remote program is
	  listening on (the remote [1mportmap [0mservice is consulted
	  for this information). The parameter _s_o_c_k_p is a socket;
	  if it is [1mRPC_ANYSOCK[0m, then this routine opens a new one
	  and sets _s_o_c_k_p.  The UDP transport resends the call
	  message in intervals of [1mwait [0mtime until a response is
	  received or until the call times out.  The total time
	  for the call to time out is specified by [1mclnt_call()[0m.

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

     [1mhost2netname(name, host, domain)
     char *name;
     char *host;
     char *domain;

	  [0mConvert from a domain-specific hostname to an
	  operating-system independent netname. Return TRUE if it
	  succeeds and FALSE if it fails. Inverse of
	  [1mnetname2host()[0m.

     [1mkey_decryptsession(remotename, deskey)
     char *remotename;
     des_block *deskey;

	  key_decryptsession() [0mis an interface to the keyserver
	  daemon, which is associated with RPC's secure authenti-
	  cation system (DES authentication).  User programs
	  rarely need to call it, or its associated routines
	  [1mkey_encryptsession()[0m, [1mkey_gendes() [0mand [1mkey_setsecret()[0m.
	  System commands such as [1mlogin [0mand the RPC library are
	  the main clients of these four routines.

	  [1mkey_decryptsession() [0mtakes a server netname and a des
	  key, and decrypts the key by using the the public key
	  of the the server and the secret key associated with
	  the effective uid of the calling process.  It is the
	  inverse of [1mkey_encryptsession()[0m.

     [1mkey_encryptsession(remotename, deskey)
     char *remotename;
     des_block *deskey;

	  key_encryptsession() [0mis a keyserver interface routine.
	  It takes a server netname and a des key, and encrypts
	  it using the public key of the the server and the



Printed 20/11/92    Revision 1.5 of 13/08/90			8






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  secret key associated with the effective uid of the
	  calling process.  It is the inverse of
	  [1mkey_decryptsession()[0m.

     [1mkey_gendes(deskey)
     des_block *deskey;

	  key_gendes() [0mis a keyserver interface routine. It is
	  used to ask the keyserver for a secure conversation
	  key.	Choosing one at random is usually not good
	  enough, because the common ways of choosing random
	  numbers, such as using the current time, are very easy
	  to guess.

     [1mkey_setsecret(key)
     char *key;

	  key_setsecret() [0mis a keyserver interface routine. It is
	  used to set the key for the effective _u_i_d of the cal-
	  ling process.

     [1mvoid
     get_myaddress(addr)
     struct sockaddr_in *addr;

	  [0mStuff the machine's IP address into *_a_d_d_r, without con-
	  sulting the library routines that deal with [1m/etc/hosts[0m.
	  The port number is always set to [1mhtons(PMAPPORT)[0m.

     [1mgetnetname(name)
     char name[MAXNETNAMELEN];

	  getnetname() [0minstalls the unique, operating-system
	  independent netname of the caller in the fixed-length
	  array _n_a_m_e.  Returns TRUE if it succeeds and FALSE if
	  it fails.

     [1mnetname2host(name, host, hostlen)
     char *name;
     char *host;
     int hostlen;

	  [0mConvert from an operating-system independent netname to
	  a domain-specific hostname. Returns TRUE if it succeeds
	  and FALSE if it fails.  Inverse of [1mhost2netname()[0m.

     [1mnetname2user(name, uidp, gidp, gidlenp, gidlist)
     char *name;
     int *uidp;
     int *gidp;
     int *gidlenp;
     int *gidlist;



[0mPrinted 20/11/92    Revision 1.5 of 13/08/90			9






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  Convert from an operating-system independent netname to
	  a domain-specific user ID. Returns TRUE if it succeeds
	  and FALSE if it fails. Inverse of [1muser2netname()[0m.

     [1mstruct pmaplist *
     pmap_getmaps(addr)
     struct sockaddr_in *addr;

	  [0mA user interface to the [1mportmap [0mservice, which returns
	  a list of the current RPC program-to-port mappings on
	  the host located at IP address *_a_d_d_r.  This routine can
	  return NULL . The command `[1mrpcinfo -p[0m' uses this rou-
	  tine.

     [1mu_short
     pmap_getport(addr, prognum, versnum, protocol)
     struct sockaddr_in *addr;
     u_long prognum, versnum, protocol;

	  [0mA user interface to the [1mportmap [0mservice, which returns
	  the port number on which waits a service that supports
	  program number _p_r_o_g_n_u_m, version _v_e_r_s_n_u_m, and speaks the
	  transport protocol associated with _p_r_o_t_o_c_o_l.	The value
	  of _p_r_o_t_o_c_o_l is most likely or [1mIPPROTO_TCP[0m.  A return
	  value of zero means that the mapping does not exist or
	  that the RPC system failured to contact the remote
	  [1mportmap [0mservice.  In the latter case, the global vari-
	  able [1mrpc_createerr() [0mcontains the RPC status.

     [1menum clnt_stat
     pmap_rmtcall(addr, prognum, versnum, procnum, inproc, in, outproc, out, tout, portp)
     struct sockaddr_in *addr;
     u_long prognum, versnum, procnum;
     char *in, *out;
     xdrproc_t inproc, outproc;
     struct timeval tout;
     u_long *portp;

	  [0mA user interface to the [1mportmap [0mservice, which
	  instructs [1mportmap [0mon the host at IP address *_a_d_d_r to
	  make an RPC call on your behalf to a procedure on that
	  host.  The parameter *_p_o_r_t_p will be modified to the
	  program's port number if the procedure succeeds. The
	  definitions of other parameters are discussed in
	  [1mcallrpc() [0mand [1mclnt_call()[0m.  This procedure should be
	  used for a ping and nothing else.  See also
	  [1mclnt_broadcast()[0m.

     [1mpmap_set(prognum, versnum, protocol, port)
     u_long prognum, versnum, protocol;
     u_short port;




[0mPrinted 20/11/92    Revision 1.5 of 13/08/90		       10






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  A user interface to the [1mportmap [0mservice, which estab-
	  lishes a mapping between the triple
	  [_p_r_o_g_n_u_m,_v_e_r_s_n_u_m,_p_r_o_t_o_c_o_l] and _p_o_r_t on the machine's
	  [1mportmap [0mservice. The value of _p_r_o_t_o_c_o_l is most likely
	  or [1mIPPROTO_TCP[0m.  This routine returns one if it
	  succeeds, zero otherwise.  Automatically done by
	  [1msvc_register()[0m.

     [1mpmap_unset(prognum, versnum)
     u_long prognum, versnum;

	  [0mA user interface to the [1mportmap [0mservice, which destroys
	  all mapping between the triple [_p_r_o_g_n_u_m,_v_e_r_s_n_u_m,*] and
	  [1mports [0mon the machine's [1mportmap [0mservice. This routine
	  returns one if it succeeds, zero otherwise.

     [1mregisterrpc(prognum, versnum, procnum, procname, inproc, outproc)
     u_long prognum, versnum, procnum;
     char *(*procname) () ;
     xdrproc_t inproc, outproc;

	  [0mRegister procedure _p_r_o_c_n_a_m_e with the RPC service pack-
	  age.	If a request arrives for program _p_r_o_g_n_u_m, version
	  _v_e_r_s_n_u_m, and procedure _p_r_o_c_n_u_m, _p_r_o_c_n_a_m_e is called with
	  a pointer to its parameter(s); _p_r_o_g_n_a_m_e should return a
	  pointer to its static result(s); _i_n_p_r_o_c is used to
	  decode the parameters while _o_u_t_p_r_o_c is used to encode
	  the results.	This routine returns zero if the regis-
	  tration succeeded, -1 otherwise.

	  Warning: remote procedures registered in this form are
	  accessed using the UDP/IP transport; see
	  [1msvcudp_create() [0mfor restrictions.

     [1mstruct rpc_createerr     rpc_createerr;

	  [0mA global variable whose value is set by any RPC client
	  creation routine that does not succeed.  Use the rou-
	  tine [1mclnt_pcreateerror() [0mto print the reason why.

     [1msvc_destroy(xprt)
     SVCXPRT *
     xprt;

	  [0mA macro that destroys the RPC service transport handle,
	  _x_p_r_t.  Destruction usually involves deallocation of
	  private data structures, including _x_p_r_t itself.  Use of
	  _x_p_r_t is undefined after calling this routine.

     [1mfd_set svc_fdset;

	  [0mA global variable reflecting the RPC service side's



Printed 20/11/92    Revision 1.5 of 13/08/90		       11






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  read file descriptor bit mask; it is suitable as a
	  parameter to the [1mselect [0msystem call. This is only of
	  interest if a service implementor does not call
	  [1msvc_run()[0m, but rather does his own asynchronous event
	  processing.  This variable is read-only (do not pass
	  its address to [1mselect[0m!), yet it may change after calls
	  to [1msvc_getreqset() [0mor any creation routines.

     [1mint svc_fds;

	  [0mSimilar to [1msvc_fedset()[0m, but limited to 32 descriptors.
	  This interface is obsoleted by [1msvc_fdset()[0m.

     [1msvc_freeargs(xprt, inproc, in)
     SVCXPRT *xprt;
     xdrproc_t inproc;
     char *in;

	  [0mA macro that frees any data allocated by the RPC/XDR
	  system when it decoded the arguments to a service pro-
	  cedure using [1msvc_getargs()[0m.  This routine returns 1 if
	  the results were successfully freed, and zero other-
	  wise.

     [1msvc_getargs(xprt, inproc, in)
     SVCXPRT *xprt;
     xdrproc_t inproc;
     char *in;

	  [0mA macro that decodes the arguments of an RPC request
	  associated with the RPC service transport handle, _x_p_r_t.
	  The parameter _i_n is the address where the arguments
	  will be placed; _i_n_p_r_o_c is the XDR routine used to
	  decode the arguments.  This routine returns one if
	  decoding succeeds, and zero otherwise.

     [1mstruct sockaddr_in *
     svc_getcaller(xprt)
     SVCXPRT *xprt;

	  [0mThe approved way of getting the network address of the
	  caller of a procedure associated with the RPC service
	  transport handle, _x_p_r_t.

     [1msvc_getreqset(rdfds)
     fd_set *rdfds;

	  [0mThis routine is only of interest if a service implemen-
	  tor does not call [1msvc_run()[0m, but instead implements
	  custom asynchronous event processing.  It is called
	  when the [1mselect [0msystem call has determined that an RPC
	  request has arrived on some RPC [1msocket(s) ; [0m_r_d_f_d_s is



Printed 20/11/92    Revision 1.5 of 13/08/90		       12






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  the resultant read file descriptor bit mask.	The rou-
	  tine returns when all sockets associated with the value
	  of _r_d_f_d_s have been serviced.

     [1msvc_getreq(rdfds)
     int rdfds;

	  [0mSimilar to [1msvc_getreqset()[0m, but limited to 32 descrip-
	  tors. This interface is obsoleted by [1msvc_getreqset()[0m.

     [1msvc_register(xprt, prognum, versnum, dispatch, protocol)
     SVCXPRT *xprt;
     u_long prognum, versnum;
     void (*dispatch) ();
     u_long protocol;

	  [0mAssociates _p_r_o_g_n_u_m and _v_e_r_s_n_u_m with the service
	  dispatch procedure, _d_i_s_p_a_t_c_h.  If _p_r_o_t_o_c_o_l is zero, the
	  service is not registered with the [1mportmap [0mservice.  If
	  _p_r_o_t_o_c_o_l is non-zero, then a mapping of the triple
	  [_p_r_o_g_n_u_m,_v_e_r_s_n_u_m,_p_r_o_t_o_c_o_l] to [1mxprt->xp_port [0mis esta-
	  blished with the local [1mportmap [0mservice (generally _p_r_o_-
	  _t_o_c_o_l is zero, or ).	The procedure _d_i_s_p_a_t_c_h has the
	  following form:
	       [1mdispatch(request, xprt)
	       struct svc_req *request;
	       SVCXPRT *xprt;

	  [0mThe [1msvc_register() [0mroutine returns one if it succeeds,
	  and zero otherwise.

     [1msvc_run()

	  [0mThis routine never returns. It waits for RPC requests
	  to arrive, and calls the appropriate service procedure
	  using [1msvc_getreq() [0mwhen one arrives. This procedure is
	  usually waiting for a [1mselect() [0msystem call to return.

     [1msvc_sendreply(xprt, outproc, out)
     SVCXPRT *xprt;
     xdrproc_t outproc;
     char *out;

	  [0mCalled by an RPC service's dispatch routine to send the
	  results of a remote procedure call.  The parameter _x_p_r_t
	  is the request's associated transport handle; _o_u_t_p_r_o_c
	  is the XDR routine which is used to encode the results;
	  and _o_u_t is the address of the results.  This routine
	  returns one if it succeeds, zero otherwise.

     [1mvoid
     svc_unregister(prognum, versnum)



[0mPrinted 20/11/92    Revision 1.5 of 13/08/90		       13






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



     [1mu_long prognum, versnum;

	  [0mRemove all mapping of the double [_p_r_o_g_n_u_m,_v_e_r_s_n_u_m] to
	  dispatch routines, and of the triple
	  [_p_r_o_g_n_u_m,_v_e_r_s_n_u_m,*] to port number.

     [1mvoid
     svcerr_auth(xprt, why)
     SVCXPRT *xprt;
     enum auth_stat why;

	  [0mCalled by a service dispatch routine that refuses to
	  perform a remote procedure call due to an authentica-
	  tion error.

     [1mvoid
     svcerr_decode(xprt)
     SVCXPRT *xprt;

	  [0mCalled by a service dispatch routine that cannot suc-
	  cessfully decode its parameters. See also
	  [1msvc_getargs()[0m.

     [1mvoid
     svcerr_noproc(xprt)
     SVCXPRT *xprt;

	  [0mCalled by a service dispatch routine that does not
	  implement the procedure number that the caller
	  requests.

     [1mvoid
     svcerr_noprog(xprt)
     SVCXPRT *xprt;

	  [0mCalled when the desired program is not registered with
	  the RPC package. Service implementors usually do not
	  need this routine.

     [1mvoid
     svcerr_progvers(xprt)
     SVCXPRT *xprt;

	  [0mCalled when the desired version of a program is not
	  registered with the RPC package. Service implementors
	  usually do not need this routine.

     [1mvoid
     svcerr_systemerr(xprt)
     SVCXPRT *xprt;

	  [0mCalled by a service dispatch routine when it detects a



Printed 20/11/92    Revision 1.5 of 13/08/90		       14






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  system error not covered by any particular protocol.
	  For example, if a service can no longer allocate
	  storage, it may call this routine.

     [1mvoid
     svcerr_weakauth(xprt)
     SVCXPRT *xprt;

	  [0mCalled by a service dispatch routine that refuses to
	  perform a remote procedure call due to insufficient
	  (but correct) authentication parameters.  The routine
	  calls [1msvcerr_auth(xprt, AUTH_TOOWEAK)[0m.

     [1mSVCXPRT *
     svcraw_create()

	  [0mThis routine creates a toy RPC service transport, to
	  which it returns a pointer.  The transport is really a
	  buffer within the process's address space, so the
	  corresponding RPC client should live in the same
	  address space; see [1mclntraw_create()[0m.	This routine
	  allows simulation of RPC and acquisition of RPC over-
	  heads (such as round trip times), without any kernel
	  interference.  This routine returns NULL if it fails.

     [1mSVCXPRT *
     svctcp_create(sock, send_buf_size, recv_buf_size)
     int sock;
     u_int send_buf_size, recv_buf_size;

	  [0mThis routine creates a TCP/IP-based RPC service tran-
	  sport, to which it returns a pointer.  The transport is
	  associated with the socket _s_o_c_k, which may be
	  [1mRPC_ANYSOCK[0m, in which case a new socket is created.  If
	  the socket is not bound to a local TCP port, then this
	  routine binds it to an arbitrary port. Upon completion,
	  [1mxprt->xp_sock [0mis the transport's socket descriptor, nd
	  [1mxprt->xp_port [0mis the transport's port number.  This
	  routine returns NULL if it fails. Since TCP-based RPC
	  uses buffered I/O , users may specify the size of
	  buffers; values of zero choose suitable defaults.

     [1mvoid
     svcfd_create(fd, sendsize, recvsize)
     int fd;
     u_int sendsize;
     u_int recvsize;

	  [0mCreate a service on top of any open desciptor. Typi-
	  cally, this descriptor is a connected socket for a
	  stream protocol such as TCP. _s_e_n_d_s_i_z_e and _r_e_c_v_s_i_z_e
	  indicate sizes for the send and receive buffers.  If



Printed 20/11/92    Revision 1.5 of 13/08/90		       15






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  they are zero, a reasonable default is chosen.

     [1mSVCXPRT *
     svcudp_create(sock)
     int sock;

	  [0mThis routine creates a UDP/IP-based RPC service tran-
	  sport, to which it returns a pointer.  The transport is
	  associated with the socket _s_o_c_k, which may be
	  [1mRPC_ANYSOCK , [0min which case a new socket is created.
	  If the socket is not bound to a local UDP port, then
	  this routine binds it to an arbitrary port. Upon com-
	  pletion, [1mxprt->xp_sock [0mis the transport's socket
	  descriptor, and [1mxprt->xp_port [0mis the transport's port
	  number.  This routine returns NULL if it fails.

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

     [1muser2netname(name, uid, domain)
     char *name;
     int uid;
     char *domain;

	  [0mConvert from a domain-specific username to an
	  operating-system independent netname. Returns TRUE if
	  it succeeds and FALSE if it fails. Inverse of
	  [1mnetname2user()[0m.

     [1mxdr_accepted_reply(xdrs, ar)
     XDR *xdrs;
     struct accepted_reply *ar;

	  [0mUsed for encoding RPC reply messages. This routine is
	  useful for users who wish to generate RPC-style mes-
	  sages without using the RPC package.

     [1mxdr_authunix_parms(xdrs, aupp)
     XDR *xdrs;
     struct authunix_parms *aupp;

	  [0mUsed for describing UNIX credentials. This routine is
	  useful for users who wish to generate these credentials
	  without using the RPC authentication package.

     [1mvoid
     xdr_callhdr(xdrs, chdr)
     XDR *xdrs;
     struct rpc_msg *chdr;




[0mPrinted 20/11/92    Revision 1.5 of 13/08/90		       16






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  Used for describing RPC call header messages.  This
	  routine is useful for users who wish to generate RPC-
	  style messages without using the RPC package.

     [1mxdr_callmsg(xdrs, cmsg)
     XDR *xdrs;
     struct rpc_msg *cmsg;

	  [0mUsed for describing RPC call messages.  This routine is
	  useful for users who wish to generate RPC-style mes-
	  sages without using the RPC package.

     [1mxdr_opaque_auth(xdrs, ap)
     XDR *xdrs;
     struct opaque_auth *ap;

	  [0mUsed for describing RPC authentication information mes-
	  sages.  This routine is useful for users who wish to
	  generate RPC-style messages without using the RPC pack-
	  age.

     [1mxdr_pmap(xdrs, regs)
     XDR *xdrs;
     struct pmap *regs;

	  [0mUsed for describing parameters to various [1mportmap [0mpro-
	  cedures, externally.	This routine is useful for users
	  who wish to generate these parameters without using the
	  [1mpmap [0minterface.

     [1mxdr_pmaplist(xdrs, rp)
     XDR *xdrs;
     struct pmaplist **rp;

	  [0mUsed for describing a list of port mappings, exter-
	  nally.  This routine is useful for users who wish to
	  generate these parameters without using the [1mpmap [0minter-
	  face.

     [1mxdr_rejected_reply(xdrs, rr)
     XDR *xdrs;
     struct rejected_reply *rr;

	  [0mUsed for describing RPC reply messages.  This routine
	  is useful for users who wish to generate RPC-style mes-
	  sages without using the RPC package.

     [1mxdr_replymsg(xdrs, rmsg)
     XDR *xdrs;
     struct rpc_msg *rmsg;

	  [0mUsed for describing RPC reply messages.  This routine



Printed 20/11/92    Revision 1.5 of 13/08/90		       17






RPC(3N)             UNIX Programmer's Manual		  RPC(3N)



	  is useful for users who wish to generate RPC style mes-
	  sages without using the RPC package.

     [1mvoid
     xprt_register(xprt)
     SVCXPRT *xprt;

	  [0mAfter RPC service transport handles are created, they
	  should register themselves with the RPC service pack-
	  age.	This routine modifies the global variable
	  [1msvc_fds()[0m.  Service implementors usually do not need
	  this routine.

     [1mvoid
     xprt_unregister(xprt)
     SVCXPRT *xprt;

	  [0mBefore an RPC service transport handle is destroyed, it
	  should unregister itself with the RPC service package.
	  This routine modifies the global variable [1msvc_fds()[0m.
	  Service implementors usually do not need this routine.

[1mSEE ALSO
     XDR[0m(3N), [1mkeyserv[0m(8)

     The following chapters in, _N_e_t_w_o_r_k _P_r_o_g_r_a_m_m_i_n_g _o_n _t_h_e _S_u_n
     _W_o_r_k_s_t_a_t_i_o_n:
	  _R_e_m_o_t_e _P_r_o_c_e_d_u_r_e _C_a_l_l_s: _P_r_o_t_o_c_o_l _S_p_e_c_i_f_i_c_a_t_i_o_n
	  _R_e_m_o_t_e _P_r_o_c_e_d_u_r_e _C_a_l_l _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e
	  _r_p_c_g_e_n _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e

























Printed 20/11/92    Revision 1.5 of 13/08/90		       18



[0m