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