path: root/epan/emem.h

/* emem.h
 * Definitions for Wireshark memory management and garbage collection
 * Ronnie Sahlberg 2005
 *
 * $Id$
 *
 * Wireshark - Network traffic analyzer
 * By Gerald Combs <gerald@wireshark.org>
 * Copyright 1998 Gerald Combs
 *
 * This program 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.
 *
 * This program 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 this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */

#ifndef __EMEM_H__
#define __EMEM_H__

/** @file
 */
/**  Initialize all the memory allocation pools described below.
 *  This function must be called once when *shark initialize to set up the
 *  required structures.
 */
void emem_init(void);

/* Functions for handling memory allocation and garbage collection with
 * a packet lifetime scope.
 * These functions are used to allocate memory that will only remain persistent
 * until Wireshark starts dissecting the next packet in the list.
 * Everytime Wireshark starts decoding the next packet all memory allocated
 * through these functions will be released back to the free pool.
 *
 * These functions are very fast and offer automatic garbage collection:
 * Everytime a new packet is dissected, all memory allocations done in
 * the previous packet is freed.
 */

/** Allocate memory with a packet lifetime scope */
void *ep_alloc(size_t size) G_GNUC_MALLOC;
#define ep_new(type) ((type*)ep_alloc(sizeof(type)))

/** Allocate memory with a packet lifetime scope and fill it with zeros*/
void* ep_alloc0(size_t size) G_GNUC_MALLOC;
#define ep_new0(type) ((type*)ep_alloc0(sizeof(type)))

/** Duplicate a string with a packet lifetime scope */
gchar* ep_strdup(const gchar* src) G_GNUC_MALLOC;

/** Duplicate at most n characters of a string with a packet lifetime scope */
gchar* ep_strndup(const gchar* src, size_t len) G_GNUC_MALLOC;

/** Duplicate a buffer with a packet lifetime scope */
void* ep_memdup(const void* src, size_t len) G_GNUC_MALLOC;

/** Create a formatted string with a packet lifetime scope */
gchar* ep_strdup_vprintf(const gchar* fmt, va_list ap) G_GNUC_MALLOC;
gchar* ep_strdup_printf(const gchar* fmt, ...)
     G_GNUC_MALLOC G_GNUC_PRINTF(1, 2);

gchar *ep_strconcat(const gchar *string, ...) G_GNUC_MALLOC G_GNUC_NULL_TERMINATED;

/** allocates with a packet lifetime scope an array of type made of num elements */
#define ep_alloc_array(type,num) (type*)ep_alloc(sizeof(type)*(num))

/** allocates with a packet lifetime scope an array of type made of num elements,
 * initialised to zero.
 */
#define ep_alloc_array0(type,num) (type*)ep_alloc0(sizeof(type)*(num))

/**
 * Splits a string into a maximum of max_tokens pieces, using the given
 * delimiter. If max_tokens is reached, the remainder of string is appended
 * to the last token. Consecutive delimiters are treated as a single delimiter.
 *
 * The vector and all the strings are allocated with packet lifetime scope
 */
gchar** ep_strsplit(const gchar* string, const gchar* delimiter, int max_tokens);

/** release all memory allocated in the previous packet dissection */
void ep_free_all(void);


/** a stack implemented using ephemeral allocators */

typedef struct _ep_stack_frame_t** ep_stack_t;

struct _ep_stack_frame_t {
    void* payload;
    struct _ep_stack_frame_t* below;
    struct _ep_stack_frame_t* above;
};

/**
 * creates an empty stack with a packet lifetime scope
 */
ep_stack_t ep_stack_new(void) G_GNUC_MALLOC;

/**
 * pushes item into stack, returns item
 */
void* ep_stack_push(ep_stack_t stack, void* item);

/**
 * pops an item from the stack
 */
void* ep_stack_pop(ep_stack_t stack);

/**
 * returns the item on top of the stack without popping it
 */
#define ep_stack_peek(stack) ((*(stack))->payload)


/* Functions for handling memory allocation and garbage collection with
 * a capture lifetime scope.
 * These functions are used to allocate memory that will only remain persistent
 * until Wireshark opens a new capture or capture file.
 * Everytime Wireshark starts a new capture or opens a new capture file
 * all the data allocated through these functions will be released back
 * to the free pool.
 *
 * These functions are very fast and offer automatic garbage collection.
 */

/** Allocate memory with a capture lifetime scope */
void *se_alloc(size_t size) G_GNUC_MALLOC;
#define se_new(type) ((type*)se_alloc(sizeof(type)))

/** Allocate memory with a capture lifetime scope and fill it with zeros*/
void* se_alloc0(size_t size) G_GNUC_MALLOC;
#define se_new0(type) ((type*)se_alloc0(sizeof(type)))

/** Duplicate a string with a capture lifetime scope */
gchar* se_strdup(const gchar* src) G_GNUC_MALLOC;

/** Duplicate at most n characters of a string with a capture lifetime scope */
gchar* se_strndup(const gchar* src, size_t len) G_GNUC_MALLOC;

/** Duplicate a buffer with a capture lifetime scope */
void* se_memdup(const void* src, size_t len) G_GNUC_MALLOC;

/* Create a formatted string with a capture lifetime scope */
gchar* se_strdup_vprintf(const gchar* fmt, va_list ap) G_GNUC_MALLOC;
gchar* se_strdup_printf(const gchar* fmt, ...)
     G_GNUC_MALLOC G_GNUC_PRINTF(1, 2);

/** allocates with a capture lifetime scope an array of type made of num elements */
#define se_alloc_array(type,num) (type*)se_alloc(sizeof(type)*(num))

/** release all memory allocated */
void se_free_all(void);

/**************************************************************
 * slab allocator
 **************************************************************/
struct _emem_chunk_t;

/* Macros to initialize ws_memory_slab */
/* XXX, is G_MEM_ALIGN enough? http://mail.gnome.org/archives/gtk-devel-list/2004-December/msg00091.html */
#define WS_MEMORY_SLAB_INIT(type, count) { ((sizeof(type) + (G_MEM_ALIGN - 1)) & ~(G_MEM_ALIGN - 1)), count, NULL, NULL }
#define WS_MEMORY_SLAB_INIT_UNALIGNED(size, count) { size, count, NULL, NULL }

struct ws_memory_slab {
	const gint item_size;
	const gint count;

	struct _emem_chunk_t *chunk_list;
	void *freed;
};

void *sl_alloc(struct ws_memory_slab *mem_chunk);
void *sl_alloc0(struct ws_memory_slab *mem_chunk);
void sl_free(struct ws_memory_slab *mem_chunk, gpointer ptr);

/** release all memory allocated */
void sl_free_all(struct ws_memory_slab *mem_chunk);

/**************************************************************
 * binary trees
 **************************************************************/
typedef struct _emem_tree_node_t {
	struct _emem_tree_node_t *parent;
	struct _emem_tree_node_t *left;
	struct _emem_tree_node_t *right;
	struct {
#define EMEM_TREE_RB_COLOR_RED		0
#define EMEM_TREE_RB_COLOR_BLACK	1
		guint32 rb_color:1;
#define EMEM_TREE_NODE_IS_DATA		0
#define EMEM_TREE_NODE_IS_SUBTREE	1
		guint32 is_subtree:1;
	} u;
	guint32 key32;
	void *data;
} emem_tree_node_t;

/** Right now we only do basic red/black trees   but in the future we might want
 * to try something different, such as a tree where each node keeps track
 * of how many times it has been looked up, and letting often looked up
 * nodes bubble upwards in the tree using rotate_right/left.
 * That would probably be good for things like nfs filehandles
 */
#define EMEM_TREE_TYPE_RED_BLACK	1
typedef struct _emem_tree_t {
	struct _emem_tree_t *next;
	int type;
	const char *name;    /**< just a string to make debugging easier */
	emem_tree_node_t *tree;
	void *(*malloc)(size_t);
} emem_tree_t;

