| blob | 1d63cd6be72cbb81badf35d7bdac9f042e1dfde2 |
1 '\" te
2 .\" Copyright 1989 AT&T
3 .\" Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH RPC_CLNT_CALLS 3NSL "Aug 1, 2001"
8 .SH NAME
9 rpc_clnt_calls, clnt_call, clnt_send, clnt_freeres, clnt_geterr, clnt_perrno,
10 clnt_perror, clnt_sperrno, clnt_sperror, rpc_broadcast, rpc_broadcast_exp,
11 rpc_call \- library routines for client side calls
12 .SH SYNOPSIS
13 .LP
14 .nf
15 #include <rpc/rpc.h>
17 \fBenum clnt_stat\fR \fBclnt_call\fR(\fBCLIENT *\fR\fIclnt\fR, \fBconst rpcproc_t\fR \fIprocnum\fR,
18 \fBconst xdrproc_t\fR \fIinproc\fR,\ \fBconst caddr_t\fR \fIin\fR, \fBconst xdrproc_t\fR \fIoutproc\fR,
19 \fBcaddr_t\fR \fIout\fR, \fBconst struct timeval\fR \fItout\fR);
20 .fi
22 .LP
23 .nf
24 \fBenum clnt_stat\fR \fBclnt_send\fR (\fBCLIENT *\fR\fIclnt\fR, \fBconst u_long\fR
25 \fIprocnum\fR, \fBconst xdrproc_t\fR \fIproc\fR, \fBconst caddr_t\fR \fIin\fR);
26 .fi
28 .LP
29 .nf
30 \fBbool_t\fR \fBclnt_freeres\fR(\fBCLIENT *\fR\fIclnt\fR, \fBconst xdrproc_t\fR \fIoutproc\fR,
31 \fBcaddr_t\fR \fIout\fR);
32 .fi
34 .LP
35 .nf
36 \fBvoid\fR \fBclnt_geterr\fR(\fBconst CLIENT *\fR\fIclnt\fR, \fBstruct rpc_err *\fR\fIerrp\fR);
37 .fi
39 .LP
40 .nf
41 \fBvoid\fR \fBclnt_perrno\fR(\fBconst enum clnt_stat\fR \fIstat\fR);
42 .fi
44 .LP
45 .nf
46 \fBvoid\fR \fBclnt_perror\fR(\fBconst CLIENT *\fR\fIclnt\fR, \fBconst char *\fR\fIs\fR);
47 .fi
49 .LP
50 .nf
51 \fBchar *\fR\fBclnt_sperrno\fR(\fBconst enum clnt_stat\fR \fIstat\fR);
52 .fi
54 .LP
55 .nf
56 \fBchar *\fR\fBclnt_sperror\fR(\fBconst CLIENT *\fR\fIclnt\fR, \fBconst char *\fR\fIs\fR);
57 .fi
59 .LP
60 .nf
61 \fBenum clnt_stat\fR \fBrpc_broadcast\fR(\fBconst rpcprog_t\fR \fIprognum\fR,
62 \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst rpcproc_t\fR \fIprocnum\fR,
63 \fBconst xdrproc_t\fR\fIinproc\fR, \fBconst caddr_t\fR \fIin\fR,
64 \fBconst xdrproc_t\fR \fIoutproc\fR, \fBcaddr_t\fR \fIout\fR,
65 \fBconst resultproc_t\fR \fIeachresult\fR, \fBconst char *\fR\fInettype\fR);
66 .fi
68 .LP
69 .nf
70 \fBenum clnt_stat\fR \fBrpc_broadcast_exp\fR(\fBconst rpcprog_t\fR \fIprognum\fR,
71 \fBconst rpcvers_t\fR \fIversnum\fR,\fBconst rpcproc_t\fR \fIprocnum\fR,
72 \fBconst xdrproc_t\fR\fIxargs\fR, \fBcaddr_t\fR \fIargsp\fR, \fBconst xdrproc_t\fR\fIxresults\fR,
73 \fBcaddr_t\fR \fIresultsp\fR, \fBconst resultproc_t\fR \fIeachresult\fR, \fBconst int\fR \fIinittime\fR,
74 \fBconst int\fR \fIwaittime\fR, \fBconst char *\fR\fInettype\fR);
75 .fi
77 .LP
78 .nf
79 \fBenum clnt_stat\fR \fBrpc_call\fR(\fBconst char *\fR\fIhost\fR, \fBconst rpcprog_t\fR \fIprognum\fR,
80 \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst rpcproc_t\fR \fIprocnum\fR, \fBconst xdrproc_t\fR \fIinproc\fR,
81 \fBconst char *\fR\fIin\fR, \fBconst xdrproc_t\fR \fIoutproc\fR, \fBchar *\fR\fIout\fR, \fBconst char *\fR\fInettype\fR);
82 .fi
84 .SH DESCRIPTION
85 .sp
86 .LP
87 \fBRPC\fR library routines allow \fBC\fR language programs to make procedure
88 calls on other machines across the network. First, the client calls a procedure
89 to send a request to the server. Upon receipt of the request, the server calls
90 a dispatch routine to perform the requested service and then sends back a
91 reply.
92 .sp
93 .LP
94 The \fBclnt_call()\fR, \fBrpc_call()\fR, and \fBrpc_broadcast()\fR routines
95 handle the client side of the procedure call. The remaining routines deal with
96 error handling.
97 .sp
98 .LP
99 Some of the routines take a \fBCLIENT\fR handle as one of the parameters. A
100 \fBCLIENT\fR handle can be created by an \fBRPC\fR creation routine such as
101 \fBclnt_create()\fR. See \fBrpc_clnt_create\fR(3NSL).
102 .sp
103 .LP
104 These routines are safe for use in multithreaded applications. \fBCLIENT\fR
105 handles can be shared between threads; however, in this implementation requests
106 by different threads are serialized. In other words, the first request will
107 receive its results before the second request is sent.
108 .SS "Routines"
109 .sp
110 .LP
111 See \fBrpc\fR(3NSL) for the definition of the \fBCLIENT\fR data structure.
112 .sp
113 .ne 2
114 .na
115 \fB\fBclnt_call()\fR\fR
116 .ad
117 .RS 23n
118 A function macro that calls the remote procedure \fIprocnum\fR associated with
119 the client handle, \fIclnt\fR, which is obtained with an \fBRPC\fR client
120 creation routine such as \fBclnt_create()\fR. See \fBrpc_clnt_create\fR(3NSL).
121 The parameter \fIinproc\fR is the \fBXDR\fR function used to encode the
122 procedure's parameters, and \fIoutproc\fR is the \fBXDR\fR function used to
123 decode the procedure's results. \fIin\fR is the address of the procedure's
124 argument(s), and \fIout\fR is the address of where to place the result(s).
125 \fItout\fR is the time allowed for results to be returned, which is overridden
126 by a time-out set explicitly through \fBclnt_control()\fR. See
127 \fBrpc_clnt_create\fR(3NSL).
128 .sp
129 If the remote call succeeds, the status returned is \fBRPC_SUCCESS\fR.
130 Otherwise, an appropriate status is returned.
131 .RE
133 .sp
134 .ne 2
135 .na
136 \fB\fBclnt_send()\fR\fR
137 .ad
138 .RS 23n
139 Use the \fBclnt_send()\fR function to call a remote asynchronous function.
140 .sp
141 The \fBclnt_send()\fR function calls the remote function \fBprocnum()\fR
142 associated with the client handle, \fIclnt\fR, which is obtained with an RPC
143 client creation routine such as \fBclnt_create()\fR. See
144 \fBrpc_clnt_create\fR(3NSL). The parameter \fIproc\fR is the XDR function used
145 to encode the procedure's parameters. The parameter \fIin\fR is the address of
146 the procedure's argument(s).
147 .sp
148 By default, the blocking I/O mode is used. See the \fBclnt_control\fR(3NSL) man
149 page for more information on I/O modes.
150 .sp
151 The \fBclnt_send()\fR function does not check if the program version number
152 supplied to \fBclnt_create()\fR is registered with the \fBrpcbind\fR service.
153 Use \fBclnt_create_vers()\fR instead of \fBclnt_create()\fR to check on
154 incorrect version number registration. \fBclnt_create_vers()\fR will return a
155 valid handle to the client only if a version within the range supplied to
156 \fBclnt_create_vers()\fR is supported by the server.
157 .sp
158 \fBRPC_SUCCESS\fR is returned when a request is successfully delivered to the
159 transport layer. This does not mean that the request was received. If an error
160 is returned, use the \fBclnt_getterr()\fR routine to find the failure status or
161 the \fBclnt_perrno()\fR routine to translate the failure status into error
162 messages.
163 .RE
165 .sp
166 .ne 2
167 .na
168 \fB\fBclnt_freeres()\fR\fR
169 .ad
170 .RS 23n
171 A function macro that frees any data allocated by the \fBRPC/XDR\fR system when
172 it decoded the results of an \fBRPC\fR call. The parameter \fIout\fR is the
173 address of the results, and \fIoutproc\fR is the \fBXDR\fR routine describing
174 the results. This routine returns \fB1\fR if the results were successfully
175 freed; otherwise it returns \fB0\fR.
176 .RE
178 .sp
179 .ne 2
180 .na
181 \fB\fBclnt_geterr()\fR\fR
182 .ad
183 .RS 23n
184 A function macro that copies the error structure out of the client handle to
185 the structure at address \fIerrp\fR.
186 .RE
188 .sp
189 .ne 2
190 .na
191 \fB\fBclnt_perrno()\fR\fR
192 .ad
193 .RS 23n
194 Prints a message to standard error corresponding to the condition indicated by
195 \fIstat\fR. A newline is appended. It is normally used after a procedure call
196 fails for a routine for which a client handle is not needed, for instance
197 \fBrpc_call()\fR
198 .RE
200 .sp
201 .ne 2
202 .na
203 \fB\fBclnt_perror()\fR\fR
204 .ad
205 .RS 23n
206 Prints a message to the standard error indicating why an \fBRPC\fR call failed;
207 \fIclnt\fR is the handle used to do the call. The message is prepended with
208 string \fIs\fR and a colon. A newline is appended. This routine is normally
209 used after a remote procedure call fails for a routine that requires a client
210 handle, for instance \fBclnt_call()\fR.
211 .RE
213 .sp
214 .ne 2
215 .na
216 \fB\fBclnt_sperrno()\fR\fR
217 .ad
218 .RS 23n
219 Takes the same arguments as \fBclnt_perrno()\fR, but instead of sending a
220 message to the standard error indicating why an \fBRPC\fR call failed, returns
221 a pointer to a string that contains the message.
222 .sp
223 \fBclnt_sperrno()\fR is normally used instead of \fBclnt_perrno()\fR when the
224 program does not have a standard error, as a program running as a server quite
225 likely does not. \fBclnt_sperrno()\fR is also used if the programmer does not
226 want the message to be output with \fBprintf()\fR, or if a message format
227 different than that supported by \fBclnt_perrno()\fR is to be used. See
228 \fBprintf\fR(3C). Unlike \fBclnt_sperror()\fR and \fBclnt_spcreaterror()\fR,
229 \fBclnt_sperrno()\fR does not return a pointer to static data. Therefore, the
230 result is not overwritten on each call. See \fBrpc_clnt_create\fR(3NSL).
231 .RE
233 .sp
234 .ne 2
235 .na
236 \fB\fBclnt_sperror()\fR\fR
237 .ad
238 .RS 23n
239 Similar to \fBclnt_perror()\fR, except that like \fBclnt_sperrno()\fR, it
240 returns a string instead of printing to standard error. However,
241 \fBclnt_sperror()\fR does not append a newline at the end of the message.
242 .sp
243 \fBclnt_sperror()\fR returns a pointer to a buffer that is overwritten on each
244 call. In multithreaded applications, this buffer is implemented as
245 thread-specific data.
246 .RE
248 .sp
249 .ne 2
250 .na
251 \fB\fBrpc_broadcast()\fR\fR
252 .ad
253 .RS 23n
254 Similar to \fBrpc_call()\fR, except that the call message is broadcast to all
255 the connectionless transports specified by \fInettype\fR. If \fInettype\fR is
256 \fINULL\fR, it defaults to \fBnetpath\fR. Each time it receives a response,
257 this routine calls \fBeachresult()\fR, whose form is:
258 .sp
259 .in +2
260 .nf
261 bool_t eachresult(caddr_t out, const struct netbuf *addr,
262 const struct netconfig *netconf);
263 .fi
264 .in -2
266 where \fIout\fR is the same as \fIout\fR passed to \fBrpc_broadcast()\fR,
267 except that the remote procedure's output is decoded there. \fIaddr\fR points
268 to the address of the machine that sent the results, and \fInetconf\fR is the
269 netconfig structure of the transport on which the remote server responded. If
270 \fBeachresult()\fR returns \fB0\fR, \fBrpc_broadcast()\fR waits for more
271 replies; otherwise, it returns with appropriate status.
272 .sp
273 The broadcast file descriptors are limited in size to the maximum transfer size
274 of that transport. For Ethernet, this value is 1500 bytes.
275 \fBrpc_broadcast()\fR uses \fBAUTH_SYS\fR credentials by default. See
276 \fBrpc_clnt_auth\fR(3NSL).
277 .RE
279 .sp
280 .ne 2
281 .na
282 \fB\fBrpc_broadcast_exp()\fR\fR
283 .ad
284 .RS 23n
285 Similar to \fBrpc_broadcast()\fR, except that the initial timeout,
286 \fIinittime\fR and the maximum timeout, \fIwaittime\fR, are specified in
287 milliseconds.
288 .sp
289 \fIinittime\fR is the initial time that \fBrpc_broadcast_exp()\fR waits before
290 resending the request. After the first resend, the retransmission interval
291 increases exponentially until it exceeds \fIwaittime\fR.
292 .RE
294 .sp
295 .ne 2
296 .na
297 \fB\fBrpc_call()\fR\fR
298 .ad
299 .RS 23n
300 Calls the remote procedure associated with \fIprognum\fR, \fIversnum\fR, and
301 \fIprocnum\fR on the machine, \fIhost\fR. The parameter \fIinproc\fR is used to
302 encode the procedure's parameters, and \fIoutproc\fR is used to decode the
303 procedure's results. \fIin\fR is the address of the procedure's argument(s),
304 and \fIout\fR is the address of where to place the result(s). \fInettype\fR can
305 be any of the values listed on \fBrpc\fR(3NSL). This routine returns
306 \fBRPC_SUCCESS\fR if it succeeds, or it returns an appropriate status. Use the
307 \fBclnt_perrno()\fR routine to translate failure status into error messages.
308 .sp
309 The \fBrpc_call()\fR function uses the first available transport belonging to
310 the class \fInettype\fR on which it can create a connection. You do not have
311 control of timeouts or authentication using this routine.
312 .RE
314 .SH ATTRIBUTES
315 .sp
316 .LP
317 See \fBattributes\fR(5) for descriptions of the following attributes:
318 .sp
320 .sp
321 .TS
322 box;
323 c | c
324 l | l .
325 ATTRIBUTE TYPE ATTRIBUTE VALUE
326 _
327 Architecture All
328 _
329 Interface Stability Evolving
330 _
331 MT-Level MT-Safe
332 .TE
334 .SH SEE ALSO
335 .sp
336 .LP
337 \fBprintf\fR(3C), \fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL),
338 \fBrpc_clnt_create\fR(3NSL), \fBattributes\fR(5)