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>
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man3nsl/rpc_svc_create.3nsl
          +++ new/usr/src/man/man3nsl/rpc_svc_create.3nsl
   1    1  '\" te
   2      -.\" Copyright 2014 Nexenta Systems, Inc.  All Rights Reserved.
        2 +.\" Copyright 2017 Nexenta Systems, Inc.  All Rights Reserved.
   3    3  .\"  Copyright 1989 AT&T
   4    4  .\" Copyright (C) 2005, Sun Microsystems, Inc. All Rights Reserved.
   5    5  .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   6    6  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   7    7  .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8      -.TH RPC_SVC_CREATE 3NSL "May 18, 2017"
        8 +.TH RPC_SVC_CREATE 3NSL "Jun 19, 2017"
   9    9  .SH NAME
  10   10  rpc_svc_create, svc_control, svc_create, svc_destroy, svc_dg_create,
  11      -svc_fd_create, svc_raw_create, svc_tli_create, svc_tp_create, svc_vc_create,
       11 +svc_fd_create, svc_raw_create, svc_tli_create, svc_tp_create,
       12 +svc_tp_create_addr, svc_vc_create,
  12   13  svc_door_create \- server handle creation routines
  13   14  .SH SYNOPSIS
  14   15  .LP
  15   16  .nf
  16   17  #include <rpc/rpc.h>
  17   18  
  18   19  \fBbool_t\fR \fBsvc_control\fR(\fBSVCXPRT *\fR\fIsvc\fR, \fBconst uint_t\fR \fIreq\fR, \fBvoid *\fR\fIinfo\fR);
  19   20  .fi
  20   21  
  21   22  .LP
↓ open down ↓ 21 lines elided ↑ open up ↑ 
  43   44  .fi
  44   45  
  45   46  .LP
  46   47  .nf
  47   48  \fBSVCXPRT *\fR\fBsvc_raw_create\fR(void);
  48   49  .fi
  49   50  
  50   51  .LP
  51   52  .nf
  52   53  \fBSVCXPRT *\fR\fBsvc_tli_create\fR(\fBconst int\fR \fIfildes\fR, \fBconst struct netconfig *\fR\fInetconf\fR,
  53      -     \fBconst struct t_bind *\fR\fIbind_addr\fR, \fBconst uint_t\fR \fIsendsz\fR,
       54 +     \fBconst struct t_bind *\fR\fIbind_info\fR, \fBconst uint_t\fR \fIsendsz\fR,
  54   55       \fBconst uint_t\fR \fIrecvsz\fR);
  55   56  .fi
  56   57  
  57   58  .LP
  58   59  .nf
  59   60  \fBSVCXPRT *\fR\fBsvc_tp_create\fR(\fBconst void (*\fR\fIdispatch\fR)
  60   61       (const struct svc_req *, const SVCXPRT *), \fBconst rpcprog_t\fR \fIprognum\fR,
  61   62       \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst struct netconfig *\fR\fInetconf\fR);
  62   63  .fi
  63   64  
  64   65  .LP
  65   66  .nf
       67 +\fBSVCXPRT *\fR\fBsvc_tp_create_addr\fR(\fBconst void (*\fR\fIdispatch\fR)
       68 +     (const struct svc_req *, const SVCXPRT *), \fBconst rpcprog_t\fR \fIprognum\fR,
       69 +     \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst struct netconfig *\fR\fInetconf\fR,
       70 +     \fBconst struct netbuf *\fR\fIbind_addr\fR)
       71 +);
       72 +.fi
       73 +
       74 +.LP
       75 +.nf
  66   76  \fBSVCXPRT *\fR\fBsvc_vc_create\fR(\fBconst int\fR \fIfildes\fR, \fBconst uint_t\fR \fIsendsz\fR,
  67   77       \fBconst uint_t\fR \fIrecvsz\fR);
  68   78  .fi
  69   79  
  70   80  .LP
  71   81  .nf
  72   82  \fBSVCXPRT *\fR\fBsvc_door_create\fR(\fBvoid (*\fR\fIdispatch\fR)(struct svc_req *, SVCXPRT *),
  73   83       \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR,
  74   84       \fBconst uint_t\fR \fIsendsz\fR);
  75   85  .fi