/* *******************************************************************
 * Tree functions for SE memory allocation scope
 * ******************************************************************* */
/** This function is used to create a se based tree with monitoring.
 * When the SE heap is released back to the system the pointer to the
 * tree is automatically reset to NULL.
 *
 * type is : EMEM_TREE_TYPE_RED_BLACK for a standard red/black tree.
 */
emem_tree_t *se_tree_create(int type, const char *name) G_GNUC_MALLOC;

/** This function is similar to the se_tree_create() call but with the
 * difference that when the se memory is released everything including the
 * pointer to the tree itself will be released.
 * This tree will not be just reset to zero, it will be completely forgotten
 * by the allocator.
 * Use this function for when you want to store the pointer to a tree inside
 * another structure that is also se allocated so that when the structure is
 * released, the tree will be completely released as well.
 */
emem_tree_t *se_tree_create_non_persistent(int type, const char *name) G_GNUC_MALLOC;

/** se_tree_insert32
 * Insert data into the tree and key it by a 32bit integer value
 */
#define se_tree_insert32 emem_tree_insert32

/** se_tree_lookup32
 * Retrieve the data at the search key. The search key is a 32bit integer value
 */
#define se_tree_lookup32 emem_tree_lookup32

/** se_tree_lookup32_le
 * Retrieve the data for the largest key that is less than or equal
 * to the search key.
 */
#define se_tree_lookup32_le emem_tree_lookup32_le

/** se_tree_insert32_array
 * Insert data into the tree and key it by a 32bit integer value
 */
#define se_tree_insert32_array emem_tree_insert32_array

/** se_tree_lookup32_array
 * Lookup data from the tree that is index by an array
 */
#define se_tree_lookup32_array emem_tree_lookup32_array

/** se_tree_lookup32_array_le
 * Retrieve the data for the largest key that is less than or equal
 * to the search key.
 */
#define se_tree_lookup32_array_le emem_tree_lookup32_array_le

/** Create a new string based hash table */
#define se_tree_create_string() se_tree_create(SE_TREE_TYPE_RED_BLACK)

/** Insert a new value under a string key */
#define se_tree_insert_string emem_tree_insert_string

/** Lookup the value under a string key */
#define se_tree_lookup_string emem_tree_lookup_string

/** Traverse a tree */
#define se_tree_foreach emem_tree_foreach


/* *******************************************************************
 * Tree functions for PE memory allocation scope
 * ******************************************************************* */
/* These trees have PErmanent allocation scope and will never be released
 */
emem_tree_t *pe_tree_create(int type, const char *name) G_GNUC_MALLOC;
#define pe_tree_insert32 emem_tree_insert32
#define pe_tree_lookup32 emem_tree_lookup32
#define pe_tree_lookup32_le emem_tree_lookup32_le
#define pe_tree_insert32_array emem_tree_insert32_array
#define pe_tree_lookup32_array emem_tree_lookup32_array
#define pe_tree_insert_string emem_tree_insert_string
#define pe_tree_lookup_string emem_tree_lookup_string
#define pe_tree_foreach emem_tree_foreach



/* ******************************************************************
 * Real tree functions
 * ****************************************************************** */

/** This function is used to insert a node indexed by a guint32 key value.
 * The data pointer should be allocated by the appropriate storage scope
 * so that it will be released at the same time as the tree itself is
 * destroyed.
 */
void emem_tree_insert32(emem_tree_t *se_tree, guint32 key, void *data);

/** This function will look up a node in the tree indexed by a guint32 integer
 * value.
 */
void *emem_tree_lookup32(emem_tree_t *se_tree, guint32 key);

/** This function will look up a node in the tree indexed by a guint32 integer
 * value.
 * The function will return the node that has the largest key that is
 * equal to or smaller than the search key, or NULL if no such key was
 * found.
 */
void *emem_tree_lookup32_le(emem_tree_t *se_tree, guint32 key);

typedef struct _emem_tree_key_t {
	guint32 length;			/**< length in guint32 words */
	guint32 *key;
} emem_tree_key_t;

