Print this page
8330 Add svc_tp_create_addr to libnsl
Reviewed by: Paul Dagnelie <pcd@delphix.com>
Reviewed by: Evan Layton <evan.layton@nexenta.com>
Reviewed by: Sebastien Roy <sebastien.roy@delphix.com>

@@ -3,11 +3,12 @@
 
 
 NAME
        rpc_svc_create, svc_control, svc_create, svc_destroy, svc_dg_create,
        svc_fd_create, svc_raw_create, svc_tli_create, svc_tp_create,
-       svc_vc_create, svc_door_create - server handle creation routines
+       svc_tp_create_addr, svc_vc_create, svc_door_create - server handle
+       creation routines
 
 SYNOPSIS
        #include <rpc/rpc.h>
 
        bool_t svc_control(SVCXPRT *svc, const uint_t req, void *info);

@@ -31,19 +32,26 @@
 
        SVCXPRT *svc_raw_create(void);
 
 
        SVCXPRT *svc_tli_create(const int fildes, const struct netconfig *netconf,
-            const struct t_bind *bind_addr, const uint_t sendsz,
+            const struct t_bind *bind_info, const uint_t sendsz,
             const uint_t recvsz);
 
 
        SVCXPRT *svc_tp_create(const void (*dispatch)
             (const struct svc_req *, const SVCXPRT *), const rpcprog_t prognum,
             const rpcvers_t versnum, const struct netconfig *netconf);
 
 
