1rpc_clnt_create(3NSL)Networking Services Library Functionsrpc_clnt_create(3NSL)
2
6 rpc_clnt_create, clnt_control, clnt_create, clnt_create_timed,
7 clnt_create_vers, clnt_create_vers_timed, clnt_destroy, clnt_dg_create,
8 clnt_pcreateerror, clnt_raw_create, clnt_spcreateerror, clnt_tli_cre‐
9 ate, clnt_tp_create, clnt_tp_create_timed, clnt_vc_create, rpc_cre‐
10 ateerr, clnt_door_create - library routines for dealing with creation
11 and manipulation of CLIENT handles
12
14 #include <rpc/rpc.h>
15 bool_t clnt_control(CLIENT *clnt, const uint_t req, char *info);
17 CLIENT *clnt_create(const char *host, const rpcprog_t prognum,
20 const rpcvers_t versnum, const char *nettype);
21 CLIENT *clnt_create_timed(const char *host, const rpcprog_t prognum,
24 const rpcvers_t versnum, const nettype,
25 const struct timeval *timetout);
26 CLIENT *clnt_create_vers (const char *host,
29 const rpcprog_t prognum, rpcvers_t *vers_outp,
30 const rpcvers_t vers_low, const rpcvers_t vers_high,
31 const char *nettype);
32 CLIENT *clnt_create_vers_timed(const char *host,
35 const rpcprog_t prognum, rpcvers_t *vers_outp,
36 const rpcvers_t vers_low, const rpcvers_t vers_high,
37 char *nettype, const struct timeval *timeout);
38 void clnt_destroy(CLIENT *clnt);
41 CLIENT *clnt_dg_create(const int fildes,
44 const struct netbuf *svcaddr, const rpcprog_t prognum,
45 const rpcvers_t versnum, const uint_t sendsz,
46 const uint_t recsz);
47 void clnt_pcreateerror(const char *s);
50 CLIENT *clnt_raw_create(const rpcprog_t prognum,
53 const rpcvers_t versnum);
54 char *clnt_spcreateerror(const char *s);
57 CLIENT *clnt_tli_create(const int fildes,
60 const struct netconfig *netconf, const struct netbuf *svcaddr,
61 const rpcprog_t prognum, const rpcvers_t versnum,
62 const uint_t sendsz, const uint_t recsz);
63 CLIENT *clnt_tp_create(const char *host,
66 const rpcprog_t prognum, const rpcvers_t versnum,
67 const struct netconfig *netconf);
68 CLIENT *clnt_tp_create_timed(const char *host,
71 const rpcprog_t prognum, const rpcvers_t versnum,
72 const struct netconfig *netconf, const struct timeval *timeout);
73 CLIENT *clnt_vc_create(const int fildes,
76 const struct netbuf *svcaddr, const rpcprog_t prognum,
77 const rpcvers_t versnum, const uint_t sendsz,
78 const uint_t recsz);
79 struct rpc_createerr rpc_createerr
82 CLIENT *clnt_door_create(const rpcprog_t prognum,
85 const rpcvers_t versnum, const uint_t sendsz);
86
89 RPC library routines allow C language programs to make procedure calls
90 on other machines across the network. First a CLIENT handle is created
91 and then the client calls a procedure to send a request to the server.
92 On receipt of the request, the server calls a dispatch routine to per‐
93 form the requested service, and then sends a reply.
94 These routines are MT-Safe. In the case of multithreaded applications,
97 the -mt option must be specified on the command line at compilation
98 time. When the -mt option is specified, rpc_createerr() becomes a macro
99 that enables each thread to have its own rpc_createerr(). See
100 threads(5).
101 Routines
103 See rpc(3NSL) for the definition of the CLIENT data structure.
104 clnt_control()
106 A function macro to change or retrieve various information about a
108 client object. req indicates the type of operation, and info is a
109 pointer to the information. For both connectionless and connection-
110 oriented transports, the supported values of req and their argument
111 types and what they do are:
112 CLSET_TIMEOUT struct timeval * set total timeout
114 CLGET_TIMEOUT struct timeval * get total timeout
115 If the timeout is set using clnt_control(), the timeout argument
117 passed by clnt_call() is ignored in all subsequent calls. If the
118 timeout value is set to 0, clnt_control() immediately returns
119 RPC_TIMEDOUT. Set the timeout parameter to 0 for batching calls.
120 CLGET_SERVER_ADDR struct netbuf * get server's address
122 CLGET_SVC_ADDR struct netbuf * get server's address
123 CLGET_FD int * get associated file descriptor
124 CLSET_FD_CLOSE void close the file descriptor when
125 destroying the client handle
126 (see clnt_destroy())
127 CLSET_FD_NCLOSE void do not close the file
128 descriptor when destroying the client handle
129 CLGET_VERS rpcvers_t get the RPC program's version
130 number associated with the
131 client handle
132 CLSET_VERS rpcvers_t set the RPC program's version
133 number associated with the
134 client handle. This assumes
135 that the RPC server for this
136 new version is still listening
137 at the address of the previous
138 version.
139 CLGET_XID uint32_t get the XID of the previous
140 remote procedure call
141 CLSET_XID uint32_t set the XID of the next
142 remote procedure call
143 CLGET_PROG rpcprog_t get program number
144 CLSET_PROG rpcprog_t set program number
145 The following operations are valid for connection-oriented trans‐
147 ports only:
148 CLSET_IO_MODE rpciomode_t* set the IO mode used
150 to send one-way requests. The argument for this operation
151 can be either:
152 - RPC_CL_BLOCKING all sending operations block
153 until the underlying transport protocol has
154 accepted requests. If you specify this argument
155 you cannot use flush and getting and setting buffer
156 size is meaningless.
157 - RPC_CL_NONBLOCKING sending operations do not
158 block and return as soon as requests enter the buffer.
159 You can now use non-blocking I/O. The requests in the
160 buffer are pending. The requests are sent to
161 the server as soon as a two-way request is sent
162 or a flush is done. You are responsible for flushing
163 the buffer. When you choose RPC_CL_NONBLOCKING argument
164 you have a choice of flush modes as specified by
165 CLSET_FLUSH_MODE.
166 CLGET_IO_MODE rpciomode_t* get the current IO mode
167 CLSET_FLUSH_MODE rpcflushmode_t* set the flush mode.
168 The flush mode can only be used in non-blocking I/O mode.
169 The argument can be either of the following:
170 - RPC_CL_BESTEFFORT_FLUSH: All flushes send requests
171 in the buffer until the transport end-point blocks.
172 If the transport connection is congested, the call
173 returns directly.
174 - RPC_CL_BLOCKING_FLUSH: Flush blocks until the
175 underlying transport protocol accepts all pending
176 requests into the queue.
177 CLGET_FLUSH_MODE rpcflushmode_t* get the current flush mode.
178 CLFLUSH rpcflushmode_t flush the pending requests.
179 This command can only be used in non-blocking I/O mode.
180 The flush policy depends on which of the following
181 parameters is specified:
182 - RPC_CL_DEFAULT_FLUSH, or NULL: The flush is done
183 according to the current flush mode policy
184 (see CLSET_FLUSH_MODE option).
185 - RPC_CL_BESTEFFORT_FLUSH: The flush tries
186 to send pending requests without blocking; the call
187 returns directly. If the transport connection is
188 congested, this call could return without the request
189 being sent.
190 - RPC_CL_BLOCKING_FLUSH: The flush sends all pending
191 requests. This call will block until all the requests
192 have been accepted by the transport layer.
193 CLSET_CONNMAXREC_SIZE int* set the buffer size.
194 It is not possible to dynamically
195 resize the buffer if it contains data.
196 The default size of the buffer is 16 kilobytes.
197 CLGET_CONNMAXREC_SIZE int* get the current size of the
198 buffer
199 CLGET_CURRENT_REC_SIZE int* get the size of
200 the pending requests stored in the buffer. Use of this
201 command is only recommended when you are in non-blocking
202 I/O mode. The current size of the buffer is always zero
203 when the handle is in blocking mode as the buffer is not
204 used in this mode.
205 The following operations are valid for connectionless transports
207 only:
208 CLSET_RETRY_TIMEOUT struct timeval * set the retry timeout
210 CLGET_RETRY_TIMEOUT struct timeval * get the retry timeout
211 The retry timeout is the time that RPC waits for the server to
213 reply before retransmitting the request.
214 clnt_control() returns TRUE on success and FALSE on failure.
216 clnt_create()
219 Generic client creation routine for program prognum and version
221 versnum. host identifies the name of the remote host where the
222 server is located. nettype indicates the class of transport proto‐
223 col to use. The transports are tried in left to right order in NET‐
224 PATH variable or in top to bottom order in the netconfig database.
225 clnt_create() tries all the transports of the nettype class avail‐
227 able from the NETPATH environment variable and the netconfig data‐
228 base, and chooses the first successful one. A default timeout is
229 set and can be modified using clnt_control(). This routine returns
230 NULL if it fails. The clnt_pcreateerror() routine can be used to
231 print the reason for failure.
232 Note that clnt_create() returns a valid client handle even if the
234 particular version number supplied to clnt_create() is not regis‐
235 tered with the rpcbind service. This mismatch will be discovered by
236 a clnt_call later (see rpc_clnt_calls(3NSL)).
237 clnt_create_timed()
240 Generic client creation routine which is similar to clnt_create()
242 but which also has the additional parameter timeout that specifies
243 the maximum amount of time allowed for each transport class tried.
244 In all other respects, the clnt_create_timed() call behaves exactly
245 like the clnt_create() call.
246 clnt_create_vers()
249 Generic client creation routine which is similar to clnt_create()
251 but which also checks for the version availability. host identifies
252 the name of the remote host where the server is located. nettype
253 indicates the class transport protocols to be used. If the routine
254 is successful it returns a client handle created for the highest
255 version between vers_low and vers_high that is supported by the
256 server. vers_outp is set to this value. That is, after a successful
257 return vers_low <= *vers_outp <= vers_high. If no version between
258 vers_low and vers_high is supported by the server then the routine
259 fails and returns NULL. A default timeout is set and can be modi‐
260 fied using clnt_control(). This routine returns NULL if it fails.
261 The clnt_pcreateerror() routine can be used to print the reason for
262 failure.
263 Note: clnt_create() returns a valid client handle even if the par‐
265 ticular version number supplied to clnt_create() is not registered
266 with the rpcbind service. This mismatch will be discovered by a
267 clnt_call later (see rpc_clnt_calls(3NSL)). However, clnt_cre‐
268 ate_vers() does this for you and returns a valid handle only if a
269 version within the range supplied is supported by the server.
270 clnt_create_vers_timed()
273 Generic client creation routine similar to clnt_create_vers() but
275 with the additional parameter timeout, which specifies the maximum
276 amount of time allowed for each transport class tried. In all
277 other respects, the clnt_create_vers_timed() call behaves exactly
278 like the clnt_create_vers() call.
279 clnt_destroy()
282 A function macro that destroys the client's RPC handle. Destruction
284 usually involves deallocation of private data structures, including
285 clnt itself. Use of clnt is undefined after calling clnt_destroy().
286 If the RPC library opened the associated file descriptor, or
287 CLSET_FD_CLOSE was set using clnt_control(), the file descriptor
288 will be closed.
289 The caller should call auth_destroy(clnt->cl_auth) (before calling
291 clnt_destroy()) to destroy the associated AUTH structure (see
292 rpc_clnt_auth(3NSL)).
293 clnt_dg_create()
296 This routine creates an RPC client for the remote program prognum
298 and version versnum; the client uses a connectionless transport.
299 The remote program is located at address svcaddr. The parameter
300 fildes is an open and bound file descriptor. This routine will
301 resend the call message in intervals of 15 seconds until a response
302 is received or until the call times out. The total time for the
303 call to time out is specified by clnt_call() (see clnt_call() in
304 rpc_clnt_calls(3NSL)). The retry time out and the total time out
305 periods can be changed using clnt_control(). The user may set the
306 size of the send and receive buffers with the parameters sendsz and
307 recvsz; values of 0 choose suitable defaults. This routine returns
308 NULL if it fails.
309 clnt_pcreateerror()
312 Print a message to standard error indicating why a client RPC han‐
314 dle could not be created. The message is prepended with the string
315 s and a colon, and appended with a newline.
316 clnt_raw_create()
319 This routine creates an RPC client handle for the remote program
321 prognum and version versnum. The transport used to pass messages to
322 the service is a buffer within the process's address space, so the
323 corresponding RPC server should live in the same address space;
324 (see svc_raw_create() in rpc_svc_create(3NSL)). This allows simula‐
325 tion of RPC and measurement of RPC overheads, such as round trip
326 times, without any kernel or networking interference. This routine
327 returns NULL if it fails. clnt_raw_create() should be called after
328 svc_raw_create().
329 clnt_spcreateerror()
332 Like clnt_pcreateerror(), except that it returns a string instead
334 of printing to the standard error. A newline is not appended to the
335 message in this case.
336 Warning: returns a pointer to a buffer that is overwritten on each
338 call. In multithread applications, this buffer is implemented as
339 thread-specific data.
340 clnt_tli_create()
343 This routine creates an RPC client handle for the remote program
345 prognum and version versnum. The remote program is located at
346 address svcaddr. If svcaddr is NULL and it is connection-oriented,
347 it is assumed that the file descriptor is connected. For connec‐
348 tionless transports, if svcaddr is NULL, RPC_UNKNOWNADDR error is
349 set. fildes is a file descriptor which may be open, bound and con‐
350 nected. If it is RPC_ANYFD, it opens a file descriptor on the
351 transport specified by netconf. If fildes is RPC_ANYFD and netconf
352 is NULL, a RPC_UNKNOWNPROTO error is set. If fildes is unbound,
353 then it will attempt to bind the descriptor. The user may specify
354 the size of the buffers with the parameters sendsz and recvsz; val‐
355 ues of 0 choose suitable defaults. Depending upon the type of the
356 transport (connection-oriented or connectionless), clnt_tli_cre‐
357 ate() calls appropriate client creation routines. This routine
358 returns NULL if it fails. The clnt_pcreateerror() routine can be
359 used to print the reason for failure. The remote rpcbind service
360 (see rpcbind(1M)) is not consulted for the address of the remote
361 service.
362 clnt_tp_create()
365 Like clnt_create() except clnt_tp_create() tries only one transport
367 specified through netconf.
368 clnt_tp_create() creates a client handle for the program prognum,
370 the version versnum, and for the transport specified by netconf.
371 Default options are set, which can be changed using clnt_control()
372 calls. The remote rpcbind service on the host host is consulted for
373 the address of the remote service. This routine returns NULL if it
374 fails. The clnt_pcreateerror() routine can be used to print the
375 reason for failure.
376 clnt_tp_create_timed()
379 Like clnt_tp_create() except clnt_tp_create_timed() has the extra
381 parameter timeout which specifies the maximum time allowed for the
382 creation attempt to succeed. In all other respects, the
383 clnt_tp_create_timed() call behaves exactly like the clnt_tp_cre‐
384 ate() call.
385 clnt_vc_create()
388 This routine creates an RPC client for the remote program prognum
390 and version versnum; the client uses a connection-oriented trans‐
391 port. The remote program is located at address svcaddr. The parame‐
392 ter fildes is an open and bound file descriptor. The user may spec‐
393 ify the size of the send and receive buffers with the parameters
394 sendsz and recvsz; values of 0 choose suitable defaults. This rou‐
395 tine returns NULL if it fails.
396 The address svcaddr should not be NULL and should point to the
398 actual address of the remote program. clnt_vc_create() does not
399 consult the remote rpcbind service for this information.
400 rpc_createerr()
403 A global variable whose value is set by any RPC client handle cre‐
405 ation routine that fails. It is used by the routine clnt_pcre‐
406 ateerror() to print the reason for the failure.
407 In multithreaded applications, rpc_createerr becomes a macro which
409 enables each thread to have its own rpc_createerr.
410 clnt_door_create()
413 This routine creates an RPC client handle over doors for the given
415 program prognum and version versnum. Doors is a transport mechanism
416 that facilitates fast data transfer between processes on the same
417 machine. The user may set the size of the send buffer with the
418 parameter sendsz. If sendsz is 0, the corresponding default buffer
419 size is 16 Kbyte. The clnt_door_create() routine returns NULL if it
420 fails and sets a value for rpc_createerr.
421
424 See attributes(5) for descriptions of the following attributes:
425 ┌─────────────────────────────┬─────────────────────────────┐
430 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
431 ├─────────────────────────────┼─────────────────────────────┤
432 │Architecture │All │
433 ├─────────────────────────────┼─────────────────────────────┤
434 │Availability │SUNWcsl (32-bit) │
435 ├─────────────────────────────┼─────────────────────────────┤
436 │ │SUNWcslx (64-bit) │
437 ├─────────────────────────────┼─────────────────────────────┤
438 │Interface Stability │Committed │
439 ├─────────────────────────────┼─────────────────────────────┤
440 │MT-Level │MT-Safe │
441 └─────────────────────────────┴─────────────────────────────┘
442
444 rpcbind(1M), rpc(3NSL), rpc_clnt_auth(3NSL), rpc_clnt_calls(3NSL),
445 rpc_svc_create(3NSL), svc_raw_create(3NSL), threads(5), attributes(5)
446SunOS 5.11 23 Jul 2009 rpc_clnt_create(3NSL)