Back to index

glibc  2.9
clnt.h
Go to the documentation of this file.
00001 /* @(#)clnt.h 2.1 88/07/29 4.0 RPCSRC; from 1.31 88/02/08 SMI*/
00002 /*
00003  * Sun RPC is a product of Sun Microsystems, Inc. and is provided for
00004  * unrestricted use provided that this legend is included on all tape
00005  * media and as a part of the software program in whole or part.  Users
00006  * may copy or modify Sun RPC without charge, but are not authorized
00007  * to license or distribute it to anyone else except as part of a product or
00008  * program developed by the user.
00009  *
00010  * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
00011  * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
00012  * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
00013  *
00014  * Sun RPC is provided with no support and without any obligation on the
00015  * part of Sun Microsystems, Inc. to assist in its use, correction,
00016  * modification or enhancement.
00017  *
00018  * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
00019  * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
00020  * OR ANY PART THEREOF.
00021  *
00022  * In no event will Sun Microsystems, Inc. be liable for any lost revenue
00023  * or profits or other special, indirect and consequential damages, even if
00024  * Sun has been advised of the possibility of such damages.
00025  *
00026  * Sun Microsystems, Inc.
00027  * 2550 Garcia Avenue
00028  * Mountain View, California  94043
00029  */
00030 
00031 /*
00032  * clnt.h - Client side remote procedure call interface.
00033  *
00034  * Copyright (C) 1984, Sun Microsystems, Inc.
00035  */
00036 
00037 #ifndef _RPC_CLNT_H
00038 #define _RPC_CLNT_H  1
00039 
00040 #include <features.h>
00041 #include <sys/types.h>
00042 #include <rpc/types.h>
00043 #include <rpc/auth.h>
00044 #include <sys/un.h>
00045 
00046 __BEGIN_DECLS
00047 
00048 /*
00049  * Rpc calls return an enum clnt_stat.  This should be looked at more,
00050  * since each implementation is required to live with this (implementation
00051  * independent) list of errors.
00052  */
00053 enum clnt_stat {
00054        RPC_SUCCESS=0,                     /* call succeeded */
00055        /*
00056         * local errors
00057         */
00058        RPC_CANTENCODEARGS=1,              /* can't encode arguments */
00059        RPC_CANTDECODERES=2,        /* can't decode results */
00060        RPC_CANTSEND=3,                    /* failure in sending call */
00061        RPC_CANTRECV=4,                    /* failure in receiving result */
00062        RPC_TIMEDOUT=5,                    /* call timed out */
00063        /*
00064         * remote errors
00065         */
00066        RPC_VERSMISMATCH=6,         /* rpc versions not compatible */
00067        RPC_AUTHERROR=7,            /* authentication error */
00068        RPC_PROGUNAVAIL=8,          /* program not available */
00069        RPC_PROGVERSMISMATCH=9,            /* program version mismatched */
00070        RPC_PROCUNAVAIL=10,         /* procedure unavailable */
00071        RPC_CANTDECODEARGS=11,             /* decode arguments error */
00072        RPC_SYSTEMERROR=12,         /* generic "other problem" */
00073        RPC_NOBROADCAST = 21,              /* Broadcasting not supported */
00074        /*
00075         * callrpc & clnt_create errors
00076         */
00077        RPC_UNKNOWNHOST=13,         /* unknown host name */
00078        RPC_UNKNOWNPROTO=17,        /* unknown protocol */
00079        RPC_UNKNOWNADDR = 19,              /* Remote address unknown */
00080 
00081        /*
00082         * rpcbind errors
00083         */
00084        RPC_RPCBFAILURE=14,         /* portmapper failed in its call */
00085 #define RPC_PMAPFAILURE RPC_RPCBFAILURE
00086        RPC_PROGNOTREGISTERED=15,   /* remote program is not registered */
00087        RPC_N2AXLATEFAILURE = 22,   /* Name to addr translation failed */
00088        /*
00089         * unspecified error
00090         */
00091        RPC_FAILED=16,
00092        RPC_INTR=18,
00093        RPC_TLIERROR=20,
00094        RPC_UDERROR=23,
00095         /*
00096          * asynchronous errors
00097          */
00098         RPC_INPROGRESS = 24,
00099         RPC_STALERACHANDLE = 25
00100 };
00101 
00102 
00103 /*
00104  * Error info.
00105  */
00106 struct rpc_err {
00107   enum clnt_stat re_status;
00108   union {
00109     int RE_errno;           /* related system error */
00110     enum auth_stat RE_why;  /* why the auth error occurred */
00111     struct {
00112       u_long low;           /* lowest verion supported */
00113       u_long high;          /* highest verion supported */
00114     } RE_vers;
00115     struct {                /* maybe meaningful if RPC_FAILED */
00116       long s1;
00117       long s2;
00118     } RE_lb;                /* life boot & debugging only */
00119   } ru;
00120 #define       re_errno      ru.RE_errno
00121 #define       re_why        ru.RE_why
00122 #define       re_vers              ru.RE_vers
00123 #define       re_lb         ru.RE_lb
00124 };
00125 
00126 
00127 /*
00128  * Client rpc handle.
00129  * Created by individual implementations, see e.g. rpc_udp.c.
00130  * Client is responsible for initializing auth, see e.g. auth_none.c.
00131  */
00132 typedef struct CLIENT CLIENT;
00133 struct CLIENT {
00134   AUTH *cl_auth;             /* authenticator */
00135   struct clnt_ops {
00136     enum clnt_stat (*cl_call) (CLIENT *, u_long, xdrproc_t, caddr_t, xdrproc_t,
00137                             caddr_t, struct timeval);
00138                                    /* call remote procedure */
00139     void (*cl_abort) (void);       /* abort a call */
00140     void (*cl_geterr) (CLIENT *, struct rpc_err *);
00141                             /* get specific error code */
00142     bool_t (*cl_freeres) (CLIENT *, xdrproc_t, caddr_t);
00143                             /* frees results */
00144     void (*cl_destroy) (CLIENT *); /* destroy this structure */
00145     bool_t (*cl_control) (CLIENT *, int, char *);
00146                             /* the ioctl() of rpc */
00147   } *cl_ops;
00148   caddr_t cl_private;              /* private stuff */
00149 };
00150 
00151 
00152 /*
00153  * client side rpc interface ops
00154  *
00155  * Parameter types are:
00156  *
00157  */
00158 
00159 /*
00160  * enum clnt_stat
00161  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
00162  *     CLIENT *rh;
00163  *     u_long proc;
00164  *     xdrproc_t xargs;
00165  *     caddr_t argsp;
00166  *     xdrproc_t xres;
00167  *     caddr_t resp;
00168  *     struct timeval timeout;
00169  */
00170 #define       CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)     \
00171        ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
00172 #define       clnt_call(rh, proc, xargs, argsp, xres, resp, secs)     \
00173        ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
00174 
00175 /*
00176  * void
00177  * CLNT_ABORT(rh);
00178  *     CLIENT *rh;
00179  */
00180 #define       CLNT_ABORT(rh)       ((*(rh)->cl_ops->cl_abort)(rh))
00181 #define       clnt_abort(rh)       ((*(rh)->cl_ops->cl_abort)(rh))
00182 
00183 /*
00184  * struct rpc_err
00185  * CLNT_GETERR(rh);
00186  *     CLIENT *rh;
00187  */
00188 #define       CLNT_GETERR(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
00189 #define       clnt_geterr(rh,errp) ((*(rh)->cl_ops->cl_geterr)(rh, errp))
00190 
00191 
00192 /*
00193  * bool_t
00194  * CLNT_FREERES(rh, xres, resp);
00195  *     CLIENT *rh;
00196  *     xdrproc_t xres;
00197  *     caddr_t resp;
00198  */
00199 #define       CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
00200 #define       clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
00201 
00202 /*
00203  * bool_t
00204  * CLNT_CONTROL(cl, request, info)
00205  *      CLIENT *cl;
00206  *      u_int request;
00207  *      char *info;
00208  */
00209 #define       CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
00210 #define       clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
00211 
00212 /*
00213  * control operations that apply to all transports
00214  *
00215  * Note: options marked XXX are no-ops in this implementation of RPC.
00216  * The are present in TI-RPC but can't be implemented here since they
00217  * depend on the presence of STREAMS/TLI, which we don't have.
00218  */
00219 #define CLSET_TIMEOUT        1    /* set timeout (timeval) */
00220 #define CLGET_TIMEOUT        2    /* get timeout (timeval) */
00221 #define CLGET_SERVER_ADDR    3    /* get server's address (sockaddr) */
00222 #define CLGET_FD             6    /* get connections file descriptor */
00223 #define CLGET_SVC_ADDR       7    /* get server's address (netbuf)      XXX */
00224 #define CLSET_FD_CLOSE       8    /* close fd while clnt_destroy */
00225 #define CLSET_FD_NCLOSE      9    /* Do not close fd while clnt_destroy*/
00226 #define CLGET_XID            10   /* Get xid */
00227 #define CLSET_XID            11   /* Set xid */
00228 #define CLGET_VERS           12   /* Get version number */
00229 #define CLSET_VERS           13   /* Set version number */
00230 #define CLGET_PROG           14   /* Get program number */
00231 #define CLSET_PROG           15   /* Set program number */
00232 #define CLSET_SVC_ADDR       16   /* get server's address (netbuf)      XXX */
00233 #define CLSET_PUSH_TIMOD     17   /* push timod if not already present  XXX */
00234 #define CLSET_POP_TIMOD      18   /* pop timod                          XXX */
00235 /*
00236  * Connectionless only control operations
00237  */
00238 #define CLSET_RETRY_TIMEOUT 4      /* set retry timeout (timeval) */
00239 #define CLGET_RETRY_TIMEOUT 5      /* get retry timeout (timeval) */
00240 
00241 /*
00242  * void
00243  * CLNT_DESTROY(rh);
00244  *     CLIENT *rh;
00245  */
00246 #define       CLNT_DESTROY(rh)     ((*(rh)->cl_ops->cl_destroy)(rh))
00247 #define       clnt_destroy(rh)     ((*(rh)->cl_ops->cl_destroy)(rh))
00248 
00249 
00250 /*
00251  * RPCTEST is a test program which is accessible on every rpc
00252  * transport/port.  It is used for testing, performance evaluation,
00253  * and network administration.
00254  */
00255 
00256 #define RPCTEST_PROGRAM            ((u_long)1)
00257 #define RPCTEST_VERSION            ((u_long)1)
00258 #define RPCTEST_NULL_PROC   ((u_long)2)
00259 #define RPCTEST_NULL_BATCH_PROC    ((u_long)3)
00260 
00261 /*
00262  * By convention, procedure 0 takes null arguments and returns them
00263  */
00264 
00265 #define NULLPROC ((u_long)0)
00266 
00267 /*
00268  * Below are the client handle creation routines for the various
00269  * implementations of client side rpc.  They can return NULL if a
00270  * creation failure occurs.
00271  */
00272 
00273 /*
00274  * Memory based rpc (for speed check and testing)
00275  * CLIENT *
00276  * clntraw_create(prog, vers)
00277  *     u_long prog;
00278  *     u_long vers;
00279  */
00280 extern CLIENT *clntraw_create (__const u_long __prog, __const u_long __vers)
00281      __THROW;
00282 
00283 
00284 /*
00285  * Generic client creation routine. Supported protocols are "udp", "tcp" and
00286  * "unix"
00287  * CLIENT *
00288  * clnt_create(host, prog, vers, prot)
00289  *     char *host;   -- hostname
00290  *     u_long prog;  -- program number
00291  *     u_ong vers;   -- version number
00292  *     char *prot;   -- protocol
00293  */
00294 extern CLIENT *clnt_create (__const char *__host, __const u_long __prog,
00295                          __const u_long __vers, __const char *__prot)
00296      __THROW;
00297 
00298 
00299 /*
00300  * TCP based rpc
00301  * CLIENT *
00302  * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
00303  *     struct sockaddr_in *raddr;
00304  *     u_long prog;
00305  *     u_long version;
00306  *     register int *sockp;
00307  *     u_int sendsz;
00308  *     u_int recvsz;
00309  */
00310 extern CLIENT *clnttcp_create (struct sockaddr_in *__raddr, u_long __prog,
00311                             u_long __version, int *__sockp, u_int __sendsz,
00312                             u_int __recvsz) __THROW;
00313 
00314 /*
00315  * UDP based rpc.
00316  * CLIENT *
00317  * clntudp_create(raddr, program, version, wait, sockp)
00318  *     struct sockaddr_in *raddr;
00319  *     u_long program;
00320  *     u_long version;
00321  *     struct timeval wait_resend;
00322  *     int *sockp;
00323  *
00324  * Same as above, but you specify max packet sizes.
00325  * CLIENT *
00326  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
00327  *     struct sockaddr_in *raddr;
00328  *     u_long program;
00329  *     u_long version;
00330  *     struct timeval wait_resend;
00331  *     int *sockp;
00332  *     u_int sendsz;
00333  *     u_int recvsz;
00334  */
00335 extern CLIENT *clntudp_create (struct sockaddr_in *__raddr, u_long __program,
00336                             u_long __version, struct timeval __wait_resend,
00337                             int *__sockp) __THROW;
00338 extern CLIENT *clntudp_bufcreate (struct sockaddr_in *__raddr,
00339                               u_long __program, u_long __version,
00340                               struct timeval __wait_resend, int *__sockp,
00341                               u_int __sendsz, u_int __recvsz) __THROW;
00342 
00343 
00344 
00345 
00346 /*
00347  * AF_UNIX based rpc
00348  * CLIENT *
00349  * clntunix_create(raddr, prog, vers, sockp, sendsz, recvsz)
00350  *      struct sockaddr_un *raddr;
00351  *      u_long prog;
00352  *      u_long version;
00353  *      register int *sockp;
00354  *      u_int sendsz;
00355  *      u_int recvsz;
00356  */
00357 extern CLIENT *clntunix_create  (struct sockaddr_un *__raddr, u_long __program,
00358                              u_long __version, int *__sockp,
00359                              u_int __sendsz, u_int __recvsz) __THROW;
00360 
00361 
00362 extern int callrpc (__const char *__host, __const u_long __prognum,
00363                   __const u_long __versnum, __const u_long __procnum,
00364                   __const xdrproc_t __inproc, __const char *__in,
00365                   __const xdrproc_t __outproc, char *__out) __THROW;
00366 extern int _rpc_dtablesize (void) __THROW;
00367 
00368 /*
00369  * Print why creation failed
00370  */
00371 extern void clnt_pcreateerror (__const char *__msg);    /* stderr */
00372 extern char *clnt_spcreateerror(__const char *__msg) __THROW;  /* string */
00373 
00374 /*
00375  * Like clnt_perror(), but is more verbose in its output
00376  */
00377 extern void clnt_perrno (enum clnt_stat __num);         /* stderr */
00378 
00379 /*
00380  * Print an English error message, given the client error code
00381  */
00382 extern void clnt_perror (CLIENT *__clnt, __const char *__msg);
00383                                                  /* stderr */
00384 extern char *clnt_sperror (CLIENT *__clnt, __const char *__msg) __THROW;
00385                                                  /* string */
00386 
00387 /*
00388  * If a creation fails, the following allows the user to figure out why.
00389  */
00390 struct rpc_createerr {
00391        enum clnt_stat cf_stat;
00392        struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
00393 };
00394 
00395 extern struct rpc_createerr rpc_createerr;
00396 
00397 
00398 
00399 /*
00400  * Copy error message to buffer.
00401  */
00402 extern char *clnt_sperrno (enum clnt_stat __num) __THROW;      /* string */
00403 
00404 /*
00405  * get the port number on the host for the rpc program,version and proto
00406  */
00407 extern int getrpcport (__const char * __host, u_long __prognum,
00408                      u_long __versnum, u_int proto) __THROW;
00409 
00410 /*
00411  * get the local host's IP address without consulting
00412  * name service library functions
00413  */
00414 extern void get_myaddress (struct sockaddr_in *) __THROW;
00415 
00416 #define UDPMSGSIZE   8800   /* rpc imposed limit on udp msg size */
00417 #define RPCSMALLMSGSIZE     400    /* a more reasonable packet size */
00418 
00419 __END_DECLS
00420 
00421 #endif /* rpc/clnt.h */