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