1 /* @(#)clnt.h 2.1 88/07/29 4.0 RPCSRC; from 1.31 88/02/08 SMI*/ 2 /* 3 * Copyright (c) 2010, Oracle America, Inc. 4 * 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions are met: 9 * 10 * * Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 13 * * Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in 15 * the documentation and/or other materials provided with the 16 * distribution. 17 * 18 * * Neither the name of the "Oracle America, Inc." nor the names of 19 * its contributors may be used to endorse or promote products 20 * derived from this software without specific prior written permission. 21 * 22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 23 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 24 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 25 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 26 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 28 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 29 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 30 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 31 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 32 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 33 */ 34 35 /* 36 * clnt.h - Client side remote procedure call interface. 37 */ 38 39 #ifndef GSSRPC_CLNT_H 40 #define GSSRPC_CLNT_H 41 42 GSSRPC__BEGIN_DECLS 43 /* 44 * Rpc calls return an enum clnt_stat. This should be looked at more, 45 * since each implementation is required to live with this (implementation 46 * independent) list of errors. 47 */ 48 enum clnt_stat { 49 RPC_SUCCESS=0, /* call succeeded */ 50 /* 51 * local errors 52 */ 53 RPC_CANTENCODEARGS=1, /* can't encode arguments */ 54 RPC_CANTDECODERES=2, /* can't decode results */ 55 RPC_CANTSEND=3, /* failure in sending call */ 56 RPC_CANTRECV=4, /* failure in receiving result */ 57 RPC_TIMEDOUT=5, /* call timed out */ 58 /* 59 * remote errors 60 */ 61 RPC_VERSMISMATCH=6, /* rpc versions not compatible */ 62 RPC_AUTHERROR=7, /* authentication error */ 63 RPC_PROGUNAVAIL=8, /* program not available */ 64 RPC_PROGVERSMISMATCH=9, /* program version mismatched */ 65 RPC_PROCUNAVAIL=10, /* procedure unavailable */ 66 RPC_CANTDECODEARGS=11, /* decode arguments error */ 67 RPC_SYSTEMERROR=12, /* generic "other problem" */ 68 69 /* 70 * callrpc & clnt_create errors 71 */ 72 RPC_UNKNOWNHOST=13, /* unknown host name */ 73 RPC_UNKNOWNPROTO=17, /* unknown protocol */ 74 75 /* 76 * _ create errors 77 */ 78 RPC_PMAPFAILURE=14, /* the pmapper failed in its call */ 79 RPC_PROGNOTREGISTERED=15, /* remote program is not registered */ 80 /* 81 * unspecified error 82 */ 83 RPC_FAILED=16 84 }; 85 86 87 /* 88 * Error info. 89 */ 90 struct rpc_err { 91 enum clnt_stat re_status; 92 union { 93 int RE_errno; /* realated system error */ 94 enum auth_stat RE_why; /* why the auth error occurred */ 95 struct { 96 rpcvers_t low; /* lowest version supported */ 97 rpcvers_t high; /* highest version supported */ 98 } RE_vers; 99 struct { /* maybe meaningful if RPC_FAILED */ 100 int32_t s1; 101 int32_t s2; 102 } RE_lb; /* life boot & debugging only */ 103 } ru; 104 #define re_errno ru.RE_errno 105 #define re_why ru.RE_why 106 #define re_vers ru.RE_vers 107 #define re_lb ru.RE_lb 108 }; 109 110 111 /* 112 * Client rpc handle. 113 * Created by individual implementations, see e.g. rpc_udp.c. 114 * Client is responsible for initializing auth, see e.g. auth_none.c. 115 */ 116 typedef struct CLIENT { 117 AUTH *cl_auth; /* authenticator */ 118 struct clnt_ops { 119 /* call remote procedure */ 120 enum clnt_stat (*cl_call)(struct CLIENT *, 121 rpcproc_t, xdrproc_t, void *, 122 xdrproc_t, void *, 123 struct timeval); 124 /* abort a call */ 125 void (*cl_abort)(struct CLIENT *); 126 /* get specific error code */ 127 void (*cl_geterr)(struct CLIENT *, 128 struct rpc_err *); 129 /* frees results */ 130 bool_t (*cl_freeres)(struct CLIENT *, 131 xdrproc_t, void *); 132 /* destroy this structure */ 133 void (*cl_destroy)(struct CLIENT *); 134 /* the ioctl() of rpc */ 135 /* XXX CITI makes 2nd arg take u_int */ 136 bool_t (*cl_control)(struct CLIENT *, int, 137 void *); 138 } *cl_ops; 139 void *cl_private; /* private stuff */ 140 } CLIENT; 141 142 143 /* 144 * client side rpc interface ops 145 * 146 * Parameter types are: 147 * 148 */ 149 150 /* 151 * enum clnt_stat 152 * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout) 153 * CLIENT *rh; 154 * rpcproc_t proc; 155 * xdrproc_t xargs; 156 * caddr_t argsp; 157 * xdrproc_t xres; 158 * caddr_t resp; 159 * struct timeval timeout; 160 */ 161 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \ 162 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs)) 163 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \ 164 ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs)) 165 166 /* 167 * void 168 * CLNT_ABORT(rh); 169 * CLIENT *rh; 170 */ 171 #define CLNT_ABORT(rh) ((*(rh)->cl_ops->cl_abort)(rh)) 172 #define clnt_abort(rh) ((*(rh)->cl_ops->cl_abort)(rh)) 173 174 /* 175 * struct rpc_err 176 * CLNT_GETERR(rh); 177 * CLIENT *rh; 178 */ 179 #define CLNT_GETERR(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp)) 180 #define clnt_geterr(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp)) 181 182 183 /* 184 * bool_t 185 * CLNT_FREERES(rh, xres, resp); 186 * CLIENT *rh; 187 * xdrproc_t xres; 188 * caddr_t resp; 189 */ 190 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp)) 191 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp)) 192 193 /* 194 * bool_t 195 * CLNT_CONTROL(cl, request, info) 196 * CLIENT *cl; 197 * u_int request; 198 * char *info; 199 */ 200 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in)) 201 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in)) 202 203 /* 204 * control operations that apply to both udp and tcp transports 205 */ 206 #define CLSET_TIMEOUT 1 /* set timeout (timeval) */ 207 #define CLGET_TIMEOUT 2 /* get timeout (timeval) */ 208 #define CLGET_SERVER_ADDR 3 /* get server's address (sockaddr) */ 209 /* 210 * udp only control operations 211 */ 212 #define CLSET_RETRY_TIMEOUT 4 /* set retry timeout (timeval) */ 213 #define CLGET_RETRY_TIMEOUT 5 /* get retry timeout (timeval) */ 214 /* 215 * new control operations 216 */ 217 #define CLGET_LOCAL_ADDR 6 /* get local address (sockaddr, getsockname)*/ 218 219 /* 220 * void 221 * CLNT_DESTROY(rh); 222 * CLIENT *rh; 223 */ 224 #define CLNT_DESTROY(rh) ((*(rh)->cl_ops->cl_destroy)(rh)) 225 #define clnt_destroy(rh) ((*(rh)->cl_ops->cl_destroy)(rh)) 226 227 228 /* 229 * RPCTEST is a test program which is accessible on every rpc 230 * transport/port. It is used for testing, performance evaluation, 231 * and network administration. 232 */ 233 234 #define RPCTEST_PROGRAM ((rpcprog_t)1) 235 #define RPCTEST_VERSION ((rpcvers_t)1) 236 #define RPCTEST_NULL_PROC ((rpcproc_t)2) 237 #define RPCTEST_NULL_BATCH_PROC ((rpcproc_t)3) 238 239 /* 240 * By convention, procedure 0 takes null arguments and returns them 241 */ 242 243 #define NULLPROC ((rpcproc_t)0) 244 245 /* 246 * Below are the client handle creation routines for the various 247 * implementations of client side rpc. They can return NULL if a 248 * creation failure occurs. 249 */ 250 251 /* 252 * Memory based rpc (for speed check and testing) 253 * CLIENT * 254 * clntraw_create(prog, vers) 255 * rpcprog_t prog; 256 * rpcvers_t vers; 257 */ 258 extern CLIENT *clntraw_create(rpcprog_t, rpcvers_t); 259 260 /* 261 * Generic client creation routine. Supported protocols are "udp" and "tcp" 262 */ 263 extern CLIENT *clnt_create(char *, rpcprog_t, rpcvers_t, char *); 264 265 266 /* 267 * TCP based rpc 268 * CLIENT * 269 * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz) 270 * struct sockaddr_in *raddr; 271 * rpcprog_t prog; 272 * rpcvers_t version; 273 * int *sockp; 274 * u_int sendsz; 275 * u_int recvsz; 276 */ 277 extern CLIENT *clnttcp_create(struct sockaddr_in *, rpcprog_t, rpcvers_t, 278 int *, u_int, u_int); 279 280 /* 281 * UDP based rpc. 282 * CLIENT * 283 * clntudp_create(raddr, program, version, wait, sockp) 284 * struct sockaddr_in *raddr; 285 * rpcprog_t program; 286 * rpcvers_t version; 287 * struct timeval wait; 288 * int *sockp; 289 * 290 * Same as above, but you specify max packet sizes. 291 * CLIENT * 292 * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz) 293 * struct sockaddr_in *raddr; 294 * rpcprog_t program; 295 * rpcvers_t version; 296 * struct timeval wait; 297 * int *sockp; 298 * u_int sendsz; 299 * u_int recvsz; 300 */ 301 extern CLIENT *clntudp_create(struct sockaddr_in *, rpcprog_t, 302 rpcvers_t, struct timeval, int *); 303 extern CLIENT *clntudp_bufcreate(struct sockaddr_in *, rpcprog_t, 304 rpcvers_t, struct timeval, int *, 305 u_int, u_int); 306 307 /* 308 * Print why creation failed 309 */ 310 void clnt_pcreateerror(char *); /* stderr */ 311 char *clnt_spcreateerror(char *); /* string */ 312 313 /* 314 * Like clnt_perror(), but is more verbose in its output 315 */ 316 void clnt_perrno(enum clnt_stat); /* stderr */ 317 318 /* 319 * Print an English error message, given the client error code 320 */ 321 void clnt_perror(CLIENT *, char *); /* stderr */ 322 char *clnt_sperror(CLIENT *, char *); /* string */ 323 324 /* 325 * If a creation fails, the following allows the user to figure out why. 326 */ 327 struct rpc_createerr { 328 enum clnt_stat cf_stat; 329 struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */ 330 }; 331 332 extern struct rpc_createerr rpc_createerr; 333 334 335 336 /* 337 * Copy error message to buffer. 338 */ 339 char *clnt_sperrno(enum clnt_stat num); /* string */ 340 341 #define UDPMSGSIZE 8800 /* rpc imposed limit on udp msg size */ 342 #define RPCSMALLMSGSIZE 400 /* a more reasonable packet size */ 343 344 GSSRPC__END_DECLS 345 346 #endif /* !defined(GSSRPC_CLNT_H) */ 347