/** This function is used to insert a node indexed by a sequence of guint32
 * key values.
 * The data pointer should be allocated by SE allocators so that the
 * data will be released at the same time as the tree itself is destroyed.
 *
 * Note: all the "key" members of the "key" argument MUST be aligned on
 * 32-bit boundaries; otherwise, this code will crash on platforms such
 * as SPARC that require aligned pointers.
 *
 * If you use ...32_array() calls you MUST make sure that every single node
 * you add to a specific tree always has a key of exactly the same number of
 * keylen words or things will most likely crash. Or at least that every single
 * item that sits behind the same top level node always have exactly the same
 * number of words.
 *
 * One way to guarantee this is the way that NFS does this for the
 * nfs_name_snoop_known tree which holds filehandles for both v2 and v3.
 * v2 filehandles are always 32 bytes (8 words) while v3 filehandles can have
 * any length (though 32 bytes are most common).
 * The NFS dissector handles this by providing a guint32 containing the length
 * as the very first item in this vector :
 *
 *			emem_tree_key_t fhkey[3];
 *
 *			fhlen=nns->fh_length;
 *			fhkey[0].length=1;
 *			fhkey[0].key=&fhlen;
 *			fhkey[1].length=fhlen/4;
 *			fhkey[1].key=nns->fh;
 *			fhkey[2].length=0;
 */
void emem_tree_insert32_array(emem_tree_t *se_tree, emem_tree_key_t *key, void *data);

/** This function will look up a node in the tree indexed by a sequence of
 * guint32 integer values.
 */
void *emem_tree_lookup32_array(emem_tree_t *se_tree, emem_tree_key_t *key);

/** This function will look up a node in the tree indexed by a
 * multi-part tree value.
 * The function will return the node that has the largest key that is
 * equal to or smaller than the search key, or NULL if no such key was
 * found.
 * Note:  The key returned will be "less" in key order.  The usefullness
 * of the returned node must be verified prior to use.
 */
void *emem_tree_lookup32_array_le(emem_tree_t *se_tree, emem_tree_key_t *key);

/** case insensitive strings as keys */
#define EMEM_TREE_STRING_NOCASE			0x00000001
/** Insert a new value under a string key */
void emem_tree_insert_string(emem_tree_t* h, const gchar* k, void* v, guint32 flags);

/** Lookup the value under a string key */
void* emem_tree_lookup_string(emem_tree_t* h, const gchar* k, guint32 flags);


/** traverse a tree. if the callback returns TRUE the traversal will end */
typedef gboolean (*tree_foreach_func)(void *value, void *userdata);

gboolean emem_tree_foreach(emem_tree_t* emem_tree, tree_foreach_func callback, void *user_data);


/* ******************************************************************
 * String buffers - Growable strings similar to GStrings
 * ****************************************************************** */

typedef struct _emem_strbuf_t {
    gchar *str;             /**< Points to the character data. It may move as text is       */
                            /*  added. The str field is null-terminated and so can        */
                            /*  be used as an ordinary C string.                          */
    gsize len;              /**< strlen: ie: length of str not including trailing '\0'      */
    gsize alloc_len;        /**< num bytes curently allocated for str: 1 .. MAX_STRBUF_LEN  */
    gsize max_alloc_len;    /**< max num bytes to allocate for str: 1 .. MAX_STRBUF_LEN     */
} emem_strbuf_t;

/*
 * The maximum length is limited to 64K. If you need something bigger, you
 * should probably use an actual GString or GByteArray.
 */

/**
 * Allocate an ephemeral string buffer with "unlimited" size.
 *
 * @param init The initial string for the buffer, or NULL to allocate an initial zero-length string.
 *
 * @return A newly-allocated string buffer.
 */
emem_strbuf_t *ep_strbuf_new(const gchar *init) G_GNUC_MALLOC;

/**
 * Allocate an ephemeral string buffer suitable for the protocol tree.
 * The string will never grow beyond the maximum tree item length.
 *
 * @param init The initial string for the buffer, or NULL to allocate an initial zero-length string.
 *
 * @return A newly-allocated string buffer.
 */