+       SVCXPRT *svc_tp_create_addr(const void (*dispatch)
+            (const struct svc_req *, const SVCXPRT *), const rpcprog_t prognum,
+            const rpcvers_t versnum, const struct netconfig *netconf,
+            const struct netbuf *bind_addr)
+       );
+
+
        SVCXPRT *svc_vc_create(const int fildes, const uint_t sendsz,
             const uint_t recvsz);
 
 
        SVCXPRT *svc_door_create(void (*dispatch)(struct svc_req *, SVCXPRT *),

@@ -59,194 +67,120 @@
 
    Routines
        See rpc(3NSL) for the definition of the SVCXPRT data structure.
 
        svc_control()
-                            A function to change or retrieve information about
-                            a service object. req indicates the type of
-                            operation and info is a pointer to the
-                            information.  The supported values of req,  their
-                            argument types, and what they do are:
+                      A function to change or retrieve information about a
+                      service object. req indicates the type of operation and
+                      info is a pointer to the information.  The supported
+                      values of req,  their argument types, and what they do
+                      are:
 
                             SVCGET_VERSQUIET
-                                                     If a request is received
-                                                     for a program number
-                                                     served by this server but
-                                                     the version number is
-                                                     outside the range
-                                                     registered with the
-                                                     server, an
-                                                     RPC_PROGVERSMISMATCH
-                                                     error will normally be
-                                                     returned.  info should be
-                                                     a pointer to an integer.
-                                                     Upon successful
-                                                     completion of the
-                                                     SVCGET_VERSQUIET request,
-                                                     *info contains an integer
-                                                     which describes the
-                                                     server's current
-                                                     behavior:  0 indicates
-                                                     normal server behavior,
-                                                     that is, an
-                                                     RPC_PROGVERSMISMATCH
-                                                     error will be returned.
-                                                     1 indicates that the out
-                                                     of range request will be
-                                                     silently ignored.
+                                If a request is received for a program number
+                                served by this server but the version number
+                                is outside the range registered with the
+                                server, an RPC_PROGVERSMISMATCH error will
+                                normally be returned.  info should be a
+                                pointer to an integer. Upon successful
+                                completion of the SVCGET_VERSQUIET request,
+                                *info contains an integer which describes the
+                                server's current behavior:  0 indicates normal
+                                server behavior, that is, an
+                                RPC_PROGVERSMISMATCH error will be returned.
+                                1 indicates that the out of range request will
+                                be silently ignored.
 
 
                             SVCSET_VERSQUIET
-                                                     If a request is received
-                                                     for a program number
-                                                     served by this server but
-                                                     the version number is
-                                                     outside the range
-                                                     registered with the
-                                                     server, an
-                                                     RPC_PROGVERSMISMATCH
-                                                     error will normally be
-                                                     returned.  It is
-                                                     sometimes desirable to
-                                                     change this behavior.
-                                                     info should be a pointer
-                                                     to an integer which is
-                                                     either  0, indicating
-                                                     normal server behavior
-                                                     and an
-                                                     RPC_PROGVERSMISMATCH
-                                                     error will be returned,
-                                                     or  1, indicating that
-                                                     the out of range request
-                                                     should be silently
-                                                     ignored.
+                                If a request is received for a program number
+                                served by this server but the version number
+                                is outside the range registered with the
+                                server, an RPC_PROGVERSMISMATCH error will
+                                normally be returned.  It is sometimes
+                                desirable to change this behavior. info should
+                                be a pointer to an integer which is either  0,
+                                indicating normal server behavior and an
+                                RPC_PROGVERSMISMATCH error will be returned,
+                                or  1, indicating that the out of range
+                                request should be silently ignored.
 
 
                             SVCGET_XID
-                                                     Returns the transaction
-                                                     ID of connection-oriented
-                                                     and connectionless
-                                                     transport service calls.
-                                                     The transaction  ID
-                                                     assists in uniquely
-                                                     identifying client
-                                                     requests for a given RPC
-                                                     version, program number,
-                                                     procedure, and client.
-                                                     The transaction  ID is
-                                                     extracted from the
-                                                     service transport handle
-                                                     svc. info must be a
-                                                     pointer  to an unsigned
-                                                     long.  Upon successful
-                                                     completion of the
-                                                     SVCGET_XID request,
-                                                     *info contains the
-                                                     transaction  ID. Note
-                                                     that rendezvous and raw
-                                                     service handles do not
-                                                     define a transaction  ID.
-                                                     Thus, if the service
-                                                     handle is of rendezvous
-                                                     or raw type, and the
-                                                     request is of type
-                                                     SVCGET_XID, svc_control()
-                                                     will return FALSE. Note
-                                                     also that the transaction
-                                                     ID read by the server can
-                                                     be set by the client
-                                                     through the suboption
-                                                     CLSET_XID in
-                                                     clnt_control(). See
-                                                     clnt_create(3NSL)
+                                Returns the transaction  ID of
+                                connection-oriented and connectionless
+                                transport service calls. The transaction  ID
+                                assists in uniquely identifying client
+                                requests for a given RPC version, program
+                                number, procedure, and client. The transaction
+                                ID is extracted from the service transport
+                                handle  svc. info must be a pointer  to an
+                                unsigned long.  Upon successful completion of
+                                the  SVCGET_XID request,  *info contains the
+                                transaction  ID. Note that rendezvous and raw
+                                service handles do not define a transaction
+                                ID. Thus, if the service handle is of
+                                rendezvous or raw type, and the request is of
+                                type SVCGET_XID, svc_control() will return
+                                FALSE. Note also that the transaction ID read
+                                by the server can be set by the client through
+                                the suboption CLSET_XID in  clnt_control().
+                                See clnt_create(3NSL)
 
 
                             SVCSET_RECVERRHANDLER
-                                                     Attaches or detaches a
-                                                     disconnection handler to
-                                                     the service handle, svc,
-                                                     that will be called when
-                                                     a transport error arrives
-                                                     during the reception of a
-                                                     request or when the
-                                                     server is waiting for a
-                                                     request and the
-                                                     connection shuts down.
-                                                     This handler is only
-                                                     useful for a connection
-                                                     oriented service handle.
+                                Attaches or detaches a disconnection handler
+                                to the service handle, svc, that will be
+                                called when a transport error arrives during
+                                the reception of a request or when the server
+                                is waiting for a request and the connection
+                                shuts down. This handler is only useful for a
+                                connection oriented service handle.
 
-                                                     *info contains the
-                                                     address of the error
-                                                     handler to attach, or
-                                                     NULL to detach a
-                                                     previously defined one.
-                                                     The error handler has two
-                                                     arguments. It has a
-                                                     pointer to the erroneous
-                                                     service handle. It also
-                                                     has an integer that
-                                                     indicates if the full
-                                                     service is closed (when
-                                                     equal to zero), or that
-                                                     only one connection on
-                                                     this service is closed
-                                                     (when not equal to zero).
+                                *info contains the address of the error
+                                handler to attach, or NULL to detach a
+                                previously defined one. The error handler has
+                                two arguments. It has a pointer to the
+                                erroneous service handle. It also has an
+                                integer that indicates if the full service is
+                                closed (when equal to zero), or that only one
+                                connection on this service is closed (when not
+                                equal to zero).
 
                                                        void handler (const SVCXPRT *svc, const bool_t isAConnection);
 
-                                                     With the service handle
-                                                     address, svc, the error
-                                                     handler is able to detect
-                                                     which connection has
-                                                     failed and to begin an
-                                                     error recovery process.
-                                                     The error handler can be
-                                                     called by multiple
-                                                     threads and should be
-                                                     implemented in an MT-safe
-                                                     way.
+                                With the service handle address, svc, the
+                                error handler is able to detect which
+                                connection has failed and to begin an error
+                                recovery process. The error handler can be
+                                called by multiple threads and should be
+                                implemented in an MT-safe way.
 
 
                             SVCGET_RECVERRHANDLER
-                                                     Upon successful
-                                                     completion of the
-                                                     SVCGET_RECVERRHANDLER
-                                                     request, *info contains
-                                                     the address of the
-                                                     handler for receiving
-                                                     errors. Upon failure,
-                                                     *info contains NULL.
+                                Upon successful completion of the
+                                SVCGET_RECVERRHANDLER request, *info contains
+                                the address of the handler for receiving
+                                errors. Upon failure, *info contains NULL.
 
 
                             SVCSET_CONNMAXREC
-                                                     Set the maximum record
-                                                     size (in bytes) and
-                                                     enable non-blocking mode
-                                                     for this service handle.
-                                                     Value can be set and read
-                                                     for both connection and
-                                                     non-connection oriented
-                                                     transports, but is
-                                                     silently ignored for the
-                                                     non-connection oriented
-                                                     case. The info argument
-                                                     should be a pointer to an
-                                                     int.
+                                Set the maximum record size (in bytes) and
+                                enable non-blocking mode for this service
+                                handle. Value can be set and read for both
+                                connection and non-connection oriented
+                                transports, but is silently ignored for the
+                                non-connection oriented case. The info
+                                argument should be a pointer to an int.
 
 
                             SVCGET_CONNMAXREC
-                                                     Get the maximum record
-                                                     size for this service
-                                                     handle. Zero means no
-                                                     maximum in effect and the
-                                                     connection is in blocking
-                                                     mode. The result is not
-                                                     significant for non-
-                                                     connection oriented
-                                                     transports. The info
-                                                     argument should be a
+                                Get the maximum record size for this service
+                                handle. Zero means no maximum in effect and
+                                the connection is in blocking mode. The result
+                                is not significant for non-connection oriented
+                                transports. The info argument should be a
                                                      pointer to an int.
 
                             This routine returns TRUE if the operation was
                             successful. Otherwise, it returns false.
 

@@ -253,139 +187,142 @@
 
        svc_create()
                             svc_create() creates server handles for all the
                             transports belonging to the class nettype.
 
-                            nettype defines a class of transports which can be
-                            used for a particular application. The transports
-                            are tried in left to right order in NETPATH
-                            variable or in top to bottom order in the
-                            netconfig database. If nettype is NULL, it
-                            defaults to netpath.
+                      nettype defines a class of transports which can be used
+                      for a particular application. The transports are tried
+                      in left to right order in NETPATH variable or in top to
+                      bottom order in the netconfig database. If nettype is
+                      NULL, it defaults to netpath.
 
-                            svc_create() registers itself with the rpcbind
-                            service (see rpcbind(1M)). dispatch is called when
-                            there is a remote procedure call for the given
-                            prognum and versnum; this requires calling
-                            svc_run() (see svc_run() in rpc_svc_calls(3NSL)).
-                            If svc_create() succeeds, it returns the number of
-                            server handles it created, otherwise it returns 0
-                            and an error message is logged.
+                      svc_create() registers itself with the rpcbind service
+                      (see rpcbind(1M)). dispatch is called when there is a
+                      remote procedure call for the given prognum and versnum;
+                      this requires calling svc_run() (see svc_run() in
+                      rpc_svc_calls(3NSL)). If svc_create() succeeds, it
+                      returns the number of server handles it created,
+                      otherwise it returns 0 and an error message is logged.
 
 
        svc_destroy()
-                            A function macro that destroys the RPC service
-                            handle xprt.  Destruction usually involves
-                            deallocation of private data structures, including
-                            xprt itself.  Use of xprt is undefined after
-                            calling this routine.
+                      A function macro that destroys the RPC service handle
+                      xprt.  Destruction usually involves deallocation of
+                      private data structures, including xprt itself.  Use of
+                      xprt is undefined after calling this routine.
 
 
        svc_dg_create()
                             This routine creates a connectionless RPC service
                             handle, and returns a pointer to it. This routine
                             returns NULL if it fails, and an error message is
-                            logged. sendsz and recvsz are parameters used to
-                            specify the size of the buffers. If they are 0,
-                            suitable defaults are chosen. The file descriptor
-                            fildes should be open and bound. The server is not
-                            registered with rpcbind(1M).
+                      logged. sendsz and recvsz are parameters used to specify
+                      the size of the buffers. If they are 0, suitable
+                      defaults are chosen. The file descriptor fildes should
+                      be open and bound. The server is not registered with
+                      rpcbind(1M).
 
-                            Warning: since connectionless-based RPC messages
-                            can only hold limited amount of encoded data, this
-                            transport cannot be used for procedures that take
-                            large arguments or return huge results.
+                      Warning: since connectionless-based RPC messages can
+                      only hold limited amount of encoded data, this transport
+                      cannot be used for procedures that take large arguments
+                      or return huge results.
 
 
        svc_fd_create()
-                            This routine creates a service on top of an open
-                            and bound file descriptor, and returns the handle
-                            to it. Typically, this descriptor is a connected
-                            file descriptor for a connection-oriented
-                            transport. sendsz and recvsz indicate sizes for
-                            the send and receive buffers. If they are 0,
-                            reasonable defaults are chosen. This routine
-                            returns NULL if it fails, and an error message is
-                            logged.
+                      This routine creates a service on top of an open and
+                      bound file descriptor, and returns the handle to it.
+                      Typically, this descriptor is a connected file
+                      descriptor for a connection-oriented transport. sendsz
+                      and recvsz indicate sizes for the send and receive
+                      buffers. If they are 0, reasonable defaults are chosen.
+                      This routine returns NULL if it fails, and an error
+                      message is logged.
 
 
        svc_raw_create()
-                            This routine creates an RPC service handle and
-                            returns a pointer to it.  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 clnt_raw_create() in
-                            rpc_clnt_create(3NSL)). This routine allows
-                            simulation of RPC and acquisition of RPC overheads
-                            (such as round trip times), without any kernel and
-                            networking interference. This routine returns NULL
+                      This routine creates an RPC service handle and returns a
+                      pointer to it.  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
+                      clnt_raw_create() in rpc_clnt_create(3NSL)). This
+                      routine allows simulation of RPC and acquisition of RPC
+                      overheads (such as round trip times), without any kernel
+                      and networking interference. This routine returns NULL
                             if it fails, and an error message is logged.
 
                             Note: svc_run() should not be called when the raw
                             interface is being used.
 
 
        svc_tli_create()
