chiark - git - mdw - become/blob - src/class.h

   1 /* -*-c-*-
   2  *
   3  * $Id: class.h,v 1.3 1997/09/17 10:14:56 mdw Exp $
   4  *
   5  * Handling classes of things nicely
   6  *
   7  * (c) 1997 EBI
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of `become'
  13  *
  14  * `Become' is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 2 of the License, or
  17  * (at your option) any later version.
  18  *
  19  * `Become' is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License
  25  * along with `become'; if not, write to the Free Software Foundation,
  26  * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  27  */
  28
  29 /*----- Revision history --------------------------------------------------*
  30  *
  31  * $Log: class.h,v $
  32  * Revision 1.3  1997/09/17 10:14:56  mdw
  33  * Complete rewrite to support class trees.  Makes the behaviour of the set
  34  * operators much more logical.
  35  *
  36  * Revision 1.2  1997/08/04 10:24:21  mdw
  37  * Sources placed under CVS control.
  38  *
  39  * Revision 1.1  1997/07/21  13:47:52  mdw
  40  * Initial revision
  41  *
  42  */
  43
  44 #ifndef CLASS_H
  45 #define CLASS_H
  46
  47 #ifdef __cplusplus
  48   extern "C" {
  49 #endif
  50
  51 /*----- Required headers --------------------------------------------------*/
  52
  53 #include <sys/types.h>
  54 #include <sys/socket.h>
  55 #include <netinet/in.h>
  56 #include <arpa/inet.h>
  57
  58 #ifndef SYM_H
  59 #  include "sym.h"
  60 #endif
  61
  62 /*----- Data structures ---------------------------------------------------*/
  63
  64 /* --- Class types --- */
  65
  66 enum {
  67
  68   /* --- Data types (user visible) --- *
  69    *
  70    * These bits encode what the user can think of as `types'.  They get used
  71    * for typechecking and things.
  72    */
  73
  74   clType_user = 0x01,                   /* Class of users */
  75   clType_command = 0x02,                /* Class of command strings */
  76   clType_host = 0x04,                   /* Class of host names */
  77   clType_all = 0x0F,                    /* All of the above (maintain me) */
  78   clType_mask = 0x0F,                   /* Mask for type flags */
  79
  80   /* --- Node types --- *
  81    *
  82    * A class actually looks suspiciously like a tree once things start
  83    * getting complicated.  These bits encode the type of node we've got here.
  84    */
  85
  86   clNode_any = 0x10,                    /* Magic type for the `all' class */
  87   clNode_immed = 0x20,                  /* Immediate data item */
  88   clNode_hash = 0x30,                   /* Hashtable of values */
  89   clNode_union = 0x40,                  /* Union of two classes */
  90   clNode_binop = 0x50,                  /* Binary operations start here */
  91   clNode_diff = 0x50,                   /* Difference of two classes */
  92   clNode_isect = 0x60,                  /* Intersection of two classes */
  93   clNode_mask = 0xF0,                   /* Mask for picking these out */
  94
  95   /* --- Other useful flags --- */
  96
  97   clFlag_friendly = 0x100               /* Item can be hashed with others */
  98 };
  99
 100 /* --- Class block --- */
 101
 102 typedef struct class_node {
 103   unsigned type;                        /* Class and node type, and flags */
 104   unsigned ref;                         /* Reference count */
 105   union {
 106     uid_t u;                            /* Immediate user id number */
 107     char *s;                            /* Immediate string value */
 108     sym_table t;                        /* Hash table for this class */
 109     struct {
 110       struct class_node *l, *r;         /* Left and right operands */
 111     } c;                                /* Class operands for binops */
 112   } v;                                  /* Value of this class node */
 113 } class_node;
 114
 115 /*----- Global variables --------------------------------------------------*/
 116
 117 extern class_node *class_all;           /* The match-everything class */
 118 extern class_node *class_none;          /* The match-nothing class */
 119
 120 /*----- Functions provided ------------------------------------------------*/
 121
 122 /* --- @class_fromString@ --- *
 123  *
 124  * Arguments:   @unsigned type@ = a type field
 125  *              @const char *s@ = pointer to string to copy
 126  *
 127  * Returns:     A pointer to a class node containing that string, typed to
 128  *              be the right thing.
 129  *
 130  * Use:         Given a string, wrap a class node around it.  The node has
 131  *              one reference (the one you get returned).  The string is
 132  *              copied, so you can get rid of your original one if you like.
 133  */
 134
 135 extern class_node *class_fromString(unsigned /*type*/, const char */*s*/);
 136
 137 /* --- @class_fromUser@ --- *
 138  *
 139  * Arguments:   @unsigned type@ = a type field
 140  *              @uid_t u@ = a user-id number
 141  *
 142  * Returns:     A pointer to a class node containing the uid, typed to be
 143  *              the thing you asked for.  Hopefully this will be
 144  *              @clType_user@.
 145  *
 146  * Use:         Given a uid, wrap a class node around it.
 147  */
 148
 149 extern class_node *class_fromUser(unsigned /*type*/, uid_t /*u*/);
 150
 151 /* --- @class_inc@ --- *
 152  *
 153  * Arguments:   @class_node *c@ = pointer to a class block
 154  *
 155  * Returns:     ---
 156  *
 157  * Use:         Adds a reference to the class definition.
 158  */
 159
 160 extern void class_inc(class_node */*c*/);
 161
 162 /* --- @class_dec@ --- *
 163  *
 164  * Arguments:   @class_node *c@ = pointer to a class block
 165  *
 166  * Returns:     ---
 167  *
 168  * Use:         Removes a reference to a class block.
 169  */
 170
 171 extern void class_dec(class_node */*c*/);
 172
 173 /* --- @class_mod@ --- *
 174  *
 175  * Arguments:   @class_node *c@ = pointer to a class node
 176  *
 177  * Returns:     A pointer to a class node, maybe the same one, maybe not,
 178  *              with a reference count of 1, containing the same data.
 179  *
 180  * Use:         Gives you a node which you can modify.  Don't call this
 181  *              for @class_all@ or @class_none@.
 182  */
 183
 184 extern class_node *class_mod(class_node */*c*/);
 185
 186 /* --- @class_union@ --- *
 187  *
 188  * Arguments:   @class_node *l@ = left argument
 189  *              @class_node *r@ = right argument
 190  *
 191  * Returns:     A class node representing the union of the two classes.
 192  *
 193  * Use:         Performs the union operation on classes.  If the types don't
 194  *              match, then a null pointer is returned.  Both @l@ and @r@
 195  *              may be modified, and will be decremented before they get
 196  *              returned to you.  If you don't want that to happen, ensure
 197  *              that you've claimed a reference to the original versions.
 198  */
 199
 200 extern class_node *class_union(class_node */*l*/, class_node */*r*/);
 201
 202 /* --- @class_diff@ --- *
 203  *
 204  * Arguments:   @class_node *l@ = left argument
 205  *              @class_node *r@ = right argument
 206  *
 207  * Returns:     A class node representing the difference of the two classes.
 208  *
 209  * Use:         Performs the set difference operation on classes.  If the
 210  *              types don't match, then a null pointer is returned.  Both
 211  *              @l@ and @r@ may be modified, and will be decremented before
 212  *              they get returned to you.  If you don't want that to happen,
 213  *              ensure that you've claimed a reference to the original
 214  *              versions.
 215  */
 216
 217 extern class_node *class_diff(class_node */*l*/, class_node */*r*/);
 218
 219 /* --- @class_isect@ --- *
 220  *
 221  * Arguments:   @class_node *l@ = left argument
 222  *              @class_node *r@ = right argument
 223  *
 224  * Returns:     A class node representing the intersection of the two
 225  *              classes.
 226  *
 227  * Use:         Performs the intersecion operation on classes.  If the types
 228  *              don't match, then a null pointer is returned.  Both @l@ and
 229  *              @r@ may be modified, and will be decremented before they get
 230  *              returned to you.  If you don't want that to happen, ensure
 231  *              that you've claimed a reference to the original versions.
 232  */
 233
 234 extern class_node *class_isect(class_node */*l*/, class_node */*r*/);
 235
 236 /* --- @class_addUser@ --- *
 237  *
 238  * Arguments:   @class_node *c@ = pointer to a class node (may be null)
 239  *              @uid_t u@ = user id number
 240  *
 241  * Returns:     Pointer to the combined node.
 242  *
 243  * Use:         Adds a user to a node, maybe hashifying it.
 244  */
 245
 246 extern class_node *class_addUser(class_node */*c*/, uid_t /*u*/);
 247
 248 /* --- @class_addString@ --- *
 249  *
 250  * Arguments:   @class_node *c@ = pointer to a class node (may be null)
 251  *              @const char *s@ = pointer to a string
 252  *
 253  * Returns:     Pointer to the combined node.
 254  *
 255  * Use:         Adds a user to a node, maybe hashifying it.
 256  */
 257
 258 extern class_node *class_addString(class_node */*c*/, const char */*s*/);
 259
 260 /* --- @class_matchUser@ --- *
 261  *
 262  * Arguments:   @class_node *c@ = pointer to root class node
 263  *              @uid_t u@ = user id number
 264  *
 265  * Returns:     Nonzero if it matches, zero if it doesn't.
 266  *
 267  * Use:         Determines whether a user is matched by a class.  Assumes
 268  *              that the types are correct.
 269  */
 270
 271 extern int class_matchUser(class_node */*c*/, uid_t /*u*/);
 272
 273 /* --- @class_matchCommand@ --- *
 274  *
 275  * Arguments:   @class_node *c@ = pointer to root class node
 276  *              @const char *s@ = pointer to a string
 277  *
 278  * Returns:     Nonzero if it matches, zero if it doesn't.
 279  *
 280  * Use:         Determines whether a string is matched by a class.  Assumes
 281  *              that the types are correct.
 282  */
 283
 284 extern int class_matchCommand(class_node */*c*/, const char */*s*/);
 285
 286 /* --- @class_matchHost@ --- *
 287  *
 288  * Arguments:   @class_node *c@ = pointer to root class node
 289  *              @struct in_addr a@ = IP address to match
 290  *
 291  * Returns:     Nonzero if it matches, zero if it doesn't.
 292  *
 293  * Use:         Determines whether a host matches a host class.  Assumes
 294  *              that the types are correct.  The actual mechanism is a bit
 295  *              odd here, but I think this is the Right Thing.  At each stage
 296  *              I try to match %%@/all/%% of the possible names for the host.
 297  *              Thus host `splat' with address 1.2.3.4 would fail to match
 298  *              the class "1.2.*" - "splat".  This seems to be what the
 299  *              author intuitively expects.  It's just a bit weird.
 300  */
 301
 302 extern int class_matchHost(class_node */*c*/, struct in_addr /*a*/);
 303
 304 /* --- @class_dump@ --- *
 305  *
 306  * Argumemnts:  @class_node *c@ = pointer to root node
 307  *              @int indent@ = indent depth
 308  *
 309  * Returns:     ---
 310  *
 311  * Use:         Dumps a class to the trace output.
 312  */
 313
 314 extern void class_dump(class_node */*c*/, int /*indent*/);
 315
 316 /*----- That's all, folks -------------------------------------------------*/
 317
 318 #ifdef __cplusplus
 319   }
 320 #endif
 321
 322 #endif
 323