1rpc_clnt_calls(3NSL) Networking Services Library Functionsrpc_clnt_calls(3NSL)
2
6 rpc_clnt_calls, clnt_call, clnt_send, clnt_freeres, clnt_geterr,
7 clnt_perrno, clnt_perror, clnt_sperrno, clnt_sperror, rpc_broadcast,
8 rpc_broadcast_exp, rpc_call - library routines for client side calls
9
11 #include <rpc/rpc.h>
12 enum clnt_stat clnt_call(CLIENT *clnt, const rpcproc_t procnum,
14 const xdrproc_t inproc, const caddr_t in, const xdrproc_t outproc,
15 caddr_t out, const struct timeval tout);
16 enum clnt_stat clnt_send (CLIENT *clnt, const u_long
19 procnum, const xdrproc_t proc, const caddr_t in);
20 bool_t clnt_freeres(CLIENT *clnt, const xdrproc_t outproc,
23 caddr_t out);
24 void clnt_geterr(const CLIENT *clnt, struct rpc_err *errp);
27 void clnt_perrno(const enum clnt_stat stat);
30 void clnt_perror(const CLIENT *clnt, const char *s);
33 char *clnt_sperrno(const enum clnt_stat stat);
36 char *clnt_sperror(const CLIENT *clnt, const char *s);
39 enum clnt_stat rpc_broadcast(const rpcprog_t prognum,
42 const rpcvers_t versnum, const rpcproc_t procnum,
43 const xdrproc_tinproc, const caddr_t in,
44 const xdrproc_t outproc, caddr_t out,
45 const resultproc_t eachresult, const char *nettype);
46 enum clnt_stat rpc_broadcast_exp(const rpcprog_t prognum,
49 const rpcvers_t versnum,const rpcproc_t procnum,
50 const xdrproc_txargs, caddr_t argsp, const xdrproc_txresults,
51 caddr_t resultsp, const resultproc_t eachresult, const int inittime,
52 const int waittime, const char *nettype);
53 enum clnt_stat rpc_call(const char *host, const rpcprog_t prognum,
56 const rpcvers_t versnum, const rpcproc_t procnum, const xdrproc_t inproc,
57 const char *in, const xdrproc_t outproc, char *out, const char *nettype);
58
61 RPC library routines allow C language programs to make procedure calls
62 on other machines across the network. First, the client calls a proce‐
63 dure to send a request to the server. Upon receipt of the request, the
64 server calls a dispatch routine to perform the requested service and
65 then sends back a reply.
66 The clnt_call(), rpc_call(), and rpc_broadcast() routines handle the
69 client side of the procedure call. The remaining routines deal with
70 error handling.
71 Some of the routines take a CLIENT handle as one of the parameters. A
74 CLIENT handle can be created by an RPC creation routine such as
75 clnt_create(). See rpc_clnt_create(3NSL).
76 These routines are safe for use in multithreaded applications. CLIENT
79 handles can be shared between threads; however, in this implementation
80 requests by different threads are serialized. In other words, the first
81 request will receive its results before the second request is sent.
82 Routines
84 See rpc(3NSL) for the definition of the CLIENT data structure.
85 clnt_call() A function macro that calls the remote procedure
87 procnum associated with the client handle, clnt,
88 which is obtained with an RPC client creation
89 routine such as clnt_create(). See rpc_clnt_cre‐
90 ate(3NSL). The parameter inproc is the XDR
91 function used to encode the procedure's parame‐
92 ters, and outproc is the XDR function used to
93 decode the procedure's results. in is the
94 address of the procedure's argument(s), and out
95 is the address of where to place the result(s).
96 tout is the time allowed for results to be
97 returned, which is overridden by a time-out set
98 explicitly through clnt_control(). See
99 rpc_clnt_create(3NSL).
100 If the remote call succeeds, the status returned
102 is RPC_SUCCESS. Otherwise, an appropriate status
103 is returned.
104 clnt_send() Use the clnt_send() function to call a remote
107 asynchronous function.
108 The clnt_send() function calls the remote func‐
110 tion procnum() associated with the client han‐
111 dle, clnt, which is obtained with an RPC client
112 creation routine such as clnt_create(). See
113 rpc_clnt_create(3NSL). The parameter proc is the
114 XDR function used to encode the procedure's
115 parameters. The parameter in is the address of
116 the procedure's argument(s).
117 By default, the blocking I/O mode is used. See
119 the clnt_control(3NSL) man page for more infor‐
120 mation on I/O modes.
121 The clnt_send() function does not check if the
123 program version number supplied to clnt_create()
124 is registered with the rpcbind service. Use
125 clnt_create_vers() instead of clnt_create() to
126 check on incorrect version number registration.
127 clnt_create_vers() will return a valid handle to
128 the client only if a version within the range
129 supplied to clnt_create_vers() is supported by
130 the server.
131 RPC_SUCCESS is returned when a request is suc‐
133 cessfully delivered to the transport layer. This
134 does not mean that the request was received. If
135 an error is returned, use the clnt_getterr()
136 routine to find the failure status or the
137 clnt_perrno() routine to translate the failure
138 status into error messages.
139 clnt_freeres() A function macro that frees any data allocated
142 by the RPC/XDR system when it decoded the
143 results of an RPC call. The parameter out is
144 the address of the results, and outproc is the
145 XDR routine describing the results. This routine
146 returns 1 if the results were successfully
147 freed; otherwise it returns 0.
148 clnt_geterr() A function macro that copies the error structure
151 out of the client handle to the structure at
152 address errp.
153 clnt_perrno() Prints a message to standard error corresponding
156 to the condition indicated by stat. A newline is
157 appended. It is normally used after a procedure
158 call fails for a routine for which a client han‐
159 dle is not needed, for instance rpc_call()
160 clnt_perror() Prints a message to the standard error indicat‐
163 ing why an RPC call failed; clnt is the handle
164 used to do the call. The message is prepended
165 with string s and a colon. A newline is
166 appended. This routine is normally used after a
167 remote procedure call fails for a routine that
168 requires a client handle, for instance
169 clnt_call().
170 clnt_sperrno() Takes the same arguments as clnt_perrno(), but
173 instead of sending a message to the standard
174 error indicating why an RPC call failed, returns
175 a pointer to a string that contains the message.
176 clnt_sperrno() is normally used instead of
178 clnt_perrno() when the program does not have a
179 standard error, as a program running as a server
180 quite likely does not. clnt_sperrno() is also
181 used if the programmer does not want the message
182 to be output with printf(), or if a message for‐
183 mat different than that supported by clnt_per‐
184 rno() is to be used. See printf(3C). Unlike
185 clnt_sperror() and clnt_spcreaterror(),
186 clnt_sperrno() does not return a pointer to
187 static data. Therefore, the result is not over‐
188 written on each call. See rpc_clnt_create(3NSL).
189 clnt_sperror() Similar to clnt_perror(), except that like
192 clnt_sperrno(), it returns a string instead of
193 printing to standard error. However, clnt_sper‐
194 ror() does not append a newline at the end of
195 the message.
196 clnt_sperror() returns a pointer to a buffer
198 that is overwritten on each call. In multi‐
199 threaded applications, this buffer is imple‐
200 mented as thread-specific data.
201 rpc_broadcast() Similar to rpc_call(), except that the call mes‐
204 sage is broadcast to all the connectionless
205 transports specified by nettype. If nettype is
206 NULL, it defaults to netpath. Each time it
207 receives a response, this routine calls eachre‐
208 sult(), whose form is:
209 bool_t eachresult(caddr_t out, const struct netbuf *addr,
211 const struct netconfig *netconf);
212 where out is the same as out passed to
214 rpc_broadcast(), except that the remote proce‐
215 dure's output is decoded there. addr points to
216 the address of the machine that sent the
217 results, and netconf is the netconfig structure
218 of the transport on which the remote server
219 responded. If eachresult() returns 0, rpc_broad‐
220 cast() waits for more replies; otherwise, it
221 returns with appropriate status.
222 The broadcast file descriptors are limited in
224 size to the maximum transfer size of that trans‐
225 port. For Ethernet, this value is 1500 bytes.
226 rpc_broadcast() uses AUTH_SYS credentials by
227 default. See rpc_clnt_auth(3NSL).
228 rpc_broadcast_exp() Similar to rpc_broadcast(), except that the ini‐
231 tial timeout, inittime and the maximum timeout,
232 waittime, are specified in milliseconds.
233 inittime is the initial time that rpc_broad‐
235 cast_exp() waits before resending the request.
236 After the first resend, the retransmission
237 interval increases exponentially until it
238 exceeds waittime.
239 rpc_call() Calls the remote procedure associated with
242 prognum, versnum, and procnum on the machine,
243 host. The parameter inproc is used to encode the
244 procedure's parameters, and outproc is used to
245 decode the procedure's results. in is the
246 address of the procedure's argument(s), and out
247 is the address of where to place the result(s).
248 nettype can be any of the values listed on
249 rpc(3NSL). This routine returns RPC_SUCCESS if
250 it succeeds, or it returns an appropriate sta‐
251 tus. Use the clnt_perrno() routine to translate
252 failure status into error messages.
253 The rpc_call() function uses the first available
255 transport belonging to the class nettype on
256 which it can create a connection. You do not
257 have control of timeouts or authentication using
258 this routine.
259
262 See attributes(5) for descriptions of the following attributes:
263 ┌─────────────────────────────┬─────────────────────────────┐
268 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
269 ├─────────────────────────────┼─────────────────────────────┤
270 │Architecture │All │
271 ├─────────────────────────────┼─────────────────────────────┤
272 │Availability │SUNWcsl (32-bit) │
273 ├─────────────────────────────┼─────────────────────────────┤
274 │ │SUNWcslx (64-bit) │
275 ├─────────────────────────────┼─────────────────────────────┤
276 │Interface Stability │Evolving │
277 ├─────────────────────────────┼─────────────────────────────┤
278 │MT-Level │MT-Safe │
279 └─────────────────────────────┴─────────────────────────────┘
280
282 printf(3C), rpc(3NSL), rpc_clnt_auth(3NSL), rpc_clnt_create(3NSL),
283 attributes(5)
284SunOS 5.11 1 Aug 2001 rpc_clnt_calls(3NSL)