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_vc_create, svc_door_create - server handle creation routines
9
10 SYNOPSIS
11 #include <rpc/rpc.h>
12
13 bool_t svc_control(SVCXPRT *svc, const uint_t req, void *info);
14
15
16 int svc_create(const void (*dispatch)(const struct svc_req *,
17 const SVCXPRT *), const rpcprog_t prognum, const rpcvers_t versnum,
18 const char *nettype);
19
20
21 void svc_destroy(SVCXPRT *xprt);
22
23
24 SVCXPRT *svc_dg_create(const int fildes, const uint_t sendsz,
25 const uint_t recvsz);
26
27
28 SVCXPRT *svc_fd_create(const int fildes, const uint_t sendsz,
29 const uint_t recvsz);
30
31
32 SVCXPRT *svc_raw_create(void);
33
34
35 SVCXPRT *svc_tli_create(const int fildes, const struct netconfig *netconf,
36 const struct t_bind *bind_addr, const uint_t sendsz,
37 const uint_t recvsz);
38
39
40 SVCXPRT *svc_tp_create(const void (*dispatch)
41 (const struct svc_req *, const SVCXPRT *), const rpcprog_t prognum,
42 const rpcvers_t versnum, const struct netconfig *netconf);
43
44
45 SVCXPRT *svc_vc_create(const int fildes, const uint_t sendsz,
46 const uint_t recvsz);
47
48
49 SVCXPRT *svc_door_create(void (*dispatch)(struct svc_req *, SVCXPRT *),
50 const rpcprog_t prognum, const rpcvers_t versnum,
51 const uint_t sendsz);
52
53
54 DESCRIPTION
55 These routines are part of the RPC library which allows C language
56 programs to make procedure calls on servers across the network. These
57 routines deal with the creation of service handles. Once the handle is
58 created, the server can be invoked by calling svc_run().
59
60 Routines
61 See rpc(3NSL) for the definition of the SVCXPRT data structure.
62
63 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:
69
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.
96
97
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.
122
123
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)
161
162
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.
177
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).
194
195 void handler (const SVCXPRT *svc, const bool_t isAConnection);
196
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.
208
209
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.
219
220
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.
235
236
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.
249
250 This routine returns TRUE if the operation was
251 successful. Otherwise, it returns false.
252
253
254 svc_create()
255 svc_create() creates server handles for all the
256 transports belonging to the class nettype.
257
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.
264
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.
273
274
275 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.
281
282
283 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).
292
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.
297
298
299 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.
309
310
311 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.
322
323 Note: svc_run() should not be called when the raw
324 interface is being used.
325
326
327 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.
346
347
348 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.
357
358
359 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.
369
370
371 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.
387
388
389 ATTRIBUTES
390 See attributes(5) for descriptions of the following attributes:
391
392
393
394
395 +--------------------+-----------------+
396 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
397 +--------------------+-----------------+
398 |Architecture | All |
399 +--------------------+-----------------+
400 |Interface Stability | Evolving |
401 +--------------------+-----------------+
402 |MT-Level | MT-Safe |
403 +--------------------+-----------------+
404
405 SEE ALSO
406 rpcbind(1M), rpc(3NSL), rpc_clnt_create(3NSL), rpc_svc_calls(3NSL),
407 rpc_svc_err(3NSL), rpc_svc_reg(3NSL), attributes(5)
408
409
410
411 May 18, 2017 RPC_SVC_CREATE(3NSL)
|
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)
|