home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3c / rpc.z / rpc
Encoding:
Text File  |  1998-10-20  |  41.9 KB  |  1,187 lines
  1.  
  2.  
  3.  
  4. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      rpc - Remote Procedure Call (RPC) library routines
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS AAAANNNNDDDD DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  12.      These routines allow C programs to make procedure calls on other machines
  13.      across the network.  First, the client calls a procedure to send a data
  14.      packet to the server.  Upon receipt of the packet, the server calls a
  15.      dispatch routine to perform the requested service, and then sends back a
  16.      reply.  Finally, the procedure call returns to the client.
  17.  
  18.           #include <rpc/rpc.h>
  19.  
  20.  
  21.           void
  22.           auth_destroy(AUTH *auth)
  23.  
  24.  
  25.           A macro that destroys the authentication information associated with
  26.           _a_u_t_h.  Destruction usually involves deallocation of private data
  27.           structures. The use of _a_u_t_h is undefined after calling
  28.           _a_u_t_h__d_e_s_t_r_o_y().
  29.  
  30.  
  31.           AUTH *
  32.           authnone_create(void)
  33.  
  34.  
  35.           Create and returns an RPC authentication handle that passes
  36.           nonusable authentication information with each remote procedure
  37.           call. This is the default authentication used by RPC.
  38.  
  39.  
  40.           AUTH *
  41.           authunix_create(const char *host, int uid,
  42.                int gid, int len, int *aup_gids)
  43.  
  44.  
  45.           Create and return an RPC authentication handle that contains UNIX
  46.           authentication information.  The parameter _h_o_s_t is the name of the
  47.           machine on which the information was created; _u_i_d is the user's user
  48.           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
  49.           counted array of groups to which the user belongs.  It is easy to
  50.           impersonate a user.
  51.  
  52.  
  53.           AUTH *
  54.           authunix_create_default(void)
  55.  
  56.  
  57.           Call _a_u_t_h_u_n_i_x__c_r_e_a_t_e() with the appropriate parameters.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  71.  
  72.  
  73.  
  74.           enum clnt_stat
  75.           callrpc(const char *host, u_long prognum,
  76.                u_long versnum, u_long procnum,
  77.                xdrproc_t inproc, void *in,
  78.                xdrproc_t outproc, void *out)
  79.  
  80.  
  81.           Call the remote procedure associated with _p_r_o_g_n_u_m, _v_e_r_s_n_u_m, and
  82.           _p_r_o_c_n_u_m on the machine, _h_o_s_t.  The parameter _i_n is the address of
  83.           the procedure's argument(s), and _o_u_t is the address of where to
  84.           place the result(s); _i_n_p_r_o_c is used to encode the procedure's
  85.           parameters, and _o_u_t_p_r_o_c is used to decode the procedure's results.
  86.           This routine returns 0 if it succeeds, or the value of _e_n_u_m
  87.           _c_l_n_t__s_t_a_t cast to an integer if it fails.  The routine _c_l_n_t__p_e_r_r_n_o()
  88.           is handy for translating failure statuses into messages.
  89.  
  90.           Warning: calling remote procedures with this routine uses UDP/IP as
  91.           a transport; see _c_l_n_t_u_d_p__c_r_e_a_t_e() for restrictions.  You do not have
  92.           control of timeouts or authentication using this routine.
  93.  
  94.  
  95.           enum clnt_stat
  96.           clnt_broadcast(u_long prognum,
  97.               u_long versnum, u_long procnum,
  98.               xdrproc_t inproc, void *in,
  99.               xdrproc_t outproc, void *out,
  100.               bool_t (*eachresult)(void *, struct sockaddr_in *))
  101.  
  102.  
  103.           Like _c_a_l_l_r_p_c(), except the call message is broadcast to all locally
  104.           connected broadcast nets. Each time it receives a response, this
  105.           routine calls _e_a_c_h_r_e_s_u_l_t(), whose form is:
  106.  
  107.                bool_t
  108.                eachresult(void *out, struct sockaddr_in *addr)
  109.  
  110.           where _o_u_t is the same as _o_u_t passed to _c_l_n_t__b_r_o_a_d_c_a_s_t(), except that
  111.           the remote procedure's output is decoded there; _a_d_d_r points to the
  112.           address of the machine that sent the results.  If _e_a_c_h_r_e_s_u_l_t()
  113.           returns 0, _c_l_n_t__b_r_o_a_d_c_a_s_t() waits for more replies; otherwise it
  114.           returns with appropriate status.  Initially, it waits 4 seconds for
  115.           a response before retrying.  The next wait interval is doubled until
  116.           it reaches a total wait time of 45 seconds.  See also
  117.           _c_l_n_t__s_e_t_b_r_o_a_d_c_a_s_t_b_a_c_k_o_f_f().
  118.  
  119.           Warning: broadcast sockets are limited in size to the maximum
  120.           transfer unit of the data link.  For ethernet, this value is 1500
  121.           bytes.  For FDDI, this value is 4532 bytes.
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  137.  
  138.  
  139.  
  140.           enum clnt_stat
  141.           clnt_broadcast_exp(u_long prognum,
  142.               u_long versnum, u_long procnum,
  143.               xdrproc_t inproc, void *in,
  144.               xdrproc_t outproc, void *out,
  145.               bool_t (*eachresult)(void *, struct sockaddr_in *),
  146.               int inittime, waittime)
  147.  
  148.  
  149.           Like _c_l_n_t__b_r_o_a_d_c_a_s_t(), except you can specify the initial and total
  150.           wait time.  See also _c_l_n_t__s_e_t_b_r_o_a_d_c_a_s_t_b_a_c_k_o_f_f().
  151.  
  152.  
  153.           enum clnt_stat
  154.           clnt_call(CLIENT *clnt, u_long procnum,
  155.                xdrproc_t inproc, void *in,
  156.                xdrproc_t outproc, void *out,
  157.                struct timeval tout)
  158.  
  159.  
  160.           A macro that calls the remote procedure _p_r_o_c_n_u_m associated with the
  161.           client handle, _c_l_n_t, which is obtained with an RPC client creation
  162.           routine such as _c_l_n_t_u_d_p__c_r_e_a_t_e().  The parameter _i_n is the address
  163.           of the procedure's argument(s), and _o_u_t is the address of where to
  164.           place the result(s); _i_n_p_r_o_c is used to encode the procedure's
  165.           parameters, and _o_u_t_p_r_o_c is used to decode the procedure's results;
  166.           _t_o_u_t is the time allowed for results to come back.
  167.  
  168.  
  169.           void
  170.           clnt_control(CLIENT *clnt, u_int request, void *info)
  171.  
  172.  
  173.           A macro used to change or retrieve various information about a
  174.           client object.  _r_e_q_u_e_s_t indicates the type of operation, and _i_n_f_o is
  175.           a pointer to the information. For both UDP and TCP, the supported
  176.           values of _r_e_q_u_e_s_t and their argument types and what they do are:
  177.           CLSET_TIMEOUT       struct timeval       set total timeout
  178.           CLGET_TIMEOUT       struct timeval       get total timeout
  179.           CLGET_SERVER_ADDR   struct sockaddr_in   get server's address
  180.           CLGET_FD            int                  get connection's file descriptor
  181.           CLSET_FD_CLOSE      (ignored)            let clnt_destroy close fd
  182.           CLSET_FD_NCLOSE     (ignored)            don't let clnt_destroy close fd
  183.  
  184.           Note: if you set the timeout using _c_l_n_t__c_o_n_t_r_o_l(), the timeout
  185.           parameter passed to _c_l_n_t__c_a_l_l() will be ignored in all future calls.
  186.  
  187.           The following operations are valid for UDP only:
  188.           CLSET_RETRY_TIMEOUT   struct timeval   set the retry timeout
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                                                         PPPPaaaaggggeeee 3333
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  202.  
  203.  
  204.  
  205.           CLGET_RETRY_TIMEOUT   struct timeval   get the retry timeout
  206.           The retry timeout is the time that UDP RPC waits for the server to
  207.           reply before retransmitting the request.
  208.  
  209.           The following operations are valid for TCP only:
  210.           CLSET_EINTR_RETURN   bool_t   set param to 1 to return on EINTR
  211.           CLGET_EINTR_RETURN   bool_t   get return on EINTR flag
  212.  
  213.  
  214.           CLIENT *
  215.           clnt_create(const char *host, u_long prog, u_long vers,
  216.                const char *proto)
  217.  
  218.  
  219.           Generic client creation routine.  _h_o_s_t identifies the name of the
  220.           remote host where the server is located.  _p_r_o_t_o indicates which kind
  221.           of transport protocol to use. The currently supported values for
  222.           this field are udp and tcp.  Default timeouts are set, but can be
  223.           modified using _c_l_n_t__c_o_n_t_r_o_l().
  224.  
  225.           Warning: Using UDP has its shortcomings.  Since UDP-based RPC
  226.           messages can only hold up to 8 kilobytes of encoded data, this
  227.           transport cannot be used for procedures that take large arguments or
  228.           return huge results.
  229.  
  230.  
  231.           CLIENT *
  232.           clnt_create_vers(const char *host, u_long prog,
  233.                u_long *vers_out, u_long vers_low,
  234.                u_long vers_high, const char *proto)
  235.  
  236.  
  237.           Generic client creation with version checking. The server must
  238.           support a version between _v_e_r_s__l_o_w and _v_e_r_s__h_i_g_h, inclusive.  An
  239.           error results if this can not be done.  The value of _v_e_r_s__o_u_t is set
  240.           to the highest server-supported value.
  241.  
  242.  
  243.           void
  244.           clnt_destroy(CLIENT *clnt)
  245.  
  246.  
  247.           A macro that destroys the client's RPC handle. Destruction usually
  248.           involves deallocation of private data structures, including _c_l_n_t
  249.           itself.  Use of _c_l_n_t is undefined after calling _c_l_n_t__d_e_s_t_r_o_y().  If
  250.           the RPC library opened the associated socket, it will close it also.
  251.           Otherwise, the socket remains open and it is the responsibility of
  252.           the caller to close the socket.  Use the CLGET_FD request to
  253.           _c_l_n_t__c_o_n_t_r_o_l() to obtain the descriptor or the CLSET_FD_CLOSE
  254.           request to have _c_l_n_t__d_e_s_t_r_o_y() close it.
  255.  
  256.  
  257.  
  258.  
  259.                                                                         PPPPaaaaggggeeee 4444
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  267.  
  268.  
  269.  
  270.           bool_t
  271.           clnt_freeres(CLIENT *clnt, xdrproc_t outproc, void *out)
  272.  
  273.  
  274.           A macro that frees any data allocated by the RPC/XDR system when it
  275.           decoded the results of an RPC call.  The parameter _o_u_t is the
  276.           address of the results, and _o_u_t_p_r_o_c is the XDR routine describing
  277.           the results.  This routine returns 1 if the results were
  278.           successfully freed, and 0 otherwise.
  279.  
  280.  
  281.           void
  282.           clnt_geterr(CLIENT *clnt, struct rpc_err *errp)
  283.  
  284.  
  285.           A macro that copies the error structure out of the client handle to
  286.           the structure at address _e_r_r_p.
  287.  
  288.  
  289.           void
  290.           clnt_pcreateerror(const char *s)
  291.  
  292.  
  293.           Print a message to standard error indicating why a client RPC handle
  294.           could not be created.  The message is prepended with string _s and a
  295.           colon.  Used when a _c_l_n_t__c_r_e_a_t_e(), _c_l_n_t_r_a_w__c_r_e_a_t_e(),
  296.           _c_l_n_t_t_c_p__c_r_e_a_t_e(), or _c_l_n_t_u_d_p__c_r_e_a_t_e() call fails.
  297.  
  298.  
  299.           void
  300.           clnt_perrno(enum clnt_stat stat)
  301.  
  302.  
  303.           Print a message to standard error corresponding to the condition
  304.           indicated by _s_t_a_t.  Used after _c_a_l_l_r_p_c().
  305.  
  306.  
  307.           void
  308.           clnt_perror(CLIENT *clnt, const char *s)
  309.  
  310.  
  311.           Print a message to standard error indicating why an RPC call failed;
  312.           _c_l_n_t is the handle used to do the call.  The message is prepended
  313.           with string _s and a colon.  Used after _c_l_n_t__c_a_l_l().
  314.  
  315.  
  316.           void
  317.           clnt_setbroadcastbackoff(void (*first)(struct timeval *tv),
  318.                int (*next)(struct timeval *tv))
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.                                                                         PPPPaaaaggggeeee 5555
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  333.  
  334.  
  335.  
  336.           Set the timeout backoff iterator for clnt_broadcast().  The initial
  337.           timeout is stored in *_t_v by _f_i_r_s_t().  Subsequent timeouts are
  338.           computed in *_t_v by _n_e_x_t() , which returns 1 until a backoff limit is
  339.           reached, and thereafter returns 0.
  340.  
  341.  
  342.           char *
  343.           clnt_spcreateerror(const char *s)
  344.  
  345.  
  346.           Like _c_l_n_t__p_c_r_e_a_t_e_e_r_r_o_r(), except that it returns a string instead of
  347.           printing to the standard error.
  348.  
  349.           Bugs: returns a pointer to static data that is overwritten on each
  350.           call.
  351.  
  352.  
  353.           char *
  354.           clnt_sperrno(enum clnt_stat stat)
  355.  
  356.  
  357.           Take the same arguments as _c_l_n_t__p_e_r_r_n_o(), but instead of sending a
  358.           message to the standard error indicating why an RPC call failed,
  359.           return a pointer to a string which contains the message.  The string
  360.           ends with a NEWLINE.
  361.  
  362.           _c_l_n_t__s_p_e_r_r_n_o() is used instead of _c_l_n_t__p_e_r_r_n_o() if the program does
  363.           not have a standard error (a server program quite likely does not),
  364.           or if the programmer does not want the message to be output with
  365.           _p_r_i_n_t_f, or if a message format different than that supported by
  366.           _c_l_n_t__p_e_r_r_n_o() is to be used.
  367.  
  368.           Note: unlike _c_l_n_t__s_p_e_r_r_o_r() and _c_l_n_t__s_p_c_r_e_a_t_e_r_r_o_r(), _c_l_n_t__s_p_e_r_r_n_o()
  369.           returns a pointer to static data, but the result will not get
  370.           overwritten on each call.
  371.  
  372.  
  373.           char *
  374.           clnt_sperror(CLIENT *clnt, const char *s)
  375.  
  376.  
  377.           Like _c_l_n_t__p_e_r_r_o_r(), except that (like _c_l_n_t__s_p_e_r_r_n_o()) it returns a
  378.           string instead of printing to standard error.
  379.  
  380.           Bugs: returns a pointer to static data that is overwritten on each
  381.           call.
  382.  
  383.  
  384.           void
  385.           clnt_syslog(CLIENT *clnt, const char *s)
  386.  
  387.  
  388.  
  389.  
  390.  
  391.                                                                         PPPPaaaaggggeeee 6666
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  399.  
  400.  
  401.  
  402.           Logs a LOG_ERR error to _s_y_s_l_o_g(3) indicating why an RPC call failed;
  403.           _c_l_n_t is the handle used to do the call.  The message is prepended
  404.           with string s and a colon.
  405.  
  406.  
  407.           CLIENT *
  408.           clntraw_create(u_long prognum, u_long versnum)
  409.  
  410.  
  411.           This routine creates a toy RPC client for the remote program
  412.           _p_r_o_g_n_u_m, version _v_e_r_s_n_u_m.  The transport used to pass messages to
  413.           the service is actually a buffer within the process's address space,
  414.           so the corresponding RPC server should live in the same address
  415.           space; see _s_v_c_r_a_w__c_r_e_a_t_e().  This allows simulation of RPC and
  416.           acquisition of RPC overheads, such as round trip times, without any
  417.           kernel interference. This routine returns NULL if it fails.
  418.  
  419.  
  420.           CLIENT *
  421.           clnttcp_create(struct sockaddr_in *addr,
  422.                u_long prognum, u_long versnum,
  423.                int *sockp, u_int sendsize, u_int recvsize)
  424.  
  425.  
  426.           This routine creates an RPC client for the remote program _p_r_o_g_n_u_m,
  427.           version _v_e_r_s_n_u_m; the client uses TCP/IP as a transport. The remote
  428.           program is located at Internet address *_a_d_d_r.  If _a_d_d_r->_s_i_n__p_o_r_t is
  429.           0, then it is set to the actual port that the remote program is
  430.           listening on (the remote _p_o_r_t_m_a_p service is consulted for this
  431.           information). The parameter _s_o_c_k_p is a socket; if it is RRRRPPPPCCCC____AAAANNNNYYYYSSSSOOOOCCCCKKKK,
  432.           then this routine opens a new one and sets _s_o_c_k_p.  Since TCP-based
  433.           RPC uses buffered I/O , the user may specify the size of the send
  434.           and receive buffers with the parameters _s_e_n_d_s_i_z_e and _r_e_c_v_s_i_z_e;
  435.           values of 0 choose suitable defaults.  This routine returns NULL if
  436.           it fails.
  437.  
  438.  
  439.           CLIENT *
  440.           clntudp_create(struct sockaddr_in *addr,
  441.                u_long prognum, u_long versnum,
  442.                struct timeval wait, int *sockp)
  443.  
  444.  
  445.           This routine creates an RPC client for the remote program _p_r_o_g_n_u_m,
  446.           version _v_e_r_s_n_u_m; the client uses use UDP/IP as a transport. The
  447.           remote program is located at Internet address _a_d_d_r.  If -
  448.           _a_d_d_r->_s_i_n__p_o_r_t is 0, then it is set to actual port that the remote
  449.           program is listening on (the remote _p_o_r_t_m_a_p service is consulted for
  450.           this information). The parameter _s_o_c_k_p is a socket; if it is
  451.           RRRRPPPPCCCC____AAAANNNNYYYYSSSSOOOOCCCCKKKK, then this routine opens a new one and sets _s_o_c_k_p.  The
  452.           UDP transport resends the call message in intervals of _w_a_i_t time
  453.           until a response is received or until the call times out.  The total
  454.  
  455.  
  456.  
  457.                                                                         PPPPaaaaggggeeee 7777
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  465.  
  466.  
  467.  
  468.           time for the call to time out is specified by _c_l_n_t__c_a_l_l().
  469.  
  470.           Warning: since UDP-based RPC messages can only hold up to 8
  471.           kilobytes of encoded data, this transport cannot be used for
  472.           procedures that take large arguments or return huge results.
  473.  
  474.  
  475.           CLIENT *
  476.           clntudp_bufcreate(struct sockaddr_in *addr,
  477.                u_long prognum, u_long versnum,
  478.                struct timeval wait, int *sockp,
  479.                u_int sendsize, u_int recvsize)
  480.  
  481.  
  482.           Like _c_l_n_t_u_d_p__c_r_e_a_t_e(), except this call allows the user to specify
  483.           the maximum packet size for sending and receiving UDP-based RPC
  484.           messages.
  485.  
  486.  
  487.           void
  488.           get_myaddress(struct sockaddr_in *addr)
  489.  
  490.  
  491.           Stuff the machine's IP address into *_a_d_d_r, without consulting the
  492.           library routines that deal with /_e_t_c/_h_o_s_t_s.  The port number is
  493.           always set to _h_t_o_n_s(PPPPMMMMAAAAPPPPPPPPOOOORRRRTTTT).
  494.  
  495.  
  496.           struct pmaplist *
  497.           pmap_getmaps(addr)
  498.                struct sockaddr_in *addr;
  499.  
  500.  
  501.           A user interface to the _p_o_r_t_m_a_p service, which returns a list of the
  502.           current RPC program-to-port mappings on the host located at IP
  503.           address *_a_d_d_r.  This routine can return NULL.  The command `rrrrppppcccciiiinnnnffffoooo
  504.           ----pppp' uses this routine.
  505.  
  506.  
  507.           u_short
  508.           pmap_getport(struct sockaddr_in *addr, u_long prognum,
  509.                u_long versnum, u_int protocol)
  510.  
  511.  
  512.           A user interface to the _p_o_r_t_m_a_p service, which returns the port
  513.           number on which waits a service that supports program number
  514.           _p_r_o_g_n_u_m, version _v_e_r_s_n_u_m, and speaks the transport protocol
  515.           associated with _p_r_o_t_o_c_o_l.  The value of _p_r_o_t_o_c_o_l is most likely
  516.           IIIIPPPPPPPPRRRROOOOTTTTOOOO____UUUUDDDDPPPP or IIIIPPPPPPPPRRRROOOOTTTTOOOO____TTTTCCCCPPPP.  A return value of 0 means that the
  517.           mapping does not exist or that the RPC system failured to contact
  518.           the remote _p_o_r_t_m_a_p service.  In the latter case, the global variable
  519.           _r_p_c__c_r_e_a_t_e_e_r_r() contains the RPC status.
  520.  
  521.  
  522.  
  523.                                                                         PPPPaaaaggggeeee 8888
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  531.  
  532.  
  533.  
  534.           enum clnt_stat
  535.           pmap_rmtcall(struct sockaddr_in *addr,
  536.                u_long prognum, u_long versnum, u_long procnum,
  537.                xdrproc_t inproc, void *in,
  538.                xdrproc_t outproc, void *out,
  539.                struct timeval tout, u_long *portp)
  540.  
  541.  
  542.           A user interface to the _p_o_r_t_m_a_p service, which instructs _p_o_r_t_m_a_p on
  543.           the host at IP address *_a_d_d_r to make an RPC call on your behalf to a
  544.           procedure on that host.  The parameter *_p_o_r_t_p will be modified to
  545.           the program's port number if the procedure succeeds. The definitions
  546.           of other parameters are discussed in _c_a_l_l_r_p_c() and _c_l_n_t__c_a_l_l().
  547.           This procedure should be used for a ping and nothing else.  See also
  548.           _c_l_n_t__b_r_o_a_d_c_a_s_t().  _p_m_a_p__s_e_t_t_i_m_e_o_u_t_s(), and _p_m_a_p__s_e_t_r_m_t_c_a_l_l_t_i_m_e_o_u_t().
  549.  
  550.  
  551.           bool_t
  552.           pmap_set(u_long prognum, u_long versnum,
  553.                u_long protocol, u_short port)
  554.  
  555.  
  556.           A user interface to the _p_o_r_t_m_a_p service, which establishes a mapping
  557.           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
  558.           machine's _p_o_r_t_m_a_p service. The value of _p_r_o_t_o_c_o_l is most likely
  559.           IIIIPPPPPPPPRRRROOOOTTTTOOOO____UUUUDDDDPPPP or IIIIPPPPPPPPRRRROOOOTTTTOOOO____TTTTCCCCPPPP.  This routine returns 1 if it succeeds,
  560.           0 otherwise.  Automatically done by _s_v_c__r_e_g_i_s_t_e_r().
  561.  
  562.  
  563.           void
  564.           pmap_setrmtcalltimeout(struct timeval intertry)
  565.  
  566.  
  567.           Set the retry timeout for _p_m_a_p__r_m_t_c_a_l_l().  Note that the total
  568.           timeout per call is an argument to _p_m_a_p__r_m_t_c_a_l_l().
  569.  
  570.  
  571.           void
  572.           pmap_settimeouts(struct timeval intertry,
  573.                struct timeval percall)
  574.  
  575.  
  576.           Set the retry and total timeouts for RPCs to the portmapper.  These
  577.           timeouts are used explicitly by _p_m_a_p__s_e_t() and _p_m_a_p__g_e_t_p_o_r_t(), and
  578.           implicitly by _c_l_n_t*__c_r_e_a_t_e().
  579.  
  580.  
  581.           bool_t
  582.           pmap_unset(u_long prognum, u_long versnum)
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.                                                                         PPPPaaaaggggeeee 9999
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  597.  
  598.  
  599.  
  600.           A user interface to the _p_o_r_t_m_a_p service, which destroys all mapping
  601.           between the triple [_p_r_o_g_n_u_m, _v_e_r_s_n_u_m, *] and _p_o_r_t_s on the machine's
  602.           _p_o_r_t_m_a_p service. This routine returns 1 if it succeeds, 0 otherwise.
  603.  
  604.  
  605.           int
  606.           registerrpc(u_long prognum,
  607.                u_long versnum, u_long procnum,
  608.                void *(*procname)(void *),
  609.                xdrproc_t inproc, xdrproc_t outproc)
  610.  
  611.  
  612.           Register procedure _p_r_o_c_n_a_m_e with the RPC service package.  If a
  613.           request arrives for program _p_r_o_g_n_u_m, version _v_e_r_s_n_u_m, and procedure
  614.           _p_r_o_c_n_u_m, _p_r_o_c_n_a_m_e is called with a pointer to its parameter(s);
  615.           _p_r_o_g_n_a_m_e should return a pointer to its static result(s); _i_n_p_r_o_c is
  616.           used to decode the parameters while _o_u_t_p_r_o_c is used to encode the
  617.           results.  This routine returns 0 if the registration succeeded, -1
  618.           otherwise.
  619.  
  620.           Warning: remote procedures registered in this form are accessed
  621.           using the UDP/IP transport; see _s_v_c_u_d_p__c_r_e_a_t_e() for restrictions.
  622.  
  623.  
  624.           struct rpc_createerr     rpc_createerr
  625.  
  626.  
  627.           A global variable whose value is set by any RPC client creation
  628.           routine that does not succeed.  Use the routine _c_l_n_t__p_c_r_e_a_t_e_e_r_r_o_r()
  629.           to print the reason why.
  630.  
  631.  
  632.           void
  633.           _rpc_errorhandler(int priority, const char *format, ...)
  634.  
  635.  
  636.           Called by the RPC library routines to print an error message to
  637.           _s_t_d_e_r_r or to _s_y_s_l_o_g(3), if _o_p_e_n_l_o_g(3) was called. _p_r_i_o_r_i_t_y values
  638.           are defined in <_s_y_s_l_o_g._h>.  _f_o_r_m_a_t is printf-like format string.
  639.           See comments in <_r_p_c/_e_r_r_o_r_h_a_n_d_l_e_r._h> for details on defining your
  640.           own version for more sophisticated error handling.
  641.  
  642.  
  643.           void
  644.           svc_destroy(SVCXPRT *xprt)
  645.  
  646.  
  647.           A macro that destroys the RPC service transport handle, _x_p_r_t.
  648.           Destruction usually involves deallocation of private data
  649.           structures, including _x_p_r_t itself.  Use of _x_p_r_t is undefined after
  650.           calling this routine.
  651.  
  652.  
  653.  
  654.  
  655.                                                                        PPPPaaaaggggeeee 11110000
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  663.  
  664.  
  665.  
  666.           fd_set svc_fdset;
  667.  
  668.  
  669.           A global variable reflecting the RPC service side's read file
  670.           descriptor bit mask; it is suitable as a parameter to the _s_e_l_e_c_t(2)
  671.           system call. This is only of interest if a service implementor does
  672.           not call _s_v_c__r_u_n(), in order to do asynchronous event processing,
  673.           for example.  This variable is read-only (do not pass its address to
  674.           _s_e_l_e_c_t!), yet it may change after calls to _s_v_c__g_e_t_r_e_q_s_e_t() or any
  675.           creation routines.
  676.  
  677.  
  678.           int svc_fds
  679.  
  680.  
  681.           Similar to _s_v_c__f_d_s_e_t, but limited to 32 descriptors. This interface
  682.           is obsoleted by _s_v_c__f_d_s_e_t.
  683.  
  684.  
  685.           bool_t
  686.           svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, void *in)
  687.  
  688.  
  689.           A macro that frees any data allocated by the RPC/XDR system when it
  690.           decoded the arguments to a service procedure using _s_v_c__g_e_t_a_r_g_s().
  691.           This routine returns 1 if the results were successfully freed, and 0
  692.           otherwise.
  693.  
  694.  
  695.           bool_t
  696.           svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, void *in)
  697.  
  698.  
  699.           A macro that decodes the arguments of an RPC request associated with
  700.           the RPC service transport handle, _x_p_r_t.  The parameter _i_n is the
  701.           address where the arguments will be placed; _i_n_p_r_o_c is the XDR
  702.           routine used to decode the arguments.  This routine returns 1 if
  703.           decoding succeeds, and 0 otherwise.  Only after this routine is
  704.           called can the server call _f_o_r_k(2) to create a child process to
  705.           handle the request.
  706.  
  707.  
  708.           struct sockaddr_in *
  709.           svc_getcaller(SVCXPRT *xprt)
  710.  
  711.  
  712.           The approved way of getting the network address of the caller of a
  713.           procedure associated with the RPC service transport handle, _x_p_r_t.
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.                                                                        PPPPaaaaggggeeee 11111111
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  729.  
  730.  
  731.  
  732.           void
  733.           svc_getreq(int rdfds)
  734.  
  735.  
  736.           This routine is provided for compatibility with old code.  Use
  737.           _s_v_c__g_e_t_r_e_q_s_e_t () when developing new code.
  738.  
  739.  
  740.           void
  741.           svc_getreqset(fd_set *rdfds)
  742.  
  743.  
  744.           This routine is only of interest if a service implementor does not
  745.           call _s_v_c__r_u_n(), but instead implements custom asynchronous event
  746.           processing.  It is called when the _s_e_l_e_c_t(2) system call has
  747.           determined that an RPC request has arrived on some RPC _s_o_c_k_e_t(_s);
  748.           _r_d_f_d_s is the resultant read file descriptor bit mask.  The routine
  749.           returns when all sockets associated with the value of _r_d_f_d_s have
  750.           been serviced.
  751.  
  752.  
  753.           bool_t
  754.           svc_register(SVCXPRT *xprt,
  755.               u_long prognum, u_long versnum,
  756.               void (*dispatch)(struct svc_req *,SVCXPRT *),
  757.               int protocol)
  758.  
  759.  
  760.           Associates _p_r_o_g_n_u_m and _v_e_r_s_n_u_m with the service dispatch procedure,
  761.           _d_i_s_p_a_t_c_h.  If _p_r_o_t_o_c_o_l is 0, the service is not registered with the
  762.           _p_o_r_t_m_a_p service.  If _p_r_o_t_o_c_o_l is non-zero, then a mapping of the
  763.           triple [_p_r_o_g_n_u_m, _v_e_r_s_n_u_m, _p_r_o_t_o_c_o_l] to _x_p_r_t->_x_p__p_o_r_t is established
  764.           with the local _p_o_r_t_m_a_p service (generally _p_r_o_t_o_c_o_l is 0, IIIIPPPPPPPPRRRROOOOTTTTOOOO____UUUUDDDDPPPP
  765.           or IIIIPPPPPPPPRRRROOOOTTTTOOOO____TTTTCCCCPPPP ).  The procedure _d_i_s_p_a_t_c_h has the following form:
  766.  
  767.                void
  768.                dispatch(struct svc_req *request, SVCXPRT *xprt)
  769.  
  770.  
  771.           The _s_v_c__r_e_g_i_s_t_e_r() routine returns 1 if it succeeds, and 0
  772.           otherwise.
  773.  
  774.  
  775.           void
  776.           svc_run(void)
  777.  
  778.  
  779.           This routine never returns. It waits for RPC requests to arrive, and
  780.           calls the appropriate service procedure using _s_v_c__g_e_t_r_e_q() when one
  781.           arrives. This procedure is usually waiting for a _s_e_l_e_c_t() system
  782.           call to return.
  783.  
  784.  
  785.  
  786.  
  787.                                                                        PPPPaaaaggggeeee 11112222
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  795.  
  796.  
  797.  
  798.           bool_t
  799.           svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, void *out)
  800.  
  801.  
  802.           Called by an RPC service's dispatch routine to send the results of a
  803.           remote procedure call.  The parameter _x_p_r_t is the request's
  804.           associated transport handle; _o_u_t_p_r_o_c is the XDR routine which is
  805.           used to encode the results; and _o_u_t is the address of the results.
  806.           This routine returns 1 if it succeeds, 0 otherwise.
  807.  
  808.  
  809.           void
  810.           svc_unregister(u_long prognum, u_long versnum)
  811.  
  812.  
  813.           Remove all mapping of the double [_p_r_o_g_n_u_m, _v_e_r_s_n_u_m] to dispatch
  814.           routines, and of the triple [_p_r_o_g_n_u_m, _v_e_r_s_n_u_m, *] to port number.
  815.  
  816.  
  817.           void
  818.           svc_versquiet(SVCXPRT *xprt)
  819.  
  820.  
  821.           Tell the RPC library to not complain about version errors to the
  822.           client.  This is useful when revving broadcast protocols that sit on
  823.           a fixed address.
  824.  
  825.  
  826.           void
  827.           svcerr_auth(SVCXPRT *xprt, enum auth_stat why)
  828.  
  829.  
  830.           Called by a service dispatch routine that refuses to perform a
  831.           remote procedure call due to an authentication error.
  832.  
  833.  
  834.           void
  835.           svcerr_decode(SVCXPRT *xprt)
  836.  
  837.  
  838.           Called by a service dispatch routine that cannot successfully decode
  839.           its parameters. See also _s_v_c__g_e_t_a_r_g_s().
  840.  
  841.  
  842.           void
  843.           svcerr_noproc(SVCXPRT *xprt)
  844.  
  845.  
  846.           Called by a service dispatch routine that does not implement the
  847.           procedure number that the caller requests.
  848.  
  849.  
  850.  
  851.  
  852.  
  853.                                                                        PPPPaaaaggggeeee 11113333
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  861.  
  862.  
  863.  
  864.           void
  865.           svcerr_noprog(SVCXPRT *xprt)
  866.  
  867.  
  868.           Called when the desired program is not registered with the RPC
  869.           package. Service implementors usually do not need this routine.
  870.  
  871.  
  872.           void
  873.           svcerr_progvers(SVCXPRT *xprt,
  874.                u_long low_vers, u_long high_vers)
  875.  
  876.  
  877.           Called when the desired version of a program is not registered with
  878.           the RPC package. Service implementors usually do not need this
  879.           routine.
  880.  
  881.  
  882.           void
  883.           svcerr_systemerr(SVCXPRT *xprt)
  884.  
  885.  
  886.           Called by a service dispatch routine when it detects a system error
  887.           not covered by any particular protocol.  For example, if a service
  888.           can no longer allocate storage, it may call this routine.
  889.  
  890.  
  891.           void
  892.           svcerr_weakauth(SVCXPRT *xprt)
  893.  
  894.  
  895.           Called by a service dispatch routine that refuses to perform a
  896.           remote procedure call due to insufficient authentication parameters.
  897.           The routine calls _s_v_c_e_r_r__a_u_t_h(_x_p_r_t, _A_U_T_H__T_O_O_W_E_A_K).
  898.  
  899.  
  900.           SVCXPRT *
  901.           svcraw_create(void)
  902.  
  903.  
  904.           This routine creates a toy RPC service transport, to which it
  905.           returns a pointer.  The transport is really a buffer within the
  906.           process's address space, so the corresponding RPC client should live
  907.           in the same address space; see _c_l_n_t_r_a_w__c_r_e_a_t_e().  This routine
  908.           allows simulation of RPC and acquisition of RPC overheads (such as
  909.           round trip times), without any kernel interference.  This routine
  910.           returns NULL if it fails.
  911.  
  912.  
  913.           SVCXPRT *
  914.           svctcp_create(int sock, u_int sendsize, u_int recvsize)
  915.  
  916.  
  917.  
  918.  
  919.                                                                        PPPPaaaaggggeeee 11114444
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  927.  
  928.  
  929.  
  930.           This routine creates a TCP/IP-based RPC service transport, to which
  931.           it returns a pointer.  The transport is associated with the socket
  932.           _s_o_c_k, which may be RRRRPPPPCCCC____AAAANNNNYYYYSSSSOOOOCCCCKKKK, in which case a new socket is
  933.           created.  If the socket is not bound to a local TCP port, then this
  934.           routine binds it to an arbitrary port.  Upon completion, -
  935.           _x_p_r_t->_x_p__s_o_c_k is the transport's socket descriptor, and -
  936.           _x_p_r_t->_x_p__p_o_r_t is the transport's port number.  This routine returns
  937.           NULL if it fails. Since TCP-based RPC uses buffered I/O, users may
  938.           specify the size of the _s_e_n_d and _r_e_c_e_i_v_e buffers; values of 0 choose
  939.           suitable defaults.
  940.  
  941.  
  942.           SVCXPRT *
  943.           svcfd_create(int fd, u_int sendsize, u_int recvsize)
  944.  
  945.  
  946.           Create a service on top of any open descriptor. Typically, this
  947.           descriptor is a connected socket for a stream protocol such as TCP.
  948.           _s_e_n_d_s_i_z_e and _r_e_c_v_s_i_z_e indicate sizes for the send and receive
  949.           buffers.  If they are zero, a reasonable default is chosen.
  950.  
  951.  
  952.           SVCXPRT *
  953.           svcudp_bufcreate(int sock,
  954.                u_int sendsize, u_int recvsize)
  955.  
  956.  
  957.           This routine creates a UDP/IP-based RPC service transport, to which
  958.           it returns a pointer.  The transport is associated with the socket
  959.           _s_o_c_k, which may be RRRRPPPPCCCC____AAAANNNNYYYYSSSSOOOOCCCCKKKK, in which case a new socket is
  960.           created.  If the socket is not bound to a local UDP port, then this
  961.           routine binds it to an arbitrary port. Upon completion, -
  962.           _x_p_r_t->_x_p__s_o_c_k is the transport's socket descriptor, and -
  963.           _x_p_r_t->_x_p__p_o_r_t is the transport's port number.  This routine returns
  964.           NULL if it fails.
  965.  
  966.           This allows the user to specify the maximun packet size for sending
  967.           and receiving UDP-based RPC messages.
  968.  
  969.  
  970.           SVCXPRT *
  971.           svcudp_create(int sock)
  972.  
  973.  
  974.           This routine creates a UDP/IP-based RPC service transport, to which
  975.           it returns a pointer.  The transport is associated with the socket
  976.           _s_o_c_k, which may be RRRRPPPPCCCC____AAAANNNNYYYYSSSSOOOOCCCCKKKK, in which case a new socket is
  977.           created.  If the socket is not bound to a local UDP port, then this
  978.           routine binds it to an arbitrary port. Upon completion,
  979.           _x_p_r_t->_x_p__s_o_c_k is the transport's socket number, and _x_p_r_t->_x_p__p_o_r_t is
  980.           the transport's port number.  This routine returns NULL if it fails.
  981.  
  982.  
  983.  
  984.  
  985.                                                                        PPPPaaaaggggeeee 11115555
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  993.  
  994.  
  995.  
  996.           Warning: since UDP-based RPC messages can only hold up to 8
  997.           kilobytes of encoded data, this transport cannot be used for
  998.           procedures that take large arguments or return huge results.
  999.  
  1000.  
  1001.           bool_t
  1002.           xdr_accepted_reply(XDR *xdrs, struct accepted_reply *ar)
  1003.  
  1004.  
  1005.           Used for encoding RPC reply messages. This routine is useful for
  1006.           users who wish to generate RPC-style messages without using the RPC
  1007.           package.
  1008.  
  1009.  
  1010.           bool_t
  1011.           xdr_authunix_parms(XDR *xdrs,
  1012.                struct authunix_parms *aupp)
  1013.  
  1014.  
  1015.           Used for describing UNIX credentials. This routine is useful for
  1016.           users who wish to generate these credentials without using the RPC
  1017.           authentication package.
  1018.  
  1019.  
  1020.           bool_t
  1021.           xdr_callhdr(XDR *xdrs, struct rpc_msg *chdr)
  1022.  
  1023.  
  1024.           Used for describing RPC call header messages.  This routine is
  1025.           useful for users who wish to generate RPC-style messages without
  1026.           using the RPC package.
  1027.  
  1028.  
  1029.           bool_t
  1030.           xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsg)
  1031.  
  1032.  
  1033.           Used for describing RPC call messages.  This routine is useful for
  1034.           users who wish to generate RPC-style messages without using the RPC
  1035.           package.
  1036.  
  1037.  
  1038.           bool_t
  1039.           xdr_opaque_auth(XDR *xdrs, struct opaque_auth *ap)
  1040.  
  1041.  
  1042.           Used for describing RPC authentication information messages.  This
  1043.           routine is useful for users who wish to generate RPC-style messages
  1044.           without using the RPC package.
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.                                                                        PPPPaaaaggggeeee 11116666
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  1059.  
  1060.  
  1061.  
  1062.           bool_t
  1063.           xdr_pmap(XDR *xdrs, struct pmap *regs)
  1064.  
  1065.  
  1066.           Used for describing parameters to various _p_o_r_t_m_a_p procedures,
  1067.           externally.  This routine is useful for users who wish to generate
  1068.           these parameters without using the _p_m_a_p interface.
  1069.  
  1070.  
  1071.           bool_t
  1072.           xdr_pmaplist(XDR *xdrs, struct pmaplist **rp)
  1073.  
  1074.  
  1075.           Used for describing a list of port mappings, externally.  This
  1076.           routine is useful for users who wish to generate these parameters
  1077.           without using the _p_m_a_p interface.
  1078.  
  1079.  
  1080.           bool_t
  1081.           xdr_rejected_reply(XDR *xdrs, struct rejected_reply *rr)
  1082.  
  1083.  
  1084.           Used for describing RPC reply messages.  This routine is useful for
  1085.           users who wish to generate RPC-style messages without using the RPC
  1086.           package.
  1087.  
  1088.  
  1089.           bool_t
  1090.           xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsg)
  1091.  
  1092.  
  1093.           Used for describing RPC reply messages.  This routine is useful for
  1094.           users who wish to generate RPC style messages without using the RPC
  1095.           package.
  1096.  
  1097.  
  1098.           void
  1099.           xprt_register(SVCXPRT *xprt)
  1100.  
  1101.  
  1102.           After RPC service transport handles are created, they should
  1103.           register themselves with the RPC service package.  This routine
  1104.           modifies the global variable _s_v_c__f_d_s.  Service implementors usually
  1105.           do not need this routine.
  1106.  
  1107.  
  1108.           void
  1109.           xprt_unregister(SVCXPRT *xprt)
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.                                                                        PPPPaaaaggggeeee 11117777
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124. RRRRPPPPCCCC((((3333RRRR))))                                                                RRRRPPPPCCCC((((3333RRRR))))
  1125.  
  1126.  
  1127.  
  1128.           Before an RPC service transport handle is destroyed, it should
  1129.           unregister itself with the RPC service package.  This routine
  1130.           modifies the global variable _s_v_c__f_d_s.  Service implementors usually
  1131.           do not need this routine.
  1132.  
  1133. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  1134.      xdr(3R), _I_R_I_X _N_e_t_w_o_r_k _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e.
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.                                                                        PPPPaaaaggggeeee 11118888
  1184.  
  1185.  
  1186.  
  1187.