↓ open down ↓ 5 lines elided ↑ open up ↑ 
  81   91  deal with the creation of service handles. Once the handle is created, the
  82   92  server can be invoked by calling \fBsvc_run()\fR.
  83   93  .SS "Routines"
  84   94  .LP
  85   95  See \fBrpc\fR(3NSL) for the definition of the \fBSVCXPRT\fR data structure.
  86   96  .sp
  87   97  .ne 2
  88   98  .na
  89   99  \fB\fBsvc_control()\fR\fR
  90  100  .ad
  91      -.RS 21n
      101 +.RS 15n
  92  102  A function to change or retrieve information about a service object. \fIreq\fR
  93  103  indicates the type of operation and \fIinfo\fR is a pointer to the information.
  94  104  The supported values of \fIreq\fR,  their argument types, and what they do are:
  95  105  .sp
  96  106  .ne 2
  97  107  .na
  98  108  \fB\fBSVCGET_VERSQUIET\fR\fR
  99  109  .ad
 100      -.RS 25n
      110 +.RS 10n
 101  111  If a request is received for a program number served by this server but the
 102  112  version number is outside the range registered with the server, an
 103  113  \fBRPC_PROGVERSMISMATCH\fR error will normally be returned.  \fIinfo\fR should
 104  114  be a pointer to an integer. Upon successful completion of the
 105  115  \fBSVCGET_VERSQUIET\fR request,  *\fIinfo\fR contains an integer which
 106  116  describes the server's current behavior:  \fB0\fR indicates normal server
 107  117  behavior, that is, an  \fBRPC_PROGVERSMISMATCH\fR error will be returned.
 108  118  \fB1\fR indicates that the out of range request will be silently ignored.
 109  119  .RE
 110  120  
 111  121  .sp
 112  122  .ne 2
 113  123  .na
 114  124  \fB\fBSVCSET_VERSQUIET\fR\fR
 115  125  .ad
 116      -.RS 25n
      126 +.RS 10n
 117  127  If a request is received for a program number served by this server but the
 118  128  version number is outside the range registered with the server, an
 119  129  \fBRPC_PROGVERSMISMATCH\fR error will normally be returned.  It is sometimes
 120  130  desirable to change this behavior. \fIinfo\fR should be a pointer to an integer
 121  131  which is either  \fB0\fR, indicating normal server behavior and an
 122  132  \fBRPC_PROGVERSMISMATCH\fR error will be returned, or  \fB1\fR, indicating that
 123  133  the out of range request should be silently ignored.
 124  134  .RE
 125  135  
 126  136  .sp
 127  137  .ne 2
 128  138  .na
 129  139  \fB\fBSVCGET_XID\fR\fR
 130  140  .ad
 131      -.RS 25n
      141 +.RS 10n
 132  142  Returns the transaction  \fBID\fR of connection\(mioriented and connectionless
 133  143  transport service calls. The transaction  \fBID\fR assists in uniquely
 134  144  identifying client requests for a given \fBRPC\fR version, program number,
 135  145  procedure, and client. The transaction  \fBID\fR is extracted from the service
 136  146  transport handle  \fIsvc\fR. \fIinfo\fR must be a pointer  to an unsigned long.
 137  147  Upon successful completion of the  \fBSVCGET_XID\fR request,  *\fIinfo\fR
 138  148  contains the transaction  \fBID\fR. Note that rendezvous and raw service
 139  149  handles do not define a transaction  \fBID\fR. Thus, if the service handle is
 140  150  of rendezvous or raw type, and the request is of type \fBSVCGET_XID,\fR
 141  151  \fBsvc_control()\fR will return \fBFALSE\fR. Note also that the transaction
 142  152  \fBID\fR read by the server can be set by the client through the suboption
 143  153  \fBCLSET_XID\fR in  \fBclnt_control()\fR. See \fBclnt_create\fR(3NSL)
 144  154  .RE
 145  155  
 146  156  .sp
 147  157  .ne 2
 148  158  .na
 149  159  \fB\fBSVCSET_RECVERRHANDLER\fR\fR
 150  160  .ad
 151      -.RS 25n
      161 +.RS 10n
 152  162  Attaches or detaches a disconnection handler to the service handle, \fIsvc\fR,
 153  163  that will be called when a transport error arrives during the reception of a
 154  164  request or when the server is waiting for a request and the connection shuts
 155  165  down. This handler is only useful for a connection oriented service handle.
 156  166  .sp
 157  167  \fI*info\fR contains the address of the error handler to attach, or \fINULL\fR
 158  168  to detach a previously defined one. The error handler has two arguments. It has
 159  169  a pointer to the erroneous service handle. It also has an integer that
 160  170  indicates if the full service is closed (when equal to zero), or that only one
 161  171  connection on this service is closed (when not equal to zero).
↓ open down ↓ 8 lines elided ↑ open up ↑ 
 170  180  which connection has failed and to begin an error recovery process. The error
 171  181  handler can be called by multiple threads and should be implemented in an
 172  182  MT-safe way.
 173  183  .RE
 174  184  
 175  185  .sp
 176  186  .ne 2
 177  187  .na
 178  188  \fB\fBSVCGET_RECVERRHANDLER\fR\fR
 179  189  .ad
 180      -.RS 25n
      190 +.RS 10n
 181  191  Upon successful completion of the \fBSVCGET_RECVERRHANDLER\fR request,
 182  192  \fI*info\fR contains the address of the handler for receiving errors. Upon
 183  193  failure, \fI*info\fR contains \fINULL\fR.
 184  194  .RE
 185  195  
 186  196  .sp
 187  197  .ne 2
 188  198  .na
 189  199  \fB\fBSVCSET_CONNMAXREC\fR\fR
 190  200  .ad
 191      -.RS 25n
      201 +.RS 10n
 192  202  Set the maximum record size (in bytes) and enable non-blocking mode for this
 193  203  service handle. Value can be set and read for both connection and
 194  204  non-connection oriented transports, but is silently ignored for the
 195  205  non-connection oriented case. The \fIinfo\fR argument should be a pointer to an
 196  206  \fBint\fR.
 197  207  .RE
 198  208  
 199  209  .sp
 200  210  .ne 2
 201  211  .na
 202  212  \fB\fBSVCGET_CONNMAXREC\fR\fR
 203  213  .ad
 204      -.RS 25n
      214 +.RS 10n
 205  215  Get the maximum record size for this service handle. Zero means no maximum in
 206  216  effect and the connection is in blocking mode. The result is not significant
 207  217  for non-connection oriented transports. The \fIinfo\fR argument should be a
 208  218  pointer to an \fBint\fR.
 209  219  .RE
 210  220  
 211  221  This routine returns TRUE if the operation was successful. Otherwise, it
 212  222  returns false.
 213  223  .RE
 214  224  
 215  225  .sp
 216  226  .ne 2
 217  227  .na
 218  228  \fB\fBsvc_create()\fR\fR
 219  229  .ad
 220      -.RS 21n
      230 +.RS 15n
 221  231  \fBsvc_create()\fR creates server handles for all the transports belonging to
 222  232  the class \fInettype\fR.
 223  233  .sp
 224  234  \fInettype\fR defines a class of transports which can be used for a particular
 225  235  application. The transports are tried in left to right order in \fBNETPATH\fR
 226  236  variable or in top to bottom order in the netconfig database. If \fInettype\fR
 227  237  is \fINULL,\fR it defaults to \fBnetpath\fR.
 228  238  .sp
 229  239  \fBsvc_create()\fR registers itself with the \fBrpcbind\fR service (see
 230  240  \fBrpcbind\fR(1M)). \fIdispatch\fR is called when there is a remote procedure
↓ open down ↓ 1 lines elided ↑ open up ↑ 
 232  242  \fBsvc_run()\fR (see \fBsvc_run()\fR in \fBrpc_svc_calls\fR(3NSL)). If
 233  243  \fBsvc_create()\fR succeeds, it returns the number of server handles it
 234  244  created, otherwise it returns \fB0\fR and an error message is logged.
 235  245  .RE
 236  246  
 237  247  .sp
 238  248  .ne 2
 239  249  .na
 240  250  \fB\fBsvc_destroy()\fR\fR
 241  251  .ad
 242      -.RS 21n
      252 +.RS 15n
 243  253  A function macro that destroys the \fBRPC\fR service handle \fIxprt\fR.
 244  254  Destruction usually involves deallocation of private data structures, including
 245  255  \fIxprt\fR itself.  Use of \fIxprt\fR is undefined after calling this routine.
 246  256  .RE
 247  257  
 248  258  .sp
 249  259  .ne 2
 250  260  .na
 251  261  \fB\fBsvc_dg_create()\fR\fR
 252  262  .ad
 253      -.RS 21n
      263 +.RS 15n
 254  264  This routine creates a connectionless \fBRPC\fR service handle, and returns a
 255  265  pointer to it. This routine returns \fINULL\fR if it fails, and an error
 256  266  message is logged. \fIsendsz\fR and \fIrecvsz\fR are parameters used to specify
 257  267  the size of the buffers. If they are \fB0\fR, suitable defaults are chosen. The
 258  268  file descriptor \fIfildes\fR should be open and bound. The server is not
 259  269  registered with \fBrpcbind\fR(1M).
 260  270  .sp
 261  271  Warning: since connectionless-based \fBRPC\fR messages can only hold limited
 262  272  amount of encoded data, this transport cannot be used for procedures that take
 263  273  large arguments or return huge results.
 264  274  .RE
 265  275  
 266  276  .sp
 267  277  .ne 2
 268  278  .na
 269  279  \fB\fBsvc_fd_create()\fR\fR
 270  280  .ad
 271      -.RS 21n
      281 +.RS 15n
 272  282  This routine creates a service on top of an open and bound file descriptor, and
 273  283  returns the handle to it. Typically, this descriptor is a connected file
 274  284  descriptor for a connection-oriented transport. \fIsendsz\fR and \fIrecvsz\fR
 275  285  indicate sizes for the send and receive buffers. If they are \fB0\fR,
 276  286  reasonable defaults are chosen. This routine returns \fINULL\fR if it fails,
 277  287  and an error message is logged.
 278  288  .RE
 279  289  
 280  290  .sp
 281  291  .ne 2
 282  292  .na
 283  293  \fB\fBsvc_raw_create()\fR\fR
 284  294  .ad
 285      -.RS 21n
      295 +.RS 15n
 286  296  This routine creates an \fBRPC\fR service handle and returns a pointer to it.
 287  297  The transport is really a buffer within the process's address space, so the
 288  298  corresponding \fBRPC\fR client should live in the same address space; (see
 289  299  \fBclnt_raw_create()\fR in \fBrpc_clnt_create\fR(3NSL)). This routine allows
 290  300  simulation of \fBRPC\fR and acquisition of \fBRPC\fR overheads (such as round
 291  301  trip times), without any kernel and networking interference. This routine
 292  302  returns \fINULL\fR if it fails, and an error message is logged.
 293  303  .sp
 294  304  Note: \fBsvc_run()\fR should not be called when the raw interface is being
 295  305  used.
 296  306  .RE
 297  307  
 298  308  .sp
 299  309  .ne 2
 300  310  .na
 301  311  \fB\fBsvc_tli_create()\fR\fR
 302  312  .ad
 303      -.RS 21n
      313 +.RS 15n
 304  314  This routine creates an \fBRPC\fR server handle, and returns a pointer to it.
 305  315  \fIfildes\fR is the file descriptor on which the service is listening.  If
 306  316  \fIfildes\fR is \fBRPC_ANYFD\fR, it opens a file descriptor on the transport
 307  317  specified by \fInetconf\fR. If the file descriptor is unbound and
 308      -\fIbindaddr\fR is non-null \fIfildes\fR is bound to the address specified by
 309      -\fIbindaddr\fR, otherwise \fIfildes\fR is bound to a default address chosen by
      318 +\fIbind_info\fR is non-null \fIfildes\fR is bound to the address specified by
      319 +\fIbind_info\fR, otherwise \fIfildes\fR is bound to a default address chosen by
 310  320  the transport. In the case where the default address is chosen, the number of
 311  321  outstanding connect requests is set to 8 for connection-oriented transports.
 312  322  The user may specify the size of the send and receive buffers with the
 313  323  parameters \fIsendsz\fR and \fIrecvsz\fR \fI;\fR values of \fB0\fR choose
 314  324  suitable defaults. This routine returns \fINULL\fR if it fails, and an error
 315  325  message is logged. The server is not registered with the \fBrpcbind\fR(1M)
 316  326  service.
 317  327  .RE
 318  328  
 319  329  .sp
 320  330  .ne 2
 321  331  .na
 322  332  \fB\fBsvc_tp_create()\fR\fR
 323  333  .ad
 324      -.RS 21n
      334 +.RS 15n
 325  335  \fBsvc_tp_create()\fR creates a server handle for the network specified by
 326  336  \fInetconf\fR, and registers itself with the \fBrpcbind\fR service.
 327  337  \fIdispatch\fR is called when there is a remote procedure call for the given
 328  338  \fIprognum\fR and \fIversnum\fR; this requires calling \fBsvc_run()\fR.
 329  339  \fBsvc_tp_create()\fR returns the service handle if it succeeds, otherwise a
 330  340  \fINULL\fR is returned and an error message is logged.
 331  341  .RE
 332  342  
 333  343  .sp
 334  344  .ne 2
 335  345  .na
      346 +\fB\fBsvc_tp_create_addr()\fR\fR
      347 +.ad
      348 +.RS 15n
      349 +\fBsvc_tp_create_addr()\fR creates a server handle for the network specified
      350 +by \fInetconf\fR, and registers itself with the \fBrpcbind\fR service.
      351 +If \fIbind_addr\fR is non-NULL, that address is used for the listener binding.
      352 +If \fIbind_addr\fR is NULL, this call is the same as \fBsvc_tp_create()\fR.
      353 +\fIdispatch\fR is called when there is a remote procedure call for the given
      354 +\fIprognum\fR and \fIversnum\fR; this requires calling \fBsvc_run()\fR.
      355 +\fBsvc_tp_create_addr()\fR returns the service handle if it succeeds,
      356 +otherwise a \fINULL\fR is returned and an error message is logged.
      357 +.RE
      358 +
      359 +.sp
      360 +.ne 2
      361 +.na
 336  362  \fB\fBsvc_vc_create()\fR\fR
 337  363  .ad
 338      -.RS 21n
      364 +.RS 15n
 339  365  This routine creates a connection-oriented \fBRPC\fR service and returns a
 340  366  pointer to it. This routine returns \fINULL\fR if it fails, and an error
 341  367  message is logged. The users may specify the size of the send and receive
 342  368  buffers with the parameters \fIsendsz\fR and \fIrecvsz\fR; values of \fB0\fR
 343  369  choose suitable defaults. The file descriptor \fIfildes\fR should be open and
 344  370  bound. The server is not registered with the \fBrpcbind\fR(1M) service.
 345  371  .RE
 346  372  
 347  373  .sp
 348  374  .ne 2
 349  375  .na
 350  376  \fB\fBsvc_door_create()\fR\fR
 351  377  .ad
 352      -.RS 21n
      378 +.RS 15n
 353  379  This routine creates an RPC server handle over doors for the given program
 354      -\fIprognum\fR and version \fIversnum\fR and returns a pointer to
 355      -it. Doors is a transport mechanism that facilitates fast data transfer between
      380 +\fIprognum\fR and version \fIversnum\fR and returns a pointer to it.
      381 +Doors is a transport mechanism that facilitates fast data transfer between
 356  382  processes on the same machine. The user may set the size
 357  383  of the send buffer with the parameter \fIsendsz\fR. If \fIsendsz\fR is 0, the
 358  384  corresponding default buffer size is 16 Kbyte. If successful, the
 359  385  \fBsvc_door_create()\fR routine returns the service handle. Otherwise it
 360  386  returns \fINULL\fR and sets a value for \fBrpc_createerr\fR. The server is not
 361  387  registered with \fBrpcbind\fR(1M). The \fBSVCSET_CONNMAXREC\fR and
 362  388  \fBSVCGET_CONNMAXREC\fR \fBsvc_control()\fR requests can be used to set and
 363  389  change the maximum allowed request size for the doors transport.
 364  390  .RE
 365  391
↓ open down ↓ 24 lines elided ↑ open up ↑ 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX