1 .\" @(#)rpc_clnt_create.3n 1.36 93/08/31 SMI; from SVr4
2 .\" Copyright 1989 AT&T
3 .\" @(#)rpc_clnt_create 1.5 89/07/24 SMI;
4 .\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
5 .\" $NetBSD: rpc_clnt_create.3,v 1.2 2000/06/20 00:53:08 fvdl Exp $
6 .\" $FreeBSD: src/lib/libc/rpc/rpc_clnt_create.3,v 1.15 2006/09/17 21:27:34 ru Exp $
14 .Nm clnt_create_timed ,
15 .Nm clnt_create_vers ,
16 .Nm clnt_create_vers_timed ,
19 .Nm clnt_pcreateerror ,
21 .Nm clnt_spcreateerror ,
24 .Nm clnt_tp_create_timed ,
27 .Nd "library routines for dealing with creation and manipulation of"
35 .Fn clnt_control "CLIENT *clnt" "const u_int req" "char *info"
37 .Fn clnt_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype"
39 .Fn clnt_create_timed "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype" "const struct timeval *timeout"
41 .Fn clnt_create_vers "const char * host" "const rpcprog_t prognum" "rpcvers_t *vers_outp" "const rpcvers_t vers_low" "const rpcvers_t vers_high" "const char *nettype"
43 .Fn clnt_create_vers_timed "const char * host" "const rpcprog_t prognum" "rpcvers_t *vers_outp" "const rpcvers_t vers_low" "const rpcvers_t vers_high" "const char *nettype" "const struct timeval *timeout"
45 .Fn clnt_destroy "CLIENT *clnt"
47 .Fn clnt_dg_create "const int fildes" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz"
49 .Fn clnt_pcreateerror "const char *s"
51 .Fn clnt_spcreateerror "const char *s"
53 .Fn clnt_raw_create "const rpcprog_t prognum" "const rpcvers_t versnum"
55 .Fn clnt_tli_create "const int fildes" "const struct netconfig *netconf" "struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz"
57 .Fn clnt_tp_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf"
59 .Fn clnt_tp_create_timed "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "const struct timeval *timeout"
61 .Fn clnt_vc_create "const int fildes" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "u_int sendsz" "u_int recvsz"
63 RPC library routines allow C language programs to make procedure
64 calls on other machines across the network.
67 handle is created and then the client calls a procedure to send a
68 request to the server.
69 On receipt of the request, the server calls a dispatch routine
70 to perform the requested service, and then sends a reply.
72 .Bl -tag -width YYYYYYY
74 A function macro to change or retrieve various information
75 about a client object.
79 indicates the type of operation, and
81 is a pointer to the information.
82 For both connectionless and connection-oriented transports,
83 the supported values of
85 and their argument types and what they do are:
86 .Bl -column "CLSET_FD_NCLOSE" "struct timeval *" "set total timeout"
87 .It Dv CLSET_TIMEOUT Ta "struct timeval *" Ta "set total timeout"
88 .It Dv CLGET_TIMEOUT Ta "struct timeval *" Ta "get total timeout"
92 if you set the timeout using
94 the timeout argument passed by
96 is ignored in all subsequent calls.
99 If you set the timeout value to 0,
101 immediately returns an error
102 .Pq Dv RPC_TIMEDOUT .
103 Set the timeout argument to 0 for batching calls.
104 .Bl -column CLSET_FD_NCLOSE "struct timeval *"
105 .It Dv CLGET_SVC_ADDR Ta "struct netbuf *" Ta "get servers address"
106 .It Dv CLGET_FD Ta "int *" Ta "get fd from handle"
107 .It Dv CLSET_FD_CLOSE Ta "void" Ta "close fd on destroy"
108 .It Dv CLSET_FD_NCLOSE Ta void Ta "do not close fd on destroy"
109 .It Dv CLGET_VERS Ta "u_int32_t *" Ta "get RPC program version"
110 .It Dv CLSET_VERS Ta "u_int32_t *" Ta "set RPC program version"
111 .It Dv CLGET_XID Ta "u_int32_t *" Ta "get XID of previous call"
112 .It Dv CLSET_XID Ta "u_int32_t *" Ta "set XID of next call"
115 The following operations are valid for connectionless transports only:
116 .Bl -column CLSET_RETRY_TIMEOUT "struct timeval *" "set total timeout"
117 .It Dv CLSET_RETRY_TIMEOUT Ta "struct timeval *" Ta "set the retry timeout"
118 .It Dv CLGET_RETRY_TIMEOUT Ta "struct timeval *" Ta "get the retry timeout"
119 .It Dv CLSET_CONNECT Ta Vt "int *" Ta use Xr connect 2
122 The retry timeout is the time that RPC
123 waits for the server to reply before retransmitting the request.
133 Generic client creation routine for program
140 identifies the name of the remote host where the server
145 indicates the class of transport protocol to use.
146 The transports are tried in left to right order in
148 environment variable or in top to bottom order in
149 the netconfig database.
153 tries all the transports of the
155 class available from the
157 environment variable and the netconfig database,
158 and chooses the first successful one.
159 A default timeout is set and can be modified using
165 .Fn clnt_pcreateerror
166 routine can be used to print the reason for failure.
170 returns a valid client handle even
171 if the particular version number supplied to
173 is not registered with the
176 This mismatch will be discovered by a
179 .Xr rpc_clnt_calls 3 ) .
180 .It Fn clnt_create_timed
181 Generic client creation routine which is similar to
183 but which also has the additional argument
185 that specifies the maximum amount of time allowed for
186 each transport class tried.
187 In all other respects, the
188 .Fn clnt_create_timed
189 call behaves exactly like the
192 .It Fn clnt_create_vers
193 Generic client creation routine which is similar to
195 but which also checks for the
196 version availability.
200 identifies the name of the remote host where the server
205 indicates the class transport protocols to be used.
206 If the routine is successful it returns a client handle created for
207 the highest version between
211 that is supported by the server.
215 is set to this value.
216 That is, after a successful return
222 If no version between
226 is supported by the server then the routine fails and returns
228 A default timeout is set and can be modified using
234 .Fn clnt_pcreateerror
235 routine can be used to print the reason for failure.
238 returns a valid client handle even
239 if the particular version number supplied to
241 is not registered with the
244 This mismatch will be discovered by a
247 .Xr rpc_clnt_calls 3 ) .
250 does this for you and returns a valid handle
251 only if a version within
252 the range supplied is supported by the server.
253 .It Fn clnt_create_vers_timed
254 Generic client creation routine which is similar to
256 but which also has the additional argument
258 that specifies the maximum amount of time allowed for
259 each transport class tried.
260 In all other respects, the
261 .Fn clnt_create_vers_timed
262 call behaves exactly like the
266 A function macro that destroys the client's RPC handle.
267 Destruction usually involves deallocation
268 of private data structures, including
273 is undefined after calling
275 If the RPC library opened the associated file descriptor, or
279 the file descriptor will be closed.
280 The caller should call
281 .Fn auth_destroy "clnt->cl_auth"
284 to destroy the associated
287 .Xr rpc_clnt_auth 3 ) .
288 .It Fn clnt_dg_create
289 This routine creates an RPC client for the remote program
293 the client uses a connectionless transport.
294 The remote program is located at address
299 is an open and bound file descriptor.
300 This routine will resend the call message in intervals of
301 15 seconds until a response is received or until the
303 The total time for the call to time out is specified by
308 .Xr rpc_clnt_calls 3 ) .
309 The retry time out and the total time out periods can
312 The user may set the size of the send and receive
318 values of 0 choose suitable defaults.
322 .It Fn clnt_pcreateerror
323 Print a message to standard error indicating
324 why a client RPC handle could not be created.
325 The message is prepended with the string
327 and a colon, and appended with a newline.
328 .It Fn clnt_spcreateerror
330 .Fn clnt_pcreateerror ,
331 except that it returns a string
332 instead of printing to the standard error.
333 A newline is not appended to the message in this case.
335 returns a pointer to a buffer that is overwritten
337 .It Fn clnt_raw_create
338 This routine creates an RPC
339 client handle for the remote program
343 The transport used to pass messages to the service is
344 a buffer within the process's address space,
345 so the corresponding RPC
346 server should live in the same address space;
350 .Xr rpc_svc_create 3 ) .
351 This allows simulation of RPC and measurement of
352 RPC overheads, such as round trip times,
353 without any kernel or networking interference.
360 should be called after
362 .It Fn clnt_tli_create
363 This routine creates an RPC
364 client handle for the remote program
368 The remote program is located at address
374 and it is connection-oriented, it is assumed that the file descriptor
376 For connectionless transports, if
385 is a file descriptor which may be open, bound and connected.
388 it opens a file descriptor on the transport specified by
403 is unbound, then it will attempt to bind the descriptor.
404 The user may specify the size of the buffers with the
409 values of 0 choose suitable defaults.
410 Depending upon the type of the transport (connection-oriented
413 calls appropriate client creation routines.
418 .Fn clnt_pcreateerror
419 routine can be used to print the reason for failure.
423 is not consulted for the address of the remote
425 .It Fn clnt_tp_create
430 tries only one transport specified through
435 creates a client handle for the program
439 and for the transport specified by
441 Default options are set,
442 which can be changed using
445 The remote rpcbind service on the host
447 is consulted for the address of the remote service.
452 .Fn clnt_pcreateerror
453 routine can be used to print the reason for failure.
454 .It Fn clnt_tp_create_timed
458 .Fn clnt_tp_create_timed
459 has the extra argument
461 which specifies the maximum time allowed for
462 the creation attempt to succeed.
463 In all other respects, the
464 .Fn clnt_tp_create_timed
465 call behaves exactly like the
468 .It Fn clnt_vc_create
469 This routine creates an RPC
470 client for the remote program
474 the client uses a connection-oriented transport.
475 The remote program is located at address
480 is an open and bound file descriptor.
481 The user may specify the size of the send and receive buffers
487 values of 0 choose suitable defaults.
495 and should point to the actual address of the remote program.
499 does not consult the remote rpcbind service for this information.
501 .Vt "struct rpc_createerr" Va rpc_createerr ;
503 A global variable whose value is set by any RPC
504 client handle creation routine
506 It is used by the routine
507 .Fn clnt_pcreateerror
508 to print the reason for the failure.
512 .Xr rpc_clnt_auth 3 ,
513 .Xr rpc_clnt_calls 3 ,