1rpc_clnt_create(3NSL)Networking Services Library Functionsrpc_clnt_create(3NSL)
2
3
4

NAME

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

SYNOPSIS

14       #include <rpc/rpc.h>
15
16       bool_t clnt_control(CLIENT *clnt, const uint_t req, char *info);
17
18
19       CLIENT *clnt_create(const char *host, const rpcprog_t prognum,
20            const rpcvers_t versnum, const char *nettype);
21
22
23       CLIENT *clnt_create_timed(const char *host, const rpcprog_t prognum,
24            const rpcvers_t versnum, const nettype,
25            const struct timeval *timetout);
26
27
28       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
33
34       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
39
40       void clnt_destroy(CLIENT *clnt);
41
42
43       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
48
49       void clnt_pcreateerror(const char *s);
50
51
52       CLIENT *clnt_raw_create(const rpcprog_t prognum,
53            const rpcvers_t versnum);
54
55
56       char *clnt_spcreateerror(const char *s);
57
58
59       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
64
65       CLIENT *clnt_tp_create(const char *host,
66            const rpcprog_t prognum, const rpcvers_t versnum,
67            const struct netconfig *netconf);
68
69
70       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
74
75       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
80
81       struct rpc_createerr rpc_createerr
82
83
84       CLIENT *clnt_door_create(const rpcprog_t prognum,
85            const rpcvers_t versnum, const uint_t sendsz);
86
87

DESCRIPTION

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
95
96       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
102   Routines
103       See rpc(3NSL) for the definition of the CLIENT data structure.
104
105       clnt_control()
106
107           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
113             CLSET_TIMEOUT struct timeval * set total timeout
114             CLGET_TIMEOUT  struct timeval *    get total timeout
115
116           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
121             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
146           The  following  operations are valid for connection-oriented trans‐
147           ports only:
148
149             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
206           The following operations are valid  for  connectionless  transports
207           only:
208
209             CLSET_RETRY_TIMEOUT  struct timeval *    set the retry timeout
210             CLGET_RETRY_TIMEOUT  struct timeval *    get the retry timeout
211
212           The  retry  timeout  is  the  time that RPC waits for the server to
213           reply before retransmitting the request.
214
215           clnt_control() returns TRUE on success and FALSE on failure.
216
217
218       clnt_create()
219
220           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
226           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
233           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
238
239       clnt_create_timed()
240
241           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
247
248       clnt_create_vers()
249
250           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
264           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
271
272       clnt_create_vers_timed()
273
274           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
280
281       clnt_destroy()
282
283           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
290           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
294
295       clnt_dg_create()
296
297           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
310
311       clnt_pcreateerror()
312
313           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
317
318       clnt_raw_create()
319
320           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
330
331       clnt_spcreateerror()
332
333           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
337           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
341
342       clnt_tli_create()
343
344           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
363
364       clnt_tp_create()
365
366           Like clnt_create() except clnt_tp_create() tries only one transport
367           specified through netconf.
368
369           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
377
378       clnt_tp_create_timed()
379
380           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
386
387       clnt_vc_create()
388
389           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
397           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
401
402       rpc_createerr()
403
404           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
408           In  multithreaded applications, rpc_createerr becomes a macro which
409           enables each thread to have its own rpc_createerr.
410
411
412       clnt_door_create()
413
414           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
422

ATTRIBUTES

424       See attributes(5)  for descriptions of the following attributes:
425
426
427
428
429       ┌─────────────────────────────┬─────────────────────────────┐
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

SEE ALSO

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)
446
447
448
449SunOS 5.11                        23 Jul 2009            rpc_clnt_create(3NSL)
Impressum