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)