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

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