projects.mako.cc - wikiq/blob - disorder.h

   1 /***************************************************************************
   2  *  libdisorder: A Library for Measuring Byte Stream Entropy
   3  *  Copyright (C) 2010 Michael E. Locasto
   4  *
   5  *  This program is free software; you can redistribute it and/or modify
   6  *  it under the terms of the GNU General Public License as published by
   7  *  the Free Software Foundation; either version 2 of the License, or
   8  *  (at your option) any later version.
   9  *
  10  *  This program is distributed in the hope that it will be useful, but
  11  *  WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  *  General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU General Public License
  16  *  along with this program; if not, write to the:
  17  *       Free Software Foundation, Inc.
  18  *       59 Temple Place, Suite 330
  19  *       Boston, MA  02111-1307  USA
  20  *
  21  * $Id$
  22  **************************************************************************/
  23
  24 #ifndef __DISORDER_H_
  25 #define __DISORDER_H_
  26
  27 /** Max number of bytes (i.e., tokens) */
  28 #define LIBDO_MAX_BYTES      256
  29
  30 /** A convienance value for clients of this library. Feel free to change
  31  * if you plan to use a larger buffer. You can also safely ignore it, as
  32  * libdisorder does not use this value internally; it relies on the
  33  * client-supplied `length' parameter.
  34  *
  35  * NB: Might become deprecated because it is potentially misleading and
  36  * has zero relationship to any library internal state.
  37  */
  38 #define LIBDO_BUFFER_LEN   16384
  39
  40 /**
  41  * Given a pointer to an array of bytes, return a float indicating the
  42  * level of entropy in bits (a number between zero and eight),
  43  * assuming a space of 256 possible byte values. The second argument
  44  * indicates the number of bytes in the sequence. If this sequence
  45  * runs into unallocated memory, this function should fail with a
  46  * SIGSEGV.
  47  */
  48 float    shannon_H(char*, long long);
  49
  50 /** Report the number of (unique) tokens seen. This is _not_ the
  51     number of individual events seen. For example, if the library sees
  52     the string `aaab', the number of events is 4 and the number of
  53     tokens is 2. */
  54 int      get_num_tokens(void);
  55
  56 /** Returns maximum entropy for byte distributions log2(256)=8 bits*/
  57 float    get_max_entropy(void);
  58
  59 /** Returns the ratio of entropy to maxentropy */
  60 float    get_entropy_ratio(void);
  61
  62 #endif