1 RPC_SVC_CREATE(3NSL)                     Networking Services Library Functions
   2 
   3 
   4 
   5 NAME
   6        rpc_svc_create, svc_control, svc_create, svc_destroy, svc_dg_create,
   7        svc_fd_create, svc_raw_create, svc_tli_create, svc_tp_create,
   8        svc_tp_create_addr, svc_vc_create, svc_door_create - server handle
   9        creation routines
  10 
  11 SYNOPSIS
  12        #include <rpc/rpc.h>
  13 
  14        bool_t svc_control(SVCXPRT *svc, const uint_t req, void *info);
  15 
  16 
  17        int svc_create(const void (*dispatch)(const struct svc_req *,
  18             const SVCXPRT *), const rpcprog_t prognum, const rpcvers_t versnum,
  19             const char *nettype);
  20 
  21 
  22        void svc_destroy(SVCXPRT *xprt);
  23 
  24 
  25        SVCXPRT *svc_dg_create(const int fildes, const uint_t sendsz,
  26             const uint_t recvsz);
  27 
  28 
  29        SVCXPRT *svc_fd_create(const int fildes, const uint_t sendsz,
  30             const uint_t recvsz);
  31 
  32 
  33        SVCXPRT *svc_raw_create(void);
  34 
  35 
  36        SVCXPRT *svc_tli_create(const int fildes, const struct netconfig *netconf,
  37             const struct t_bind *bind_info, const uint_t sendsz,
  38             const uint_t recvsz);
  39 
  40 
  41        SVCXPRT *svc_tp_create(const void (*dispatch)
  42             (const struct svc_req *, const SVCXPRT *), const rpcprog_t prognum,
  43             const rpcvers_t versnum, const struct netconfig *netconf);
  44 
  45 
  46        SVCXPRT *svc_tp_create_addr(const void (*dispatch)
  47             (const struct svc_req *, const SVCXPRT *), const rpcprog_t prognum,
  48             const rpcvers_t versnum, const struct netconfig *netconf,
  49             const struct netbuf *bind_addr)
  50        );
  51 
  52 
  53        SVCXPRT *svc_vc_create(const int fildes, const uint_t sendsz,
  54             const uint_t recvsz);
  55 
  56 
  57        SVCXPRT *svc_door_create(void (*dispatch)(struct svc_req *, SVCXPRT *),
  58             const rpcprog_t prognum, const rpcvers_t versnum,
  59             const uint_t sendsz);
  60 
  61 
  62 DESCRIPTION
  63        These routines are part of the RPC library which allows C language
  64        programs to make procedure calls on servers across the network. These
  65        routines deal with the creation of service handles. Once the handle is
  66        created, the server can be invoked by calling svc_run().
  67 
  68    Routines
  69        See rpc(3NSL) for the definition of the SVCXPRT data structure.
  70 
  71        svc_control()
  72                       A function to change or retrieve information about a
  73                       service object. req indicates the type of operation and
  74                       info is a pointer to the information.  The supported
  75                       values of req,  their argument types, and what they do
  76                       are:
  77 
  78                       SVCGET_VERSQUIET
  79                                 If a request is received for a program number
  80                                 served by this server but the version number
  81                                 is outside the range registered with the
  82                                 server, an RPC_PROGVERSMISMATCH error will
  83                                 normally be returned.  info should be a
  84                                 pointer to an integer. Upon successful
  85                                 completion of the SVCGET_VERSQUIET request,
  86                                 *info contains an integer which describes the
  87                                 server's current behavior:  0 indicates normal
  88                                 server behavior, that is, an
  89                                 RPC_PROGVERSMISMATCH error will be returned.
  90                                 1 indicates that the out of range request will
  91                                 be silently ignored.
  92 
  93 
  94                       SVCSET_VERSQUIET
  95                                 If a request is received for a program number
  96                                 served by this server but the version number
  97                                 is outside the range registered with the
  98                                 server, an RPC_PROGVERSMISMATCH error will
  99                                 normally be returned.  It is sometimes
 100                                 desirable to change this behavior. info should
 101                                 be a pointer to an integer which is either  0,
 102                                 indicating normal server behavior and an
 103                                 RPC_PROGVERSMISMATCH error will be returned,
 104                                 or  1, indicating that the out of range
 105                                 request should be silently ignored.
 106 
 107 
 108                       SVCGET_XID
 109                                 Returns the transaction  ID of
 110                                 connection-oriented and connectionless
 111                                 transport service calls. The transaction  ID
 112                                 assists in uniquely identifying client
 113                                 requests for a given RPC version, program
 114                                 number, procedure, and client. The transaction
 115                                 ID is extracted from the service transport
 116                                 handle  svc. info must be a pointer  to an
 117                                 unsigned long.  Upon successful completion of
 118                                 the  SVCGET_XID request,  *info contains the
 119                                 transaction  ID. Note that rendezvous and raw
 120                                 service handles do not define a transaction
 121                                 ID. Thus, if the service handle is of
 122                                 rendezvous or raw type, and the request is of
 123                                 type SVCGET_XID, svc_control() will return
 124                                 FALSE. Note also that the transaction ID read
 125                                 by the server can be set by the client through
 126                                 the suboption CLSET_XID in  clnt_control().
 127                                 See clnt_create(3NSL)
 128 
 129 
 130                       SVCSET_RECVERRHANDLER
 131                                 Attaches or detaches a disconnection handler
 132                                 to the service handle, svc, that will be
 133                                 called when a transport error arrives during
 134                                 the reception of a request or when the server
 135                                 is waiting for a request and the connection
 136                                 shuts down. This handler is only useful for a
 137                                 connection oriented service handle.
 138 
 139                                 *info contains the address of the error
 140                                 handler to attach, or NULL to detach a
 141                                 previously defined one. The error handler has
 142                                 two arguments. It has a pointer to the
 143                                 erroneous service handle. It also has an
 144                                 integer that indicates if the full service is
 145                                 closed (when equal to zero), or that only one
 146                                 connection on this service is closed (when not
 147                                 equal to zero).
 148 
 149                                   void handler (const SVCXPRT *svc, const bool_t isAConnection);
 150 
 151                                 With the service handle address, svc, the
 152                                 error handler is able to detect which
 153                                 connection has failed and to begin an error
 154                                 recovery process. The error handler can be
 155                                 called by multiple threads and should be
 156                                 implemented in an MT-safe way.
 157 
 158 
 159                       SVCGET_RECVERRHANDLER
 160                                 Upon successful completion of the
 161                                 SVCGET_RECVERRHANDLER request, *info contains
 162                                 the address of the handler for receiving
 163                                 errors. Upon failure, *info contains NULL.
 164 
 165 
 166                       SVCSET_CONNMAXREC
 167                                 Set the maximum record size (in bytes) and
 168                                 enable non-blocking mode for this service
 169                                 handle. Value can be set and read for both
 170                                 connection and non-connection oriented
 171                                 transports, but is silently ignored for the
 172                                 non-connection oriented case. The info
 173                                 argument should be a pointer to an int.
 174 
 175 
 176                       SVCGET_CONNMAXREC
 177                                 Get the maximum record size for this service
 178                                 handle. Zero means no maximum in effect and
 179                                 the connection is in blocking mode. The result
 180                                 is not significant for non-connection oriented
 181                                 transports. The info argument should be a
 182                                 pointer to an int.
 183 
 184                       This routine returns TRUE if the operation was
 185                       successful. Otherwise, it returns false.
 186 
 187 
 188        svc_create()
 189                       svc_create() creates server handles for all the
 190                       transports belonging to the class nettype.
 191 
 192                       nettype defines a class of transports which can be used
 193                       for a particular application. The transports are tried
 194                       in left to right order in NETPATH variable or in top to
 195                       bottom order in the netconfig database. If nettype is
 196                       NULL, it defaults to netpath.
 197 
 198                       svc_create() registers itself with the rpcbind service
 199                       (see rpcbind(1M)). dispatch is called when there is a
 200                       remote procedure call for the given prognum and versnum;
 201                       this requires calling svc_run() (see svc_run() in
 202                       rpc_svc_calls(3NSL)). If svc_create() succeeds, it
 203                       returns the number of server handles it created,
 204                       otherwise it returns 0 and an error message is logged.
 205 
 206 
 207        svc_destroy()
 208                       A function macro that destroys the RPC service handle
 209                       xprt.  Destruction usually involves deallocation of
 210                       private data structures, including xprt itself.  Use of
 211                       xprt is undefined after calling this routine.
 212 
 213 
 214        svc_dg_create()
 215                       This routine creates a connectionless RPC service
 216                       handle, and returns a pointer to it. This routine
 217                       returns NULL if it fails, and an error message is
 218                       logged. sendsz and recvsz are parameters used to specify
 219                       the size of the buffers. If they are 0, suitable
 220                       defaults are chosen. The file descriptor fildes should
 221                       be open and bound. The server is not registered with
 222                       rpcbind(1M).
 223 
 224                       Warning: since connectionless-based RPC messages can
 225                       only hold limited amount of encoded data, this transport
 226                       cannot be used for procedures that take large arguments
 227                       or return huge results.
 228 
 229 
 230        svc_fd_create()
 231                       This routine creates a service on top of an open and
 232                       bound file descriptor, and returns the handle to it.
 233                       Typically, this descriptor is a connected file
 234                       descriptor for a connection-oriented transport. sendsz
 235                       and recvsz indicate sizes for the send and receive
 236                       buffers. If they are 0, reasonable defaults are chosen.
 237                       This routine returns NULL if it fails, and an error
 238                       message is logged.
 239 
 240 
 241        svc_raw_create()
 242                       This routine creates an RPC service handle and returns a
 243                       pointer to it.  The transport is really a buffer within
 244                       the process's address space, so the corresponding RPC
 245                       client should live in the same address space; (see
 246                       clnt_raw_create() in rpc_clnt_create(3NSL)). This
 247                       routine allows simulation of RPC and acquisition of RPC
 248                       overheads (such as round trip times), without any kernel
 249                       and networking interference. This routine returns NULL
 250                       if it fails, and an error message is logged.
 251 
 252                       Note: svc_run() should not be called when the raw
 253                       interface is being used.
 254 
 255 
 256        svc_tli_create()
 257                       This routine creates an RPC server handle, and returns a
 258                       pointer to it.  fildes is the file descriptor on which
 259                       the service is listening.  If fildes is RPC_ANYFD, it
 260                       opens a file descriptor on the transport specified by
 261                       netconf. If the file descriptor is unbound and bind_info
 262                       is non-null fildes is bound to the address specified by
 263                       bind_info, otherwise fildes is bound to a default
 264                       address chosen by the transport. In the case where the
 265                       default address is chosen, the number of outstanding
 266                       connect requests is set to 8 for connection-oriented
 267                       transports.  The user may specify the size of the send
 268                       and receive buffers with the parameters sendsz and
 269                       recvsz ; values of 0 choose suitable defaults. This
 270                       routine returns NULL if it fails, and an error message
 271                       is logged. The server is not registered with the
 272                       rpcbind(1M) service.
 273 
 274 
 275        svc_tp_create()
 276                       svc_tp_create() creates a server handle for the network
 277                       specified by netconf, and registers itself with the
 278                       rpcbind service.  dispatch is called when there is a
 279                       remote procedure call for the given prognum and versnum;
 280                       this requires calling svc_run().  svc_tp_create()
 281                       returns the service handle if it succeeds, otherwise a
 282                       NULL is returned and an error message is logged.
 283 
 284 
 285        svc_tp_create_addr()
 286                       svc_tp_create_addr() creates a server handle for the
 287                       network specified by netconf, and registers itself with
 288                       the rpcbind service.  If bind_addr is non-NULL, that
 289                       address is used for the listener binding.  If bind_addr
 290                       is NULL, this call is the same as svc_tp_create().
 291                       dispatch is called when there is a remote procedure call
 292                       for the given prognum and versnum; this requires calling
 293                       svc_run().  svc_tp_create_addr() returns the service
 294                       handle if it succeeds, otherwise a NULL is returned and
 295                       an error message is logged.
 296 
 297 
 298        svc_vc_create()
 299                       This routine creates a connection-oriented RPC service
 300                       and returns a pointer to it. This routine returns NULL
 301                       if it fails, and an error message is logged. The users
 302                       may specify the size of the send and receive buffers
 303                       with the parameters sendsz and recvsz; values of 0
 304                       choose suitable defaults. The file descriptor fildes
 305                       should be open and bound. The server is not registered
 306                       with the rpcbind(1M) service.
 307 
 308 
 309        svc_door_create()
 310                       This routine creates an RPC server handle over doors for
 311                       the given program prognum and version versnum and
 312                       returns a pointer to it.  Doors is a transport mechanism
 313                       that facilitates fast data transfer between processes on
 314                       the same machine. The user may set the size of the send
 315                       buffer with the parameter sendsz. If sendsz is 0, the
 316                       corresponding default buffer size is 16 Kbyte. If
 317                       successful, the svc_door_create() routine returns the
 318                       service handle. Otherwise it returns NULL and sets a
 319                       value for rpc_createerr. The server is not registered
 320                       with rpcbind(1M). The SVCSET_CONNMAXREC and
 321                       SVCGET_CONNMAXREC svc_control() requests can be used to
 322                       set and change the maximum allowed request size for the
 323                       doors transport.
 324 
 325 
 326 ATTRIBUTES
 327        See attributes(5)  for descriptions of the following attributes:
 328 
 329 
 330 
 331 
 332        +--------------------+-----------------+
 333        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 334        +--------------------+-----------------+
 335        |Architecture        | All             |
 336        +--------------------+-----------------+
 337        |Interface Stability | Evolving        |
 338        +--------------------+-----------------+
 339        |MT-Level            | MT-Safe         |
 340        +--------------------+-----------------+
 341 
 342 SEE ALSO
 343        rpcbind(1M), rpc(3NSL), rpc_clnt_create(3NSL), rpc_svc_calls(3NSL),
 344        rpc_svc_err(3NSL), rpc_svc_reg(3NSL), attributes(5)
 345 
 346 
 347 
 348                                  June 19, 2017            RPC_SVC_CREATE(3NSL)