rpc.subproj/clnt.h

   1 /*
   2  * Copyright (c) 1999-2018 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Portions Copyright (c) 1999 Apple Computer, Inc.  All Rights
   7  * Reserved.  This file contains Original Code and/or Modifications of
   8  * Original Code as defined in and that are subject to the Apple Public
   9  * Source License Version 1.1 (the "License").  You may not use this file
  10  * except in compliance with the License.  Please obtain a copy of the
  11  * License at http://www.apple.com/publicsource and read it before using
  12  * this file.
  13  *
  14  * The Original Code and all software distributed under the License are
  15  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  16  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  17  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE OR NON- INFRINGEMENT.  Please see the
  19  * License for the specific language governing rights and limitations
  20  * under the License.
  21  *
  22  * @APPLE_LICENSE_HEADER_END@
  23  */
  24 /*
  25  * Sun RPC is a product of Sun Microsystems, Inc. and is provided for
  26  * unrestricted use provided that this legend is included on all tape
  27  * media and as a part of the software program in whole or part.  Users
  28  * may copy or modify Sun RPC without charge, but are not authorized
  29  * to license or distribute it to anyone else except as part of a product or
  30  * program developed by the user.
  31  *
  32  * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
  33  * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
  34  * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
  35  *
  36  * Sun RPC is provided with no support and without any obligation on the
  37  * part of Sun Microsystems, Inc. to assist in its use, correction,
  38  * modification or enhancement.
  39  *
  40  * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
  41  * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
  42  * OR ANY PART THEREOF.
  43  *
  44  * In no event will Sun Microsystems, Inc. be liable for any lost revenue
  45  * or profits or other special, indirect and consequential damages, even if
  46  * Sun has been advised of the possibility of such damages.
  47  *
  48  * Sun Microsystems, Inc.
  49  * 2550 Garcia Avenue
  50  * Mountain View, California  94043
  51  *
  52  *      from: @(#)clnt.h 1.31 88/02/08 SMI
  53  *      from: @(#)clnt.h        2.1 88/07/29 4.0 RPCSRC
  54  *      $Id: clnt.h,v 1.4 2004/10/28 21:58:22 emoy Exp $
  55  */
  56
  57 /*
  58  * clnt.h - Client side remote procedure call interface.
  59  *
  60  * Copyright (C) 1984, Sun Microsystems, Inc.
  61  */
  62
  63 #ifndef _RPC_CLNT_H_
  64 #define _RPC_CLNT_H_
  65 #include <rpc/auth.h>
  66 #include <sys/cdefs.h>
  67
  68 /*
  69  * Rpc calls return an enum clnt_stat.  This should be looked at more,
  70  * since each implementation is required to live with this (implementation
  71  * independent) list of errors.
  72  */
  73
  74 /* Avoid collision with mach definition */
  75 #if defined(RPC_SUCCESS)
  76 #undef RPC_SUCCESS
  77 #endif
  78
  79 enum clnt_stat {
  80         RPC_SUCCESS=0,                  /* call succeeded */
  81         /*
  82          * local errors
  83          */
  84         RPC_CANTENCODEARGS=1,           /* can't encode arguments */
  85         RPC_CANTDECODERES=2,            /* can't decode results */
  86         RPC_CANTSEND=3,                 /* failure in sending call */
  87         RPC_CANTRECV=4,                 /* failure in receiving result */
  88         RPC_TIMEDOUT=5,                 /* call timed out */
  89         /*
  90          * remote errors
  91          */
  92         RPC_VERSMISMATCH=6,             /* rpc versions not compatible */
  93         RPC_AUTHERROR=7,                /* authentication error */
  94         RPC_PROGUNAVAIL=8,              /* program not available */
  95         RPC_PROGVERSMISMATCH=9,         /* program version mismatched */
  96         RPC_PROCUNAVAIL=10,             /* procedure unavailable */
  97         RPC_CANTDECODEARGS=11,          /* decode arguments error */
  98         RPC_SYSTEMERROR=12,             /* generic "other problem" */
  99
 100         /*
 101          * callrpc & clnt_create errors
 102          */
 103         RPC_UNKNOWNHOST=13,             /* unknown host name */
 104         RPC_UNKNOWNPROTO=17,            /* unkown protocol */
 105
 106         /*
 107          * _ create errors
 108          */
 109         RPC_PMAPFAILURE=14,             /* the pmapper failed in its call */
 110         RPC_PROGNOTREGISTERED=15,       /* remote program is not registered */
 111         /*
 112          * unspecified error
 113          */
 114         RPC_FAILED=16
 115 };
 116
 117
 118 /*
 119  * Error info.
 120  */
 121 struct rpc_err {
 122         enum clnt_stat re_status;
 123         union {
 124                 int RE_errno;           /* realated system error */
 125                 enum auth_stat RE_why;  /* why the auth error occurred */
 126                 struct {
 127 #ifdef __LP64__
 128                         unsigned int low;       /* lowest verion supported */
 129                         unsigned int high;      /* highest verion supported */
 130 #else
 131                         unsigned long low;      /* lowest verion supported */
 132                         unsigned long high;     /* highest verion supported */
 133 #endif
 134                 } RE_vers;
 135                 struct {                /* maybe meaningful if RPC_FAILED */
 136 #ifdef __LP64__
 137                         int s1;
 138                         int s2;
 139 #else
 140                         long s1;
 141                         long s2;
 142 #endif
 143                 } RE_lb;                /* life boot & debugging only */
 144         } ru;
 145 #define re_errno        ru.RE_errno
 146 #define re_why          ru.RE_why
 147 #define re_vers         ru.RE_vers
 148 #define re_lb           ru.RE_lb
 149 };
 150
 151
 152 /*
 153  * Client rpc handle.
 154  * Created by individual implementations, see e.g. rpc_udp.c.
 155  * Client is responsible for initializing auth, see e.g. auth_none.c.
 156  */
 157 typedef struct CLIENT CLIENT;
 158 struct CLIENT
 159 {
 160         AUTH    *cl_auth;       /* authenticator */
 161         struct clnt_ops {
 162 #ifdef __LP64__
 163                 enum clnt_stat (*cl_call)(CLIENT *, unsigned int, xdrproc_t, void *, xdrproc_t, void *, struct timeval);        /* call remote procedure */
 164 #else
 165                 enum clnt_stat (*cl_call)(CLIENT *, unsigned long, xdrproc_t, void *, xdrproc_t, void *, struct timeval);       /* call remote procedure */
 166 #endif
 167                 void (*cl_abort)(void);         /* abort a call */
 168                 void (*cl_geterr)(CLIENT *, struct rpc_err *);  /* get specific error code */
 169                 bool_t (*cl_freeres)(CLIENT *, xdrproc_t, void *);      /* frees results */
 170                 void (*cl_destroy)(CLIENT *);   /* destroy this structure */
 171                 bool_t (*cl_control)(CLIENT *, int, char *);    /* the ioctl() of rpc */
 172         } *cl_ops;
 173         caddr_t cl_private;     /* private stuff */
 174 };
 175
 176 /*
 177  * client side rpc interface ops
 178  *
 179  * Parameter types are:
 180  *
 181  */
 182
 183 /*
 184  * enum clnt_stat
 185  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
 186  *      CLIENT *rh;
 187  *      u_long proc;
 188  *      xdrproc_t xargs;
 189  *      caddr_t argsp;
 190  *      xdrproc_t xres;
 191  *      caddr_t resp;
 192  *      struct timeval timeout;
 193  */
 194 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)     \
 195         ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
 196 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs)     \
 197         ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
 198
 199 /*
 200  * void
 201  * CLNT_ABORT(rh);
 202  *      CLIENT *rh;
 203  */
 204 #define CLNT_ABORT(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
 205 #define clnt_abort(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
 206
 207 /*
 208  * struct rpc_err
 209  * CLNT_GETERR(rh);
 210  *      CLIENT *rh;
 211  */
 212 #define CLNT_GETERR(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
 213 #define clnt_geterr(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
 214
 215
 216 /*
 217  * bool_t
 218  * CLNT_FREERES(rh, xres, resp);
 219  *      CLIENT *rh;
 220  *      xdrproc_t xres;
 221  *      caddr_t resp;
 222  */
 223 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
 224 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
 225
 226 /*
 227  * bool_t
 228  * CLNT_CONTROL(cl, request, info)
 229  *      CLIENT *cl;
 230  *      unsigned int request;
 231  *      char *info;
 232  */
 233 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
 234 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
 235
 236 /*
 237  * control operations that apply to both udp and tcp transports
 238  */
 239 #define CLSET_TIMEOUT       1   /* set timeout (timeval) */
 240 #define CLGET_TIMEOUT       2   /* get timeout (timeval) */
 241 #define CLGET_SERVER_ADDR   3   /* get server's address (sockaddr) */
 242 /*
 243  * udp only control operations
 244  */
 245 #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
 246 #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
 247
 248 /*
 249  * void
 250  * CLNT_DESTROY(rh);
 251  *      CLIENT *rh;
 252  */
 253 #define CLNT_DESTROY(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
 254 #define clnt_destroy(rh)        ((*(rh)->cl_ops->cl_destroy)(rh))
 255
 256
 257 /*
 258  * RPCTEST is a test program which is accessable on every rpc
 259  * transport/port.  It is used for testing, performance evaluation,
 260  * and network administration.
 261  */
 262
 263 #ifdef __LP64__
 264 #define RPCTEST_PROGRAM         ((unsigned int)1)
 265 #define RPCTEST_VERSION         ((unsigned int)1)
 266 #define RPCTEST_NULL_PROC       ((unsigned int)2)
 267 #define RPCTEST_NULL_BATCH_PROC ((unsigned int)3)
 268 #else
 269 #define RPCTEST_PROGRAM         ((unsigned long)1)
 270 #define RPCTEST_VERSION         ((unsigned long)1)
 271 #define RPCTEST_NULL_PROC       ((unsigned long)2)
 272 #define RPCTEST_NULL_BATCH_PROC ((unsigned long)3)
 273 #endif
 274
 275 /*
 276  * By convention, procedure 0 takes null arguments and returns them
 277  */
 278
 279 #ifdef __LP64__
 280 #define NULLPROC ((unsigned int)0)
 281 #else
 282 #define NULLPROC ((unsigned long)0)
 283 #endif
 284
 285 /*
 286  * Below are the client handle creation routines for the various
 287  * implementations of client side rpc.  They can return NULL if a
 288  * creation failure occurs.
 289  */
 290
 291 /*
 292  * Memory based rpc (for speed check and testing)
 293  * CLIENT *
 294  * clntraw_create(prog, vers)
 295  *      u_long prog;
 296  *      u_long vers;
 297  */
 298 __BEGIN_DECLS
 299 #ifdef __LP64__
 300 extern CLIENT *clntraw_create   __P((unsigned int, unsigned int));
 301 #else
 302 extern CLIENT *clntraw_create   __P((unsigned long, unsigned long));
 303 #endif
 304 __END_DECLS
 305
 306
 307 /*
 308  * Generic client creation routine. Supported protocols are "udp" and "tcp"
 309  * CLIENT *
 310  * clnt_create(host, prog, vers, prot);
 311  *      char *host;     -- hostname
 312  *      u_long prog;    -- program number
 313  *      u_long vers;    -- version number
 314  *      char *prot;     -- protocol
 315  */
 316 __BEGIN_DECLS
 317 #ifdef __LP64__
 318 extern CLIENT *clnt_create      __P((char *, unsigned int, unsigned int, char *));
 319 #else
 320 extern CLIENT *clnt_create      __P((char *, unsigned long, unsigned long, char *));
 321 #endif
 322 __END_DECLS
 323
 324
 325 /*
 326  * TCP based rpc
 327  * CLIENT *
 328  * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
 329  *      struct sockaddr_in *raddr;
 330  *      u_long prog;
 331  *      u_long version;
 332  *      register int *sockp;
 333  *      unsigned int sendsz;
 334  *      unsigned int recvsz;
 335  */
 336 __BEGIN_DECLS
 337 #ifdef __LP64__
 338 extern CLIENT *clnttcp_create   __P((struct sockaddr_in *,
 339                                                                          unsigned int,
 340                                                                          unsigned int,
 341                                                                          int *,
 342                                                                          unsigned int,
 343                                                                          unsigned int));
 344 #else
 345 extern CLIENT *clnttcp_create   __P((struct sockaddr_in *,
 346                                                                          unsigned long,
 347                                                                          unsigned long,
 348                                                                          int *,
 349                                                                          unsigned int,
 350                                                                          unsigned int));
 351 #endif
 352 __END_DECLS
 353
 354
 355 /*
 356  * UDP based rpc.
 357  * CLIENT *
 358  * clntudp_create(raddr, program, version, wait, sockp)
 359  *      struct sockaddr_in *raddr;
 360  *      u_long program;
 361  *      u_long version;
 362  *      struct timeval wait;
 363  *      int *sockp;
 364  *
 365  * Same as above, but you specify max packet sizes.
 366  * CLIENT *
 367  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
 368  *      struct sockaddr_in *raddr;
 369  *      u_long program;
 370  *      u_long version;
 371  *      struct timeval wait;
 372  *      int *sockp;
 373  *      unsigned int sendsz;
 374  *      unsigned int recvsz;
 375  */
 376 __BEGIN_DECLS
 377 #ifdef __LP64__
 378 extern CLIENT *clntudp_create   __P((struct sockaddr_in *,
 379                                                                          unsigned int,
 380                                                                          unsigned int,
 381                                                                          struct timeval,
 382                                                                          int *));
 383 extern CLIENT *clntudp_bufcreate __P((struct sockaddr_in *,
 384                                                                           unsigned int,
 385                                                                           unsigned int,
 386                                                                           struct timeval,
 387                                                                           int *,
 388                                                                           unsigned int,
 389                                                                           unsigned int));
 390 #else
 391 extern CLIENT *clntudp_create   __P((struct sockaddr_in *,
 392                                                                          unsigned long,
 393                                                                          unsigned long,
 394                                                                          struct timeval,
 395                                                                          int *));
 396 extern CLIENT *clntudp_bufcreate __P((struct sockaddr_in *,
 397                                                                           unsigned long,
 398                                                                           unsigned long,
 399                                                                           struct timeval,
 400                                                                           int *,
 401                                                                           unsigned int,
 402                                                                           unsigned int));
 403 #endif
 404 __END_DECLS
 405
 406
 407 /*
 408  * Print why creation failed
 409  */
 410 __BEGIN_DECLS
 411 extern void clnt_pcreateerror   __P((char *));                  /* stderr */
 412 extern char *clnt_spcreateerror __P((char *));                  /* string */
 413 __END_DECLS
 414
 415 /*
 416  * Like clnt_perror(), but is more verbose in its output
 417  */
 418 __BEGIN_DECLS
 419 extern void clnt_perrno         __P((enum clnt_stat));          /* stderr */
 420 extern char *clnt_sperrno       __P((enum clnt_stat));          /* string */
 421 __END_DECLS
 422
 423 /*
 424  * Print an English error message, given the client error code
 425  */
 426 __BEGIN_DECLS
 427 extern void clnt_perror         __P((CLIENT *, char *));        /* stderr */
 428 extern char *clnt_sperror       __P((CLIENT *, char *));        /* string */
 429 __END_DECLS
 430
 431
 432 /*
 433  * If a creation fails, the following allows the user to figure out why.
 434  */
 435 struct rpc_createerr {
 436         enum clnt_stat cf_stat;
 437         struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
 438 };
 439
 440 extern struct rpc_createerr rpc_createerr;
 441
 442
 443 #define UDPMSGSIZE      8800    /* rpc imposed limit on udp msg size */
 444 #define RPCSMALLMSGSIZE 400     /* a more reasonable packet size */
 445
 446 #endif /* !_RPC_CLNT_H */