From df77e26485b9c46ee397ef2fc49f9f8ee3488431 Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Wed, 26 Feb 2014 17:22:22 -0500 Subject: [PATCH] Fix some wmem-related documentation. Discovered while reviewing Ibd3efb92a203861f507ce71bc8d04d19d9d38a93 Change-Id: Ie4dfc1b9b7a99f14657148ed5a935bbb079c2b4e Reviewed-on: https://code.wireshark.org/review/415 Reviewed-by: Evan Huus --- doc/README.dissector | 18 ++++++++---------- doc/README.wmem | 11 ++++++++++- 2 files changed, 18 insertions(+), 11 deletions(-) diff --git a/doc/README.dissector b/doc/README.dissector index 5f5eb789a5..ae6980e464 100644 --- a/doc/README.dissector +++ b/doc/README.dissector @@ -256,9 +256,8 @@ data from the specified tvbuff, starting at the specified offset, and containing the specified length worth of characters. Reads data in the specified encoding and produces UTF-8 in the buffer. See below for a list of input encoding values. -The buffer is allocated by g_malloc() if scope is set to NULL (in that -case memory must be explicitely freed), or with the allocator lifetime -if scope is not NULL. +The buffer is allocated in the given wmem scope (see README.wmem for more +information). guint8 *tvb_get_stringz_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, gint *lengthp, const guint encoding); @@ -270,9 +269,8 @@ specified encoding and produces UTF-8 in the buffer. See below for a list of input encoding values. "*lengthp" will be set to the length of the string, including the terminating null. -The buffer is allocated by g_malloc() if scope is set to NULL (in that -case memory must be explicitely freed), or with the allocator lifetime -if scope is not NULL. +The buffer is allocated in the given wmem scope (see README.wmem for more +information). const guint8 *tvb_get_const_stringz(tvbuff_t *tvb, const gint offset, gint *lengthp); @@ -303,9 +301,8 @@ gchar *tvb_get_ts_23_038_7bits_string(wmem_allocator_t *scope, tvb_get_ts_23_038_7bits_string() returns a string of a given number of characters and encoded according to 3GPP TS 23.038 7 bits alphabet. -The buffer is allocated by g_malloc() if scope is set to NULL (in that -case memory must be explicitely freed), or with the allocator lifetime -if scope is not NULL. +The buffer is allocated in the given wmem scope (see README.wmem for more +information). Byte Array Accessors: @@ -341,7 +338,8 @@ from the specified tvbuff, starting at the specified offset. guint8* tvb_memdup(wmem_allocator_t *scope, tvbuff_t *tvb, gint offset, gint length); -Returns a buffer, allocated with "g_malloc()" if scope is NULL, or with the specified pool. +Returns a buffer containing a copy of the given TVB bytes. The buffer is +allocated in the given wmem scope (see README.wmem for more information). Pointer-retrieval: /* WARNING! Don't use this function. There is almost always a better way. diff --git a/doc/README.wmem b/doc/README.wmem index 8012bea2e1..853d078997 100644 --- a/doc/README.wmem +++ b/doc/README.wmem @@ -68,6 +68,15 @@ next packet is dissected. This is, in fact, the scope of Wireshark's pinfo structure, so the pinfo struct has a 'pool' member which is a wmem pool scoped to the lifetime of the pinfo struct. +2.1.3 NULL Pool + +Any function that takes a pointer to a wmem_allocator_t can also be passed NULL +instead. In this case the memory is not allocated in a pool at all - it is +manually managed, and *must* eventually be passed to wmem_free() in order to +prevent memory leaks. Note that passing wmem_allocated memory directly to free() +or g_free() is not safe; the backing type of manually managed memory may be +changed without warning. + 2.2 API Full documentation for each function (parameters, return values, behaviours) @@ -77,7 +86,7 @@ This is just an overview of which header files you should be looking at. 2.2.1 Core API wmem_core.h - - Basic memory management functions like malloc, realloc and free. + - Basic memory management functions (wmem_alloc, wmem_realloc, wmem_free). 2.2.2 Strings