1RPC_CLNT_CREATE(3) BSD Library Functions Manual RPC_CLNT_CREATE(3)
2
4 rpc_clnt_create, clnt_control, clnt_create, clnt_create_timed,
5 clnt_create_vers, clnt_create_vers_timed, clnt_destroy, clnt_dg_create,
6 clnt_pcreateerror, clnt_raw_create, clnt_spcreateerror, clnt_tli_create,
7 clnt_tp_create, clnt_tp_create_timed, clnt_vc_create, rpc_createerr —
8 library routines for dealing with creation and manipulation of CLIENT
9 handles
10
12 #include <rpc/rpc.h>
13 bool_t
15 clnt_control(CLIENT *clnt, const u_int req, char *info);
16 CLIENT *
18 clnt_create(const char * host, const rpcprog_t prognum,
19 const rpcvers_t versnum, const char *nettype);
20 CLIENT *
22 clnt_create_timed(const char * host, const rpcprog_t prognum,
23 const rpcvers_t versnum, const char *nettype,
24 const struct timeval *timeout);
25 CLIENT *
27 clnt_create_vers(const char * host, const rpcprog_t prognum,
28 rpcvers_t *vers_outp, const rpcvers_t vers_low,
29 const rpcvers_t vers_high, const char *nettype);
30 CLIENT *
32 clnt_create_vers_timed(const char * host, const rpcprog_t prognum,
33 rpcvers_t *vers_outp, const rpcvers_t vers_low,
34 const rpcvers_t vers_high, char *nettype,
35 const struct timeval *timeout);
36 void
38 clnt_destroy(CLIENT *clnt);
39 CLIENT *
41 clnt_dg_create(const int fildes, const struct netbuf *svcaddr,
42 const rpcprog_t prognum, const rpcvers_t versnum, const u_int sendsz,
43 const u_int recvsz);
44 void
46 clnt_pcreateerror(const char *s);
47 char *
49 clnt_spcreateerror(const char *s);
50 CLIENT *
52 clnt_raw_create(const rpcprog_t prognum, const rpcvers_t versnum);
53 CLIENT *
55 clnt_tli_create(const int fildes, const struct netconfig *netconf,
56 const struct netbuf *svcaddr, const rpcprog_t prognum,
57 const rpcvers_t versnum, const u_int sendsz, const u_int recvsz);
58 CLIENT *
60 clnt_tp_create(const char * host, const rpcprog_t prognum,
61 const rpcvers_t versnum, const struct netconfig *netconf);
62 CLIENT *
64 clnt_tp_create_timed(const char * host, const rpcprog_t prognum,
65 const rpcvers_t versnum, const struct netconfig *netconf,
66 const struct timeval *timeout);
67 CLIENT *
69 clnt_vc_create(const int fildes, const struct netbuf *svcaddr,
70 const rpcprog_t prognum, const rpcvers_t versnum, u_int sendsz,
71 u_int recvsz);
72
74 RPC library routines allow C language programs to make procedure calls on
75 other machines across the network. First a CLIENT handle is created and
76 then the client calls a procedure to send a request to the server. On
77 receipt of the request, the server calls a dispatch routine to perform
78 the requested service, and then sends a reply.
79
81 clnt_control()
82 A function macro to change or retrieve various information about
83 a client object. The req argument indicates the type of opera‐
84 tion, and info is a pointer to the information. For both con‐
85 nectionless and connection-oriented transports, the supported
86 values of req and their argument types and what they do are:
87 CLSET_TIMEOUT struct timeval * set total timeout
89 CLGET_TIMEOUT struct timeval * get total timeout
90 Note: if you set the timeout using clnt_control(), the timeout
92 argument passed by clnt_call() is ignored in all subsequent
93 calls.
94 Note: If you set the timeout value to 0, clnt_control() immedi‐
96 ately returns an error (RPC_TIMEDOUT). Set the timeout argument
97 to 0 for batching calls.
98 CLGET_SVC_ADDR struct netbuf * get servers address
100 CLGET_FD int * get fd from handle
101 CLSET_FD_CLOSE void close fd on destroy
102 CLSET_FD_NCLOSE void don't close fd on destroy
103 CLGET_VERS u_int32_t * get RPC program version
104 CLSET_VERS u_int32_t * set RPC program version
105 CLGET_XID u_int32_t * get XID of previous call
106 CLSET_XID u_int32_t * set XID of next call
107 The following operations are valid for connectionless transports
109 only:
110 CLSET_RETRY_TIMEOUT struct timeval * set the retry timeout
112 CLGET_RETRY_TIMEOUT struct timeval * get the retry timeout
113 CLSET_CONNECT int * use connect(2)
114 The retry timeout is the time that RPC waits for the server to
116 reply before retransmitting the request. The clnt_control()
117 function returns TRUE on success and FALSE on failure.
118 clnt_create()
120 Generic client creation routine for program prognum and version
121 versnum. The host argument identifies the name of the remote
122 host where the server is located. The nettype argument indi‐
123 cates the class of transport protocol to use. The transports
124 are tried in left to right order in NETPATH environment variable
125 or in top to bottom order in the netconfig database. The
126 clnt_create() function tries all the transports of the nettype
127 class available from the NETPATH environment variable and the
128 netconfig database, and chooses the first successful one. A
129 default timeout is set and can be modified using clnt_control().
130 This routine returns NULL if it fails. The clnt_pcreateerror()
131 routine can be used to print the reason for failure.
132 Note: clnt_create() returns a valid client handle even if the
134 particular version number supplied to clnt_create() is not reg‐
135 istered with the rpcbind(8) service. This mismatch will be dis‐
136 covered by a clnt_call() later (see rpc_clnt_calls(3)).
137 clnt_create_timed()
139 Generic client creation routine which is similar to
140 clnt_create() but which also has the additional argument timeout
141 that specifies the maximum amount of time allowed for each
142 transport class tried. In all other respects, the
143 clnt_create_timed() call behaves exactly like the clnt_create()
144 call.
145 clnt_create_vers()
147 Generic client creation routine which is similar to
148 clnt_create() but which also checks for the version availabil‐
149 ity. The host argument identifies the name of the remote host
150 where the server is located. The nettype argument indicates the
151 class transport protocols to be used. If the routine is suc‐
152 cessful it returns a client handle created for the highest ver‐
153 sion between vers_low and vers_high that is supported by the
154 server. The vers_outp argument is set to this value. That is,
155 after a successful return vers_low <= *vers_outp <= vers_high.
156 If no version between vers_low and vers_high is supported by the
157 server then the routine fails and returns NULL. A default time‐
158 out is set and can be modified using clnt_control(). This rou‐
159 tine returns NULL if it fails. The clnt_pcreateerror() routine
160 can be used to print the reason for failure. Note:
161 clnt_create() returns a valid client handle even if the particu‐
162 lar version number supplied to clnt_create() is not registered
163 with the rpcbind(8) service. This mismatch will be discovered
164 by a clnt_call() later (see rpc_clnt_calls(3)). However,
165 clnt_create_vers() does this for you and returns a valid handle
166 only if a version within the range supplied is supported by the
167 server.
168 clnt_create_vers_timed()
170 Generic client creation routine which is similar to
171 clnt_create_vers() but which also has the additional argument
172 timeout that specifies the maximum amount of time allowed for
173 each transport class tried. In all other respects, the
174 clnt_create_vers_timed() call behaves exactly like the
175 clnt_create_vers() call.
176 clnt_destroy()
178 A function macro that destroys the client's RPC handle.
179 Destruction usually involves deallocation of private data struc‐
180 tures, including clnt itself. Use of clnt is undefined after
181 calling clnt_destroy(). If the RPC library opened the associ‐
182 ated file descriptor, or CLSET_FD_CLOSE was set using
183 clnt_control(), the file descriptor will be closed. The caller
184 should call auth_destroy(clnt->cl_auth) (before calling
185 clnt_destroy()) to destroy the associated AUTH structure (see
186 rpc_clnt_auth(3)).
187 clnt_dg_create()
189 This routine creates an RPC client for the remote program
190 prognum and version versnum; the client uses a connectionless
191 transport. The remote program is located at address svcaddr.
192 The fildes argument is an open and bound file descriptor. This
193 routine will resend the call message in intervals of 15 seconds
194 until a response is received or until the call times out. The
195 total time for the call to time out is specified by clnt_call()
196 (see clnt_call() in rpc_clnt_calls(3)). The retry time out and
197 the total time out periods can be changed using clnt_control().
198 The user may set the size of the send and receive buffers with
199 the sendsz and recvsz arguments; values of 0 choose suitable
200 defaults. This routine returns NULL if it fails.
201 clnt_pcreateerror()
203 Print a message to standard error indicating why a client RPC
204 handle could not be created. The message is prepended with the
205 string s and a colon, and appended with a newline.
206 clnt_spcreateerror()
208 Like clnt_pcreateerror(), except that it returns a string
209 instead of printing to the standard error. A newline is not
210 appended to the message in this case. Warning: returns a
211 pointer to a buffer that is overwritten on each call.
212 clnt_raw_create()
214 This routine creates an RPC client handle for the remote program
215 prognum and version versnum. The transport used to pass mes‐
216 sages to the service is a buffer within the process's address
217 space, so the corresponding RPC server should live in the same
218 address space; (see svc_raw_create() in rpc_svc_create(3)).
219 This allows simulation of RPC and measurement of RPC overheads,
220 such as round trip times, without any kernel or networking
221 interference. This routine returns NULL if it fails. The
222 clnt_raw_create() function should be called after
223 svc_raw_create().
224 clnt_tli_create()
226 This routine creates an RPC client handle for the remote program
227 prognum and version versnum. The remote program is located at
228 address svcaddr. If svcaddr is NULL and it is connection-ori‐
229 ented, it is assumed that the file descriptor is connected. For
230 connectionless transports, if svcaddr is NULL, RPC_UNKNOWNADDR
231 error is set. The fildes argument is a file descriptor which
232 may be open, bound and connected. If it is RPC_ANYFD, it opens
233 a file descriptor on the transport specified by netconf. If
234 fildes is RPC_ANYFD and netconf is NULL, a RPC_UNKNOWNPROTO
235 error is set. If fildes is unbound, then it will attempt to
236 bind the descriptor. The user may specify the size of the buf‐
237 fers with the sendsz and recvsz arguments; values of 0 choose
238 suitable defaults. Depending upon the type of the transport
239 (connection-oriented or connectionless), clnt_tli_create() calls
240 appropriate client creation routines. This routine returns NULL
241 if it fails. The clnt_pcreateerror() routine can be used to
242 print the reason for failure. The remote rpcbind service (see
243 rpcbind(8)) is not consulted for the address of the remote ser‐
244 vice.
245 clnt_tp_create()
247 Like clnt_create() except clnt_tp_create() tries only one trans‐
248 port specified through netconf. The clnt_tp_create() function
249 creates a client handle for the program prognum, the version
250 versnum, and for the transport specified by netconf. Default
251 options are set, which can be changed using clnt_control()
252 calls. The remote rpcbind service on the host host is consulted
253 for the address of the remote service. This routine returns
254 NULL if it fails. The clnt_pcreateerror() routine can be used
255 to print the reason for failure.
256 clnt_tp_create_timed()
258 Like clnt_tp_create() except clnt_tp_create_timed() has the
259 extra argument timeout which specifies the maximum time allowed
260 for the creation attempt to succeed. In all other respects, the
261 clnt_tp_create_timed() call behaves exactly like the
262 clnt_tp_create() call.
263 clnt_vc_create()
265 This routine creates an RPC client for the remote program
266 prognum and version versnum; the client uses a connection-ori‐
267 ented transport. The remote program is located at address
268 svcaddr. The fildes argument is an open and bound file descrip‐
269 tor. The user may specify the size of the send and receive buf‐
270 fers with the sendsz and recvsz arguments; values of 0 choose
271 suitable defaults. This routine returns NULL if it fails. The
272 address svcaddr should not be NULL and should point to the
273 actual address of the remote program. The clnt_vc_create()
274 function does not consult the remote rpcbind service for this
275 information.
276 struct rpc_createerr rpc_createerr;
278 A global variable whose value is set by any RPC client handle
279 creation routine that fails. It is used by the routine
280 clnt_pcreateerror() to print the reason for the failure.
281
283 These functions are part of libtirpc.
284
286 rpc(3), rpc_clnt_auth(3), rpc_clnt_calls(3), rpcbind(8)
287BSD May 7, 1993 BSD