doc/README.malloc

   1 $Id$
   2
   3 IMPORTANT NOTE:
   4       The emem interface (as described in this file) is deprecated.
   5       Please use wmem (as described in README.wmem) for all new code.
   6       This file is left as a reference since a great deal of existing
   7       code still uses emem.
   8
   9 1. Introduction
  10
  11 In order to make memory management easier and to reduce the probability of
  12 memory leaks wireshark provides its own memory management API. This API is
  13 implemented inside epan/emem.c and provides memory allocation functions
  14 where the allocated memory is automatically freed at certain points.
  15
  16 If you use these functions you will no longer need to keep track of when and
  17 where to free any dynamically allocated memory, the memory will
  18 automatically be freed at the appropriate time.
  19
  20 Using these functions will greatly elevate the probability that your code
  21 will not leak memory so do use them where appropriate.
  22
  23 2. The allocation types
  24
  25 There are two sets of functions with different allocation temporal scopes:
  26  * ephemeral (ep_...)
  27  * seasonal (se_...)
  28
  29 2.1 Ephemeral allocations
  30
  31 The ephemeral functions allocate memory that will be automatically freed
  32 once the current packet dissection completes. These functions are useful for
  33 situations where you just want a temporary buffer that should stay around for
  34 a short while. Do not use these functions if you need persistent allocations
  35 where the data is to still be available in some later packet.
  36
  37 2.2 Seasonal allocations
  38
  39 The seasonal functions allocate memory that will stay around a lot longer
  40 but will be automatically freed once the current capture is closed and
  41 Wireshark opens a new capture (either by reading a new capture file or by
  42 starting a new capture on some interface). These functions are useful for
  43 allocations with longer scope for example if you need some buffers or data to
  44 keep state between packets.
  45
  46 3 The API
  47
  48 For a detailed description of the functions please refer to the header file
  49 epan/emem.h
  50
  51 3.1 Common memory allocation functions
  52
  53 .._alloc(n) : allocate a chunk of memory of size n with ep/se scope.
  54 ep_new(t) : allocate a single element of type t.
  55 .._alloc_array(t,n): will allocate an array of n elements of type t.
  56
  57 .._alloc0(n) : allocate a chunk of memory of size n and fill it with 0.
  58 ep_new0(t) : allocate a single element of type t and fill it with 0.
  59
  60 3.2 String related functions
  61
  62 .._strdup(s) : equivalent to strdup(s) with ep/se scope.
  63 .._strndup(s,n) : allocate a chunk of size n+1 and copy s into it.
  64 .._memdup(s,n) : allocate n chunk and copy into it n bytes starting at s.
  65
  66 .._strdup_printf() : will calculate the size of the formatted string, allocate
  67   a chunk for it and format the string.
  68 .._strdup_vprintf() : will calculate the size of the formatted string,
  69   allocate a chunk for it and format the string.
  70
  71 ep_strsplit(): will split a string based on a certain separator returning an
  72   array of strings.
  73
  74 3.3 Stack related functions
  75
  76 ep_stack_new() : creates an ephemeral stack.
  77 ep_stack_push() : pushes an element into the stack.
  78 ep_stack_pop() : pops an element from the stack.
  79 ep_stack_peek() : returns the top element of the stack without popping it.
  80
  81 3.4 tvbuff related functions
  82
  83 ep_tvb_memdup(): create an ephemeral duplicate of part of the tvbuff.
  84
  85 3.4 String buffers
  86
  87 The ep_strbuf_... functions create and modify growable strings, similar to GLib's
  88 GStrings.
  89
  90 ep_strbuf_new(s) : Creates a new strbuf, initialized to s.
  91 ep_strbuf_new_label(s) : Like ep_strbuf_new, but with a max length suitable for
  92   protocol tree items.
  93 ep_strbuf_sized_new() : Creates a new strbuf with explicit sizes.
  94 ep_strbuf_append_vprintf() : Appends an argument list to a strbuf.
  95 ep_strbuf_append_printf() : Appends to a strbuf in the style of printf.
  96 ep_strbuf_append() : Appends a string to a strbuf.
  97 ep_strbuf_truncate() : Shortens a strbuf.