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.12 2011/05/17 03:35:39 enami Exp $
13 .Nm clnt_create_vers ,
16 .Nm clnt_pcreateerror ,
18 .Nm clnt_spcreateerror ,
23 .Nd "library routines for dealing with creation and manipulation of CLIENT handles"
29 .Fn clnt_control "CLIENT *clnt" "const u_int req" "char *info"
31 .Fn clnt_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype"
33 .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" "char *nettype"
35 .Fn clnt_destroy "CLIENT * clnt"
37 .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"
39 .Fn clnt_pcreateerror "const char *s"
41 .Fn clnt_spcreateerror "const char *s"
43 .Fn clnt_raw_create "const rpcprog_t prognum" "const rpcvers_t versnum"
45 .Fn clnt_tli_create "const int fildes" "const struct netconfig *netconf" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz"
47 .Fn clnt_tp_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf"
49 .Fn clnt_vc_create "const int fildes" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz"
51 RPC library routines allow C language programs to make procedure
52 calls on other machines across the network.
55 handle is created and then the client calls a procedure to send a
56 request to the server.
57 On receipt of the request, the server calls a dispatch routine
58 to perform the requested service, and then sends a reply.
60 .Bl -tag -width YYYYYYY
62 A function macro to change or retrieve various information
63 about a client object.
65 indicates the type of operation, and
67 is a pointer to the information.
68 For both connectionless and connection-oriented transports,
69 the supported values of
71 and their argument types and what they do are:
72 .Bl -column "CLSET_FD_NCLOSE" "struct timeval *" "set total timeout"
73 .It Dv CLSET_TIMEOUT Ta "struct timeval *" Ta "set total timeout"
74 .It Dv CLGET_TIMEOUT Ta "struct timeval *" Ta "get total timeout"
78 if you set the timeout using
80 the timeout argument passed by
82 is ignored in all subsequent calls.
85 If you set the timeout value to 0
87 immediately returns an error
89 Set the timeout parameter to 0 for batching calls.
90 .Bl -column CLSET_FD_NCLOSE "struct timeval *" "do not close fd on destroy"
91 .It Dv CLGET_SVC_ADDR Ta "struct netbuf *" Ta "get servers address"
92 .It Dv CLGET_FD Ta "int *" Ta "get fd from handle"
93 .It Dv CLSET_FD_CLOSE Ta "void" Ta "close fd on destroy"
94 .It Dv CLSET_FD_NCLOSE Ta void Ta "don't close fd on destroy"
95 .It Dv CLGET_VERS Ta "unsigned long *" Ta "get RPC program version"
96 .It Dv CLSET_VERS Ta "unsigned long *" Ta "set RPC program version"
97 .It Dv CLGET_XID Ta "unsigned long *" Ta "get XID of previous call"
98 .It Dv CLSET_XID Ta "unsigned long *" Ta "set XID of next call"
101 The following operations are valid for connectionless transports only:
102 .Bl -column CLSET_RETRY_TIMEOUT "struct timeval *" "set total timeout"
103 .It Dv CLSET_RETRY_TIMEOUT Ta "struct timeval *" Ta "set the retry timeout"
104 .It Dv CLGET_RETRY_TIMEOUT Ta "struct timeval *" Ta "get the retry timeout"
107 The retry timeout is the time that RPC
108 waits for the server to reply before retransmitting the request.
117 Generic client creation routine for program
122 identifies the name of the remote host where the server
125 indicates the class of transport protocol to use.
126 The transports are tried in left to right order in
128 environment variable or in top to bottom order in
129 the netconfig database.
131 tries all the transports of the
133 class available from the
135 environment variable and the netconfig database,
136 and chooses the first successful one.
137 A default timeout is set and can be modified using
143 .Fn clnt_pcreateerror
144 routine can be used to print the reason for failure.
148 returns a valid client handle even
149 if the particular version number supplied to
151 is not registered with the
154 This mismatch will be discovered by a
157 .Xr rpc_clnt_calls 3 ) .
159 .It Fn clnt_create_vers
160 Generic client creation routine which is similar to
162 but which also checks for the
163 version availability.
165 identifies the name of the remote host where the server
168 indicates the class transport protocols to be used.
169 If the routine is successful it returns a client handle created for
170 the highest version between
174 that is supported by the server.
176 is set to this value.
177 That is, after a successful return
183 If no version between
187 is supported by the server then the routine fails and returns
189 A default timeout is set and can be modified using
195 .Fn clnt_pcreateerror
196 routine can be used to print the reason for failure.
199 returns a valid client handle even
200 if the particular version number supplied to
202 is not registered with the
205 This mismatch will be discovered by a
208 .Xr rpc_clnt_calls 3 ) .
211 does this for you and returns a valid handle
212 only if a version within
213 the range supplied is supported by the server.
216 A function macro that destroys the client's RPC handle.
217 Destruction usually involves deallocation
218 of private data structures, including
223 is undefined after calling
225 If the RPC library opened the associated file descriptor, or
229 the file descriptor will be closed.
230 The caller should call
231 .Fn auth_destroy "clnt-\*[Gt]cl_auth"
234 to destroy the associated
237 .Xr rpc_clnt_auth 3 ) .
239 .It Fn clnt_dg_create
240 This routine creates an RPC client for the remote program
244 the client uses a connectionless transport.
245 The remote program is located at address
249 is an open and bound file descriptor.
250 This routine will resend the call message in intervals of
251 15 seconds until a response is received or until the
253 The total time for the call to time out is specified by
258 .Xr rpc_clnt_calls 3 ) .
259 The retry time out and the total time out periods can
262 The user may set the size of the send and receive
263 buffers with the parameters
267 values of 0 choose suitable defaults.
272 .It Fn clnt_pcreateerror
273 Print a message to standard error indicating
274 why a client RPC handle could not be created.
275 The message is prepended with the string
277 and a colon, and appended with a newline.
279 .It Fn clnt_spcreateerror
281 .Fn clnt_pcreateerror ,
282 except that it returns a string
283 instead of printing to the standard error.
284 A newline is not appended to the message in this case.
286 returns a pointer to a buffer that is overwritten
289 .It Fn clnt_raw_create
290 This routine creates an RPC
291 client handle for the remote program
295 The transport used to pass messages to the service is
296 a buffer within the process's address space,
297 so the corresponding RPC
298 server should live in the same address space;
302 .Xr rpc_svc_create 3 ) .
303 This allows simulation of RPC and measurement of
304 RPC overheads, such as round trip times,
305 without any kernel or networking interference.
310 should be called after
313 .It Fn clnt_tli_create
314 This routine creates an RPC
315 client handle for the remote program
319 The remote program is located at address
325 and it is connection-oriented, it is assumed that the file descriptor
327 For connectionless transports, if
334 is a file descriptor which may be open, bound and connected.
337 it opens a file descriptor on the transport specified by
352 is unbound, then it will attempt to bind the descriptor.
353 The user may specify the size of the buffers with the parameters
357 values of 0 choose suitable defaults.
358 Depending upon the type of the transport (connection-oriented
361 calls appropriate client creation routines.
366 .Fn clnt_pcreateerror
367 routine can be used to print the reason for failure.
371 is not consulted for the address of the remote
374 .It Fn clnt_tp_create
379 tries only one transport specified through
382 creates a client handle for the program
386 and for the transport specified by
388 Default options are set,
389 which can be changed using
392 The remote rpcbind service on the host
394 is consulted for the address of the remote service.
399 .Fn clnt_pcreateerror
400 routine can be used to print the reason for failure.
402 .It Fn clnt_vc_create
403 This routine creates an RPC
404 client for the remote program
408 the client uses a connection-oriented transport.
409 The remote program is located at address
413 is an open and bound file descriptor.
414 The user may specify the size of the send and receive buffers
419 values of 0 choose suitable defaults.
427 and should point to the actual address of the remote program.
429 does not consult the remote rpcbind service for this information.
431 .It struct rpc_createerr rpc_createerr;
432 A global variable whose value is set by any RPC
433 client handle creation routine
435 It is used by the routine
436 .Fn clnt_pcreateerror
437 to print the reason for the failure.
441 .Xr rpc_clnt_auth 3 ,
442 .Xr rpc_clnt_calls 3 ,