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 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /** Max number of bytes (i.e., tokens) */
  32 #define LIBDO_MAX_BYTES      256
  33
  34 /** A convienance value for clients of this library. Feel free to change
  35  * if you plan to use a larger buffer. You can also safely ignore it, as
  36  * libdisorder does not use this value internally; it relies on the
  37  * client-supplied `length' parameter.
  38  *
  39  * NB: Might become deprecated because it is potentially misleading and
  40  * has zero relationship to any library internal state.
  41  */
  42 #define LIBDO_BUFFER_LEN   16384
  43
  44 /**
  45  * Given a pointer to an array of bytes, return a float indicating the
  46  * level of entropy in bits (a number between zero and eight),
  47  * assuming a space of 256 possible byte values. The second argument
  48  * indicates the number of bytes in the sequence. If this sequence
  49  * runs into unallocated memory, this function should fail with a
  50  * SIGSEGV.
  51  */
  52 float    shannon_H(char*, long long);
  53
  54 /** Report the number of (unique) tokens seen. This is _not_ the
  55     number of individual events seen. For example, if the library sees
  56     the string `aaab', the number of events is 4 and the number of
  57     tokens is 2. */
  58 int      get_num_tokens(void);
  59
  60 /** Returns maximum entropy for byte distributions log2(256)=8 bits*/
  61 float    get_max_entropy(void);
  62
  63 /** Returns the ratio of entropy to maxentropy */
  64 float    get_entropy_ratio(void);
  65
  66 #ifdef __cplusplus
  67 };
  68 #endif
  69
  70 #endif