[become] / src / class.h

/* -*-c-*-
 *
 * $Id: class.h,v 1.4 1998/01/12 16:45:53 mdw Exp $
 *
 * Handling classes of things nicely
 *
 * (c) 1998 EBI
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of `become'
 *
 * `Become' is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * `Become' is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with `become'; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------*
 *
 * $Log: class.h,v $
 * Revision 1.4  1998/01/12 16:45:53  mdw
 * Fix copyright date.
 *
 * Revision 1.3  1997/09/17  10:14:56  mdw
 * Complete rewrite to support class trees.  Makes the behaviour of the set
 * operators much more logical.
 *
 * Revision 1.2  1997/08/04 10:24:21  mdw
 * Sources placed under CVS control.
 *
 * Revision 1.1  1997/07/21  13:47:52  mdw
 * Initial revision
 *
 */

#ifndef CLASS_H
#define CLASS_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Required headers --------------------------------------------------*/

#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>

#ifndef SYM_H
#  include "sym.h"
#endif

/*----- Data structures ---------------------------------------------------*/

/* --- Class types --- */

enum {

  /* --- Data types (user visible) --- *
   *
   * These bits encode what the user can think of as `types'.  They get used
   * for typechecking and things.
   */

  clType_user = 0x01,                   /* Class of users */
  clType_command = 0x02,                /* Class of command strings */
  clType_host = 0x04,                   /* Class of host names */
  clType_all = 0x0F,                    /* All of the above (maintain me) */
  clType_mask = 0x0F,                   /* Mask for type flags */

  /* --- Node types --- *
   *
   * A class actually looks suspiciously like a tree once things start
   * getting complicated.  These bits encode the type of node we've got here.
   */

  clNode_any = 0x10,                    /* Magic type for the `all' class */
  clNode_immed = 0x20,                  /* Immediate data item */
  clNode_hash = 0x30,                   /* Hashtable of values */
  clNode_union = 0x40,                  /* Union of two classes */
  clNode_binop = 0x50,                  /* Binary operations start here */
  clNode_diff = 0x50,                   /* Difference of two classes */
  clNode_isect = 0x60,                  /* Intersection of two classes */
  clNode_mask = 0xF0,                   /* Mask for picking these out */

  /* --- Other useful flags --- */

  clFlag_friendly = 0x100               /* Item can be hashed with others */
};

/* --- Class block --- */

typedef struct class_node {
  unsigned type;                        /* Class and node type, and flags */
  unsigned ref;                         /* Reference count */
  union {
    uid_t u;                            /* Immediate user id number */
    char *s;                            /* Immediate string value */
    sym_table t;                        /* Hash table for this class */
    struct {
      struct class_node *l, *r;         /* Left and right operands */
    } c;                                /* Class operands for binops */
  } v;                                  /* Value of this class node */
} class_node;

/*----- Global variables --------------------------------------------------*/

extern class_node *class_all;           /* The match-everything class */
extern class_node *class_none;          /* The match-nothing class */

/*----- Functions provided ------------------------------------------------*/

/* --- @class_fromString@ --- *
 *
 * Arguments:   @unsigned type@ = a type field
 *              @const char *s@ = pointer to string to copy
 *
 * Returns:     A pointer to a class node containing that string, typed to
 *              be the right thing.
 *
 * Use:         Given a string, wrap a class node around it.  The node has
 *              one reference (the one you get returned).  The string is
 *              copied, so you can get rid of your original one if you like.
 */

extern class_node *class_fromString(unsigned /*type*/, const char */*s*/);

/* --- @class_fromUser@ --- *
 *
 * Arguments:   @unsigned type@ = a type field
 *              @uid_t u@ = a user-id number
 *
 * Returns:     A pointer to a class node containing the uid, typed to be
 *              the thing you asked for.  Hopefully this will be
 *              @clType_user@.
 *
 * Use:         Given a uid, wrap a class node around it.
 */

extern class_node *class_fromUser(unsigned /*type*/, uid_t /*u*/);

/* --- @class_inc@ --- *
 *
 * Arguments:   @class_node *c@ = pointer to a class block
 *
 * Returns:     ---
 *
 * Use:         Adds a reference to the class definition.
 */

extern void class_inc(class_node */*c*/);

/* --- @class_dec@ --- *
 *
 * Arguments:   @class_node *c@ = pointer to a class block
 *
 * Returns:     ---
 *
 * Use:         Removes a reference to a class block.
 */

extern void class_dec(class_node */*c*/);

/* --- @class_mod@ --- *
 *
 * Arguments:   @class_node *c@ = pointer to a class node
 *
 * Returns:     A pointer to a class node, maybe the same one, maybe not,
 *              with a reference count of 1, containing the same data.
 *
 * Use:         Gives you a node which you can modify.  Don't call this
 *              for @class_all@ or @class_none@.
 */

extern class_node *class_mod(class_node */*c*/);

/* --- @class_union@ --- *
 *
 * Arguments:   @class_node *l@ = left argument
 *              @class_node *r@ = right argument
 *
 * Returns:     A class node representing the union of the two classes.
 *
 * Use:         Performs the union operation on classes.  If the types don't
 *              match, then a null pointer is returned.  Both @l@ and @r@
 *              may be modified, and will be decremented before they get
 *              returned to you.  If you don't want that to happen, ensure
 *              that you've claimed a reference to the original versions.
 */

extern class_node *class_union(class_node */*l*/, class_node */*r*/);

/* --- @class_diff@ --- *
 *
 * Arguments:   @class_node *l@ = left argument
 *              @class_node *r@ = right argument
 *
 * Returns:     A class node representing the difference of the two classes.
 *
 * Use:         Performs the set difference operation on classes.  If the
 *              types don't match, then a null pointer is returned.  Both
 *              @l@ and @r@ may be modified, and will be decremented before
 *              they get returned to you.  If you don't want that to happen,
 *              ensure that you've claimed a reference to the original
 *              versions.
 */

extern class_node *class_diff(class_node */*l*/, class_node */*r*/);

/* --- @class_isect@ --- *
 *
 * Arguments:   @class_node *l@ = left argument
 *              @class_node *r@ = right argument
 *
 * Returns:     A class node representing the intersection of the two
 *              classes.
 *
 * Use:         Performs the intersecion operation on classes.  If the types
 *              don't match, then a null pointer is returned.  Both @l@ and
 *              @r@ may be modified, and will be decremented before they get
 *              returned to you.  If you don't want that to happen, ensure
 *              that you've claimed a reference to the original versions.
 */

extern class_node *class_isect(class_node */*l*/, class_node */*r*/);

/* --- @class_addUser@ --- *
 *
 * Arguments:   @class_node *c@ = pointer to a class node (may be null)
 *              @uid_t u@ = user id number
 *
 * Returns:     Pointer to the combined node.
 *
 * Use:         Adds a user to a node, maybe hashifying it.
 */

extern class_node *class_addUser(class_node */*c*/, uid_t /*u*/);

/* --- @class_addString@ --- *
 *
 * Arguments:   @class_node *c@ = pointer to a class node (may be null)
 *              @const char *s@ = pointer to a string
 *
 * Returns:     Pointer to the combined node.
 *
 * Use:         Adds a user to a node, maybe hashifying it.
 */

extern class_node *class_addString(class_node */*c*/, const char */*s*/);

/* --- @class_matchUser@ --- *
 *
 * Arguments:   @class_node *c@ = pointer to root class node
 *              @uid_t u@ = user id number
 *
 * Returns:     Nonzero if it matches, zero if it doesn't.
 *
 * Use:         Determines whether a user is matched by a class.  Assumes
 *              that the types are correct.
 */

extern int class_matchUser(class_node */*c*/, uid_t /*u*/);

/* --- @class_matchCommand@ --- *
 *
 * Arguments:   @class_node *c@ = pointer to root class node
 *              @const char *s@ = pointer to a string
 *
 * Returns:     Nonzero if it matches, zero if it doesn't.
 *
 * Use:         Determines whether a string is matched by a class.  Assumes
 *              that the types are correct.
 */

extern int class_matchCommand(class_node */*c*/, const char */*s*/);

/* --- @class_matchHost@ --- *
 *
 * Arguments:   @class_node *c@ = pointer to root class node
 *              @struct in_addr a@ = IP address to match
 *
 * Returns:     Nonzero if it matches, zero if it doesn't.
 *
 * Use:         Determines whether a host matches a host class.  Assumes
 *              that the types are correct.  The actual mechanism is a bit
 *              odd here, but I think this is the Right Thing.  At each stage
 *              I try to match %%@/all/%% of the possible names for the host.
 *              Thus host `splat' with address 1.2.3.4 would fail to match
 *              the class "1.2.*" - "splat".  This seems to be what the
 *              author intuitively expects.  It's just a bit weird.
 */

extern int class_matchHost(class_node */*c*/, struct in_addr /*a*/);

/* --- @class_dump@ --- *
 *
 * Argumemnts:  @class_node *c@ = pointer to root node
 *              @int indent@ = indent depth
 *
 * Returns:     ---
 *
 * Use:         Dumps a class to the trace output.
 */

extern void class_dump(class_node */*c*/, int /*indent*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif