Don't underestimate length of DST substitution
[glibc.git] / sunrpc / rpc / clnt.h
blob5b03b86c0f034d3e1e8cd040af6e26e8e9970365
1 /*
2 * clnt.h - Client side remote procedure call interface.
4 * Copyright (C) 1984, Sun Microsystems, Inc.
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are
8 * met:
10 * * Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * * Redistributions in binary form must reproduce the above
13 * copyright notice, this list of conditions and the following
14 * disclaimer in the documentation and/or other materials
15 * provided with the distribution.
16 * * Neither the name of Sun Microsystems, Inc. nor the names of its
17 * contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
24 * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
25 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
27 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
29 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
30 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 #ifndef _RPC_CLNT_H
35 #define _RPC_CLNT_H 1
37 #include <features.h>
38 #include <sys/types.h>
39 #include <rpc/types.h>
40 #include <rpc/auth.h>
41 #include <sys/un.h>
43 __BEGIN_DECLS
46 * Rpc calls return an enum clnt_stat. This should be looked at more,
47 * since each implementation is required to live with this (implementation
48 * independent) list of errors.
50 enum clnt_stat {
51 RPC_SUCCESS=0, /* call succeeded */
53 * local errors
55 RPC_CANTENCODEARGS=1, /* can't encode arguments */
56 RPC_CANTDECODERES=2, /* can't decode results */
57 RPC_CANTSEND=3, /* failure in sending call */
58 RPC_CANTRECV=4, /* failure in receiving result */
59 RPC_TIMEDOUT=5, /* call timed out */
61 * remote errors
63 RPC_VERSMISMATCH=6, /* rpc versions not compatible */
64 RPC_AUTHERROR=7, /* authentication error */
65 RPC_PROGUNAVAIL=8, /* program not available */
66 RPC_PROGVERSMISMATCH=9, /* program version mismatched */
67 RPC_PROCUNAVAIL=10, /* procedure unavailable */
68 RPC_CANTDECODEARGS=11, /* decode arguments error */
69 RPC_SYSTEMERROR=12, /* generic "other problem" */
70 RPC_NOBROADCAST = 21, /* Broadcasting not supported */
72 * callrpc & clnt_create errors
74 RPC_UNKNOWNHOST=13, /* unknown host name */
75 RPC_UNKNOWNPROTO=17, /* unknown protocol */
76 RPC_UNKNOWNADDR = 19, /* Remote address unknown */
79 * rpcbind errors
81 RPC_RPCBFAILURE=14, /* portmapper failed in its call */
82 #define RPC_PMAPFAILURE RPC_RPCBFAILURE
83 RPC_PROGNOTREGISTERED=15, /* remote program is not registered */
84 RPC_N2AXLATEFAILURE = 22, /* Name to addr translation failed */
86 * unspecified error
88 RPC_FAILED=16,
89 RPC_INTR=18,
90 RPC_TLIERROR=20,
91 RPC_UDERROR=23,
93 * asynchronous errors
95 RPC_INPROGRESS = 24,
96 RPC_STALERACHANDLE = 25
101 * Error info.
103 struct rpc_err {
104 enum clnt_stat re_status;
105 union {
106 int RE_errno; /* related system error */
107 enum auth_stat RE_why; /* why the auth error occurred */
108 struct {
109 u_long low; /* lowest verion supported */
110 u_long high; /* highest verion supported */
111 } RE_vers;
112 struct { /* maybe meaningful if RPC_FAILED */
113 long s1;
114 long s2;
115 } RE_lb; /* life boot & debugging only */
116 } ru;
117 #define re_errno ru.RE_errno
118 #define re_why ru.RE_why
119 #define re_vers ru.RE_vers
120 #define re_lb ru.RE_lb
125 * Client rpc handle.
126 * Created by individual implementations, see e.g. rpc_udp.c.
127 * Client is responsible for initializing auth, see e.g. auth_none.c.
129 typedef struct CLIENT CLIENT;
130 struct CLIENT {
131 AUTH *cl_auth; /* authenticator */
132 struct clnt_ops {
133 enum clnt_stat (*cl_call) (CLIENT *, u_long, xdrproc_t, caddr_t, xdrproc_t,
134 caddr_t, struct timeval);
135 /* call remote procedure */
136 void (*cl_abort) (void); /* abort a call */
137 void (*cl_geterr) (CLIENT *, struct rpc_err *);
138 /* get specific error code */
139 bool_t (*cl_freeres) (CLIENT *, xdrproc_t, caddr_t);
140 /* frees results */
141 void (*cl_destroy) (CLIENT *); /* destroy this structure */
142 bool_t (*cl_control) (CLIENT *, int, char *);
143 /* the ioctl() of rpc */
144 } *cl_ops;
145 caddr_t cl_private; /* private stuff */
150 * client side rpc interface ops
152 * Parameter types are:
157 * enum clnt_stat
158 * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
159 * CLIENT *rh;
160 * u_long proc;
161 * xdrproc_t xargs;
162 * caddr_t argsp;
163 * xdrproc_t xres;
164 * caddr_t resp;
165 * struct timeval timeout;
167 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \
168 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
169 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \
170 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
173 * void
174 * CLNT_ABORT(rh);
175 * CLIENT *rh;
177 #define CLNT_ABORT(rh) ((*(rh)->cl_ops->cl_abort)(rh))
178 #define clnt_abort(rh) ((*(rh)->cl_ops->cl_abort)(rh))
181 * struct rpc_err
182 * CLNT_GETERR(rh);
183 * CLIENT *rh;
185 #define CLNT_GETERR(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
186 #define clnt_geterr(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
190 * bool_t
191 * CLNT_FREERES(rh, xres, resp);
192 * CLIENT *rh;
193 * xdrproc_t xres;
194 * caddr_t resp;
196 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
197 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
200 * bool_t
201 * CLNT_CONTROL(cl, request, info)
202 * CLIENT *cl;
203 * u_int request;
204 * char *info;
206 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
207 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
210 * control operations that apply to all transports
212 * Note: options marked XXX are no-ops in this implementation of RPC.
213 * The are present in TI-RPC but can't be implemented here since they
214 * depend on the presence of STREAMS/TLI, which we don't have.
216 #define CLSET_TIMEOUT 1 /* set timeout (timeval) */
217 #define CLGET_TIMEOUT 2 /* get timeout (timeval) */
218 #define CLGET_SERVER_ADDR 3 /* get server's address (sockaddr) */
219 #define CLGET_FD 6 /* get connections file descriptor */
220 #define CLGET_SVC_ADDR 7 /* get server's address (netbuf) XXX */
221 #define CLSET_FD_CLOSE 8 /* close fd while clnt_destroy */
222 #define CLSET_FD_NCLOSE 9 /* Do not close fd while clnt_destroy*/
223 #define CLGET_XID 10 /* Get xid */
224 #define CLSET_XID 11 /* Set xid */
225 #define CLGET_VERS 12 /* Get version number */
226 #define CLSET_VERS 13 /* Set version number */
227 #define CLGET_PROG 14 /* Get program number */
228 #define CLSET_PROG 15 /* Set program number */
229 #define CLSET_SVC_ADDR 16 /* get server's address (netbuf) XXX */
230 #define CLSET_PUSH_TIMOD 17 /* push timod if not already present XXX */
231 #define CLSET_POP_TIMOD 18 /* pop timod XXX */
233 * Connectionless only control operations
235 #define CLSET_RETRY_TIMEOUT 4 /* set retry timeout (timeval) */
236 #define CLGET_RETRY_TIMEOUT 5 /* get retry timeout (timeval) */
239 * void
240 * CLNT_DESTROY(rh);
241 * CLIENT *rh;
243 #define CLNT_DESTROY(rh) ((*(rh)->cl_ops->cl_destroy)(rh))
244 #define clnt_destroy(rh) ((*(rh)->cl_ops->cl_destroy)(rh))
248 * RPCTEST is a test program which is accessible on every rpc
249 * transport/port. It is used for testing, performance evaluation,
250 * and network administration.
253 #define RPCTEST_PROGRAM ((u_long)1)
254 #define RPCTEST_VERSION ((u_long)1)
255 #define RPCTEST_NULL_PROC ((u_long)2)
256 #define RPCTEST_NULL_BATCH_PROC ((u_long)3)
259 * By convention, procedure 0 takes null arguments and returns them
262 #define NULLPROC ((u_long)0)
265 * Below are the client handle creation routines for the various
266 * implementations of client side rpc. They can return NULL if a
267 * creation failure occurs.
271 * Memory based rpc (for speed check and testing)
272 * CLIENT *
273 * clntraw_create(prog, vers)
274 * u_long prog;
275 * u_long vers;
277 extern CLIENT *clntraw_create (__const u_long __prog, __const u_long __vers)
278 __THROW;
282 * Generic client creation routine. Supported protocols are "udp", "tcp" and
283 * "unix"
284 * CLIENT *
285 * clnt_create(host, prog, vers, prot)
286 * char *host; -- hostname
287 * u_long prog; -- program number
288 * u_ong vers; -- version number
289 * char *prot; -- protocol
291 extern CLIENT *clnt_create (__const char *__host, __const u_long __prog,
292 __const u_long __vers, __const char *__prot)
293 __THROW;
297 * TCP based rpc
298 * CLIENT *
299 * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
300 * struct sockaddr_in *raddr;
301 * u_long prog;
302 * u_long version;
303 * register int *sockp;
304 * u_int sendsz;
305 * u_int recvsz;
307 extern CLIENT *clnttcp_create (struct sockaddr_in *__raddr, u_long __prog,
308 u_long __version, int *__sockp, u_int __sendsz,
309 u_int __recvsz) __THROW;
312 * UDP based rpc.
313 * CLIENT *
314 * clntudp_create(raddr, program, version, wait, sockp)
315 * struct sockaddr_in *raddr;
316 * u_long program;
317 * u_long version;
318 * struct timeval wait_resend;
319 * int *sockp;
321 * Same as above, but you specify max packet sizes.
322 * CLIENT *
323 * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
324 * struct sockaddr_in *raddr;
325 * u_long program;
326 * u_long version;
327 * struct timeval wait_resend;
328 * int *sockp;
329 * u_int sendsz;
330 * u_int recvsz;
332 extern CLIENT *clntudp_create (struct sockaddr_in *__raddr, u_long __program,
333 u_long __version, struct timeval __wait_resend,
334 int *__sockp) __THROW;
335 extern CLIENT *clntudp_bufcreate (struct sockaddr_in *__raddr,
336 u_long __program, u_long __version,
337 struct timeval __wait_resend, int *__sockp,
338 u_int __sendsz, u_int __recvsz) __THROW;
344 * AF_UNIX based rpc
345 * CLIENT *
346 * clntunix_create(raddr, prog, vers, sockp, sendsz, recvsz)
347 * struct sockaddr_un *raddr;
348 * u_long prog;
349 * u_long version;
350 * register int *sockp;
351 * u_int sendsz;
352 * u_int recvsz;
354 extern CLIENT *clntunix_create (struct sockaddr_un *__raddr, u_long __program,
355 u_long __version, int *__sockp,
356 u_int __sendsz, u_int __recvsz) __THROW;
359 extern int callrpc (__const char *__host, __const u_long __prognum,
360 __const u_long __versnum, __const u_long __procnum,
361 __const xdrproc_t __inproc, __const char *__in,
362 __const xdrproc_t __outproc, char *__out) __THROW;
363 extern int _rpc_dtablesize (void) __THROW;
366 * Print why creation failed
368 extern void clnt_pcreateerror (__const char *__msg); /* stderr */
369 extern char *clnt_spcreateerror(__const char *__msg) __THROW; /* string */
372 * Like clnt_perror(), but is more verbose in its output
374 extern void clnt_perrno (enum clnt_stat __num); /* stderr */
377 * Print an English error message, given the client error code
379 extern void clnt_perror (CLIENT *__clnt, __const char *__msg);
380 /* stderr */
381 extern char *clnt_sperror (CLIENT *__clnt, __const char *__msg) __THROW;
382 /* string */
385 * If a creation fails, the following allows the user to figure out why.
387 struct rpc_createerr {
388 enum clnt_stat cf_stat;
389 struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
392 extern struct rpc_createerr rpc_createerr;
397 * Copy error message to buffer.
399 extern char *clnt_sperrno (enum clnt_stat __num) __THROW; /* string */
402 * get the port number on the host for the rpc program,version and proto
404 extern int getrpcport (__const char * __host, u_long __prognum,
405 u_long __versnum, u_int __proto) __THROW;
408 * get the local host's IP address without consulting
409 * name service library functions
411 extern void get_myaddress (struct sockaddr_in *) __THROW;
413 #define UDPMSGSIZE 8800 /* rpc imposed limit on udp msg size */
414 #define RPCSMALLMSGSIZE 400 /* a more reasonable packet size */
416 __END_DECLS
418 #endif /* rpc/clnt.h */