-                            This routine creates an RPC server handle, and
-                            returns a pointer to it.  fildes is the file
-                            descriptor on which the service is listening.  If
-                            fildes is RPC_ANYFD, it opens a file descriptor on
-                            the transport specified by netconf. If the file
-                            descriptor is unbound and bindaddr is non-null
-                            fildes is bound to the address specified by
-                            bindaddr, otherwise fildes is bound to a default
-                            address chosen by the transport. In the case where
-                            the default address is chosen, the number of
-                            outstanding connect requests is set to 8 for
-                            connection-oriented transports.  The user may
-                            specify the size of the send and receive buffers
-                            with the parameters sendsz and recvsz ; values of
-                            0 choose suitable defaults. This routine returns
-                            NULL if it fails, and an error message is logged.
-                            The server is not registered with the rpcbind(1M)
-                            service.
+                      This routine creates an RPC server handle, and returns a
+                      pointer to it.  fildes is the file descriptor on which
+                      the service is listening.  If fildes is RPC_ANYFD, it
+                      opens a file descriptor on the transport specified by
+                      netconf. If the file descriptor is unbound and bind_info
+                      is non-null fildes is bound to the address specified by
+                      bind_info, otherwise fildes is bound to a default
+                      address chosen by the transport. In the case where the
+                      default address is chosen, the number of outstanding
+                      connect requests is set to 8 for connection-oriented
+                      transports.  The user may specify the size of the send
+                      and receive buffers with the parameters sendsz and
+                      recvsz ; values of 0 choose suitable defaults. This
+                      routine returns NULL if it fails, and an error message
+                      is logged. The server is not registered with the
+                      rpcbind(1M) service.
 
 
        svc_tp_create()
