1rpc_svc_create(3NSL) Networking Services Library Functionsrpc_svc_create(3NSL)
2
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
11 #include <rpc/rpc.h>
12 bool_t svc_control(SVCXPRT *svc, const uint_t req, void *info);
14 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 void svc_destroy(SVCXPRT *xprt);
22 SVCXPRT *svc_dg_create(const int fildes, const uint_t sendsz,
25 const uint_t recvsz);
26 SVCXPRT *svc_fd_create(const int fildes, const uint_t sendsz,
29 const uint_t recvsz);
30 SVCXPRT *svc_raw_create(void)
33 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 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 SVCXPRT *svc_vc_create(const int fildes, const uint_t sendsz,
46 const uint_t recvsz);
47 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
55 These routines are part of the RPC library which allows C language pro‐
56 grams to make procedure calls on servers across the network. These rou‐
57 tines deal with the creation of service handles. Once the handle is
58 created, the server can be invoked by calling svc_run().
59 Routines
61 See rpc(3NSL) for the definition of the SVCXPRT data structure.
62 svc_control() A function to change or retrieve information about
64 a service object. req indicates the type of opera‐
65 tion and info is a pointer to the information. The
66 supported values of req, their argument types,
67 and what they do are:
68 SVCGET_VERSQUIET If a request is received
70 for a program number
71 served by this server but
72 the version number is
73 outside the range regis‐
74 tered with the server, an
75 RPC_PROGVERSMISMATCH
76 error will normally be
77 returned. info should be
78 a pointer to an integer.
79 Upon successful comple‐
80 tion of the SVCGET_VER‐
81 SQUIET request, *info
82 contains an integer which
83 describes the server's
84 current behavior: 0
85 indicates normal server
86 behavior, that is, an
87 RPC_PROGVERSMISMATCH
88 error will be returned. 1
89 indicates that the out of
90 range request will be
91 silently ignored.
92 SVCSET_VERSQUIET If a request is received
95 for a program number
96 served by this server but
97 the version number is
98 outside the range regis‐
99 tered with the server, an
100 RPC_PROGVERSMISMATCH
101 error will normally be
102 returned. It is some‐
103 times desirable to change
104 this behavior. info
105 should be a pointer to an
106 integer which is either
107 0, indicating normal
108 server behavior and an
109 RPC_PROGVERSMISMATCH
110 error will be returned,
111 or 1, indicating that
112 the out of range request
113 should be silently
114 ignored.
115 SVCGET_XID Returns the transaction
118 ID of connection−oriented
119 and connectionless trans‐
120 port service calls. The
121 transaction ID assists
122 in uniquely identifying
123 client requests for a
124 given RPC version, pro‐
125 gram number, procedure,
126 and client. The transac‐
127 tion ID is extracted
128 from the service trans‐
129 port handle svc. info
130 must be a pointer to an
131 unsigned long. Upon suc‐
132 cessful completion of the
133 SVCGET_XID request,
134 *info contains the trans‐
135 action ID. Note that
136 rendezvous and raw ser‐
137 vice handles do not
138 define a transaction ID.
139 Thus, if the service han‐
140 dle is of rendezvous or
141 raw type, and the request
142 is of type SVCGET_XID,
143 svc_control() will return
144 FALSE. Note also that the
145 transaction ID read by
146 the server can be set by
147 the client through the
148 suboption CLSET_XID in
149 clnt_control(). See
150 clnt_create(3NSL)
151 SVCSET_RECVERRHANDLER Attaches or detaches a
154 disconnection handler to
155 the service handle, svc,
156 that will be called when
157 a transport error arrives
158 during the reception of a
159 request or when the
160 server is waiting for a
161 request and the connec‐
162 tion shuts down. This
163 handler is only useful
164 for a connection oriented
165 service handle.
166 *info contains the
168 address of the error han‐
169 dler to attach, or NULL
170 to detach a previously
171 defined one. The error
172 handler has two argu‐
173 ments. It has a pointer
174 to the erroneous service
175 handle. It also has an
176 integer that indicates if
177 the full service is
178 closed (when equal to
179 zero), or that only one
180 connection on this ser‐
181 vice is closed (when not
182 equal to zero).
183 void handler (const SVCXPRT *svc, const bool_t isAConnection);
185 With the service handle
187 address, svc, the error
188 handler is able to detect
189 which connection has
190 failed and to begin an
191 error recovery process.
192 The error handler can be
193 called by multiple
194 threads and should be
195 implemented in an MT-safe
196 way.
197 SVCGET_RECVERRHANDLER Upon successful comple‐
200 tion of the
201 SVCGET_RECVERRHANDLER
202 request, *info contains
203 the address of the han‐
204 dler for receiving
205 errors. Upon failure,
206 *info contains NULL.
207 SVCSET_CONNMAXREC Set the maximum record
210 size (in bytes) and
211 enable non-blocking mode
212 for this service handle.
213 Value can be set and read
214 for both connection and
215 non-connection oriented
216 transports, but is
217 silently ignored for the
218 non-connection oriented
219 case. The info argument
220 should be a pointer to an
221 int.
222 SVCGET_CONNMAXREC Get the maximum record
225 size for this service
226 handle. Zero means no
227 maximum in effect and the
228 connection is in blocking
229 mode. The result is not
230 significant for non-con‐
231 nection oriented trans‐
232 ports. The info argument
233 should be a pointer to an
234 int.
235 This routine returns TRUE if the operation was
237 successful. Otherwise, it returns false.
238 svc_create() svc_create() creates server handles for all the
241 transports belonging to the class nettype.
242 nettype defines a class of transports which can be
244 used for a particular application. The transports
245 are tried in left to right order in NETPATH vari‐
246 able or in top to bottom order in the netconfig
247 database. If nettype is NULL, it defaults to net‐
248 path.
249 svc_create() registers itself with the rpcbind
251 service (see rpcbind(1M)). dispatch is called when
252 there is a remote procedure call for the given
253 prognum and versnum; this requires calling
254 svc_run() (see svc_run() in rpc_svc_reg(3NSL)). If
255 svc_create() succeeds, it returns the number of
256 server handles it created, otherwise it returns 0
257 and an error message is logged.
258 svc_destroy() A function macro that destroys the RPC service
261 handle xprt. Destruction usually involves deallo‐
262 cation of private data structures, including xprt
263 itself. Use of xprt is undefined after calling
264 this routine.
265 svc_dg_create() This routine creates a connectionless RPC service
268 handle, and returns a pointer to it. This routine
269 returns NULL if it fails, and an error message is
270 logged. sendsz and recvsz are parameters used to
271 specify the size of the buffers. If they are 0,
272 suitable defaults are chosen. The file descriptor
273 fildes should be open and bound. The server is not
274 registered with rpcbind(1M).
275 Warning: since connectionless-based RPC messages
277 can only hold limited amount of encoded data, this
278 transport cannot be used for procedures that take
279 large arguments or return huge results.
280 svc_fd_create() This routine creates a service on top of an open
283 and bound file descriptor, and returns the handle
284 to it. Typically, this descriptor is a connected
285 file descriptor for a connection-oriented trans‐
286 port. sendsz and recvsz indicate sizes for the
287 send and receive buffers. If they are 0, reason‐
288 able defaults are chosen. This routine returns
289 NULL if it fails, and an error message is logged.
290 svc_raw_create() This routine creates an RPC service handle and
293 returns a pointer to it. The transport is really a
294 buffer within the process's address space, so the
295 corresponding RPC client should live in the same
296 address space; (see clnt_raw_create() in
297 rpc_clnt_create(3NSL)). This routine allows simu‐
298 lation of RPC and acquisition of RPC overheads
299 (such as round trip times), without any kernel and
300 networking interference. This routine returns NULL
301 if it fails, and an error message is logged.
302 Note: svc_run() should not be called when the raw
304 interface is being used.
305 svc_tli_create() This routine creates an RPC server handle, and
308 returns a pointer to it. fildes is the file
309 descriptor on which the service is listening. If
310 fildes is RPC_ANYFD, it opens a file descriptor on
311 the transport specified by netconf. If the file
312 descriptor is unbound and bindaddr is non-null
313 fildes is bound to the address specified by
314 bindaddr, otherwise fildes is bound to a default
315 address chosen by the transport. In the case where
316 the default address is chosen, the number of out‐
317 standing connect requests is set to 8 for connec‐
318 tion-oriented transports. The user may specify the
319 size of the send and receive buffers with the
320 parameters sendsz and recvsz ; values of 0 choose
321 suitable defaults. This routine returns NULL if it
322 fails, and an error message is logged. The server
323 is not registered with the rpcbind(1M) service.
324 svc_tp_create() svc_tp_create() creates a server handle for the
327 network specified by netconf, and registers itself
328 with the rpcbind service. dispatch is called when
329 there is a remote procedure call for the given
330 prognum and versnum; this requires calling
331 svc_run(). svc_tp_create() returns the service
332 handle if it succeeds, otherwise a NULL is
333 returned and an error message is logged.
334 svc_vc_create() This routine creates a connection-oriented RPC
337 service and returns a pointer to it. This routine
338 returns NULL if it fails, and an error message is
339 logged. The users may specify the size of the send
340 and receive buffers with the parameters sendsz and
341 recvsz; values of 0 choose suitable defaults. The
342 file descriptor fildes should be open and bound.
343 The server is not registered with the rpcbind(1M)
344 service.
345 svc_door_create() This routine creates an RPC server handle over
348 doors and returns a pointer to it. Doors is a
349 transport mechanism that facilitates fast data
350 transfer between processes on the same machine.
351 for the given program The user may set the size of
352 the send buffer with the parameter sendsz. If
353 sendsz is 0, the corresponding default buffer size
354 is 16 Kbyte. If successful, the svc_door_create()
355 routine returns the service handle. Otherwise it
356 returns NULL and sets a value for rpc_createerr.
357 The server is not registered with rpcbind(1M). The
358 SVCSET_CONNMAXREC and SVCGET_CONNMAXREC svc_con‐
359 trol() requests can be used to set and change the
360 maximum allowed request size for the doors trans‐
361 port.
362
365 See attributes(5) for descriptions of the following attributes:
366 ┌─────────────────────────────┬─────────────────────────────┐
371 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
372 ├─────────────────────────────┼─────────────────────────────┤
373 │Architecture │All │
374 ├─────────────────────────────┼─────────────────────────────┤
375 │Availability │SUNWcsl (32-bit) │
376 ├─────────────────────────────┼─────────────────────────────┤
377 │ │SUNWcslx (64-bit) │
378 ├─────────────────────────────┼─────────────────────────────┤
379 │Interface Stability │Evolving │
380 ├─────────────────────────────┼─────────────────────────────┤
381 │MT-Level │MT-Safe │
382 └─────────────────────────────┴─────────────────────────────┘
383
385 rpcbind(1M), rpc(3NSL), rpc_clnt_create(3NSL), rpc_svc_calls(3NSL),
386 rpc_svc_err(3NSL), rpc_svc_reg(3NSL), attributes(5)
387SunOS 5.11 22 Mar 2005 rpc_svc_create(3NSL)