emem_strbuf_t *ep_strbuf_new_label(const gchar *init) G_GNUC_MALLOC;

/**
 * Allocate an ephemeral string buffer with enough initial space for alloc_len bytes
 * and a maximum of max_alloc_len bytes.
 *
 * @param alloc_len The initial size of the buffer. This value can be 0, but a nonzero
 * value is recommended.
 * @param max_alloc_len The maximum size of the buffer. 0 means "unlimited" (within
 * reason).
 *
 * @return A newly-allocated string buffer. str will be empty.
 */
emem_strbuf_t *ep_strbuf_sized_new(gsize alloc_len, gsize max_alloc_len) G_GNUC_MALLOC;

/**
 * Append vprintf-style formatted text to a string buffer.
 *
 * @param strbuf The ep_strbuf-allocated string buffer to append to.
 * @param format A printf-style string format.
 * @param ap The list of arguments to append.
 */
void ep_strbuf_append_vprintf(emem_strbuf_t *strbuf, const gchar *format, va_list ap);

/**
 * Apply printf-style formatted text to a string buffer.
 *
 * @param strbuf The ep_strbuf-allocated string buffer to set to.
 * @param format A printf-style string format.
 */
void ep_strbuf_printf(emem_strbuf_t *strbuf, const gchar *format, ...)
     G_GNUC_PRINTF(2, 3);

/**
 * Append printf-style formatted text to a string buffer.
 *
 * @param strbuf The ep_strbuf-allocated string buffer to append to.
 * @param format A printf-style string format.
 */
void ep_strbuf_append_printf(emem_strbuf_t *strbuf, const gchar *format, ...)
    G_GNUC_PRINTF(2, 3);

/**
 * Append a string to a string buffer.
 *
 * @param strbuf The ep_strbuf-allocated string buffer to append to.
 * @param str A null-terminated string.
 *
 * @return strbuf
 */
emem_strbuf_t *ep_strbuf_append(emem_strbuf_t *strbuf, const gchar *str);

/**
 * Append a character to a string buffer.
 *
 * @param strbuf The ep_strbuf-allocated string buffer to append to.
 * @param c The character to append.
 *
 * @return strbuf
 */
emem_strbuf_t *ep_strbuf_append_c(emem_strbuf_t *strbuf, const gchar c);

/**
 * Chop off the end of a string buffer.
 *
 * @param strbuf The ep_strbuf-allocated string buffer to append to.
 * @param len The new string length.
 *
 * @return strbuf
 */
emem_strbuf_t *ep_strbuf_truncate(emem_strbuf_t *strbuf, gsize len);

void emem_print_tree(emem_tree_t* emem_tree);

/* #define DEBUG_INTENSE_CANARY_CHECKS */

/** Helper to troubleshoot ep memory corruption.
 * If compiled and the environment variable WIRESHARK_DEBUG_EP_INTENSE_CANARY exists
 * it will check the canaries and when found corrupt stop there in the hope
 * the corruptor is still there in the stack.
 * Some checkpoints are already set in packet.c in strategic points
 * before and after dissection of a frame or a dissector call.
 */

#ifdef DEBUG_INTENSE_CANARY_CHECKS
void ep_check_canary_integrity(const char* fmt, ...)
    G_GNUC_PRINTF(1, 2);
#define EP_CHECK_CANARY(args) ep_check_canary_integrity args
#else
#define EP_CHECK_CANARY(args)
#endif

/**
 * Verify that the given pointer is of ephemeral type.
 *
 * @param ptr The pointer to verify
 *
 * @return TRUE if the pointer belongs to the ephemeral pool.
 */
gboolean ep_verify_pointer(const void *ptr);
/**
 * Verify that the given pointer is of seasonal type.
 *
 * @param ptr The pointer to verify
 *
 * @return TRUE if the pointer belongs to the seasonal pool.
 */
gboolean se_verify_pointer(const void *ptr);

#endif /* emem.h */