-                            svc_tp_create() creates a server handle for the
-                            network specified by netconf, and registers itself
-                            with the rpcbind service.  dispatch is called when
-                            there is a remote procedure call for the given
-                            prognum and versnum; this requires calling
-                            svc_run().  svc_tp_create() returns the service
-                            handle if it succeeds, otherwise a NULL is
-                            returned and an error message is logged.
+                      svc_tp_create() creates a server handle for the network
+                      specified by netconf, and registers itself with the
+                      rpcbind service.  dispatch is called when there is a
+                      remote procedure call for the given prognum and versnum;
+                      this requires calling svc_run().  svc_tp_create()
+                      returns the service handle if it succeeds, otherwise a
+                      NULL is returned and an error message is logged.
 
 
+       svc_tp_create_addr()
+                      svc_tp_create_addr() creates a server handle for the
+                      network specified by netconf, and registers itself with
+                      the rpcbind service.  If bind_addr is non-NULL, that
+                      address is used for the listener binding.  If bind_addr
+                      is NULL, this call is the same as svc_tp_create().
+                      dispatch is called when there is a remote procedure call
+                      for the given prognum and versnum; this requires calling
+                      svc_run().  svc_tp_create_addr() returns the service
+                      handle if it succeeds, otherwise a NULL is returned and
+                      an error message is logged.
+
+
        svc_vc_create()
-                            This routine creates a connection-oriented RPC
-                            service and returns a pointer to it. This routine
-                            returns NULL if it fails, and an error message is
-                            logged. The users may specify the size of the send
-                            and receive buffers with the parameters sendsz and
-                            recvsz; values of 0 choose suitable defaults. The
-                            file descriptor fildes should be open and bound.
-                            The server is not registered with the rpcbind(1M)
-                            service.
+                      This routine creates a connection-oriented RPC service
+                      and returns a pointer to it. This routine returns NULL
+                      if it fails, and an error message is logged. The users
+                      may specify the size of the send and receive buffers
+                      with the parameters sendsz and recvsz; values of 0
+                      choose suitable defaults. The file descriptor fildes
+                      should be open and bound. The server is not registered
+                      with the rpcbind(1M) service.
 
 
        svc_door_create()
-                            This routine creates an RPC server handle over
-                            doors for the given program prognum and version
-                            versnum and returns a pointer to it. Doors is a
-                            transport mechanism that facilitates fast data
-                            transfer between processes on the same machine.
-                            The user may set the size of the send buffer with
-                            the parameter sendsz. If sendsz is 0, the
+                      This routine creates an RPC server handle over doors for
+                      the given program prognum and version versnum and
+                      returns a pointer to it.  Doors is a transport mechanism
+                      that facilitates fast data transfer between processes on
+                      the same machine. The user may set the size of the send
+                      buffer with the parameter sendsz. If sendsz is 0, the
                             corresponding default buffer size is 16 Kbyte. If
-                            successful, the svc_door_create() routine returns
-                            the service handle. Otherwise it returns NULL and
-                            sets a value for rpc_createerr. The server is not
-                            registered with rpcbind(1M). The SVCSET_CONNMAXREC
-                            and SVCGET_CONNMAXREC svc_control() requests can
-                            be used to set and change the maximum allowed
-                            request size for the doors transport.
+                      successful, the svc_door_create() routine returns the
+                      service handle. Otherwise it returns NULL and sets a
+                      value for rpc_createerr. The server is not registered
+                      with rpcbind(1M). The SVCSET_CONNMAXREC and
+                      SVCGET_CONNMAXREC svc_control() requests can be used to
+                      set and change the maximum allowed request size for the
+                      doors transport.
 
 
 ATTRIBUTES
        See attributes(5)  for descriptions of the following attributes:
 

@@ -406,6 +343,6 @@
        rpcbind(1M), rpc(3NSL), rpc_clnt_create(3NSL), rpc_svc_calls(3NSL),
        rpc_svc_err(3NSL), rpc_svc_reg(3NSL), attributes(5)
 
 
 
-                                 May 18, 2017             RPC_SVC_CREATE(3NSL)
+                                 June 19, 2017            RPC_SVC_CREATE(3NSL)