Memory Utility Routines(3)

NAME
Memory Utility Routines -

  Defines
#define SNMP_MAXPATH 1024 /* Should be safe enough */
#define SNMP_MAXBUF (1024 * 4)
#define SNMP_MAXBUF_MEDIUM 1024
#define SNMP_MAXBUF_SMALL 512
#define SNMP_MAXBUF_MESSAGE 1500
#define SNMP_MAXOID 64
#define SNMP_MAX_CMDLINE_OIDS 128
#define SNMP_FILEMODE_CLOSED 0600
#define SNMP_FILEMODE_OPEN 0644
#define BYTESIZE(bitsize) ((bitsize + 7) >> 3)
#define ROUNDUP8(x) ( ( (x+7) >> 3 ) * 8 )
#define SNMP_FREE(s) do { if (s) { free((void *)s); s=NULL; } } while(0)
Frees a pointer only if it is !NULL and sets its value to NULL.
#define SNMP_SWIPE_MEM(n, s) do { if (n) free((void *)n); n = s; s=NULL; } while(0)
Frees pointer n only if it is !NULL, sets n to s and sets s to NULL.
#define SNMP_MALLOC_STRUCT(s) (struct s *) calloc(1, sizeof(struct s))
Mallocs memory of sizeof(struct s), zeros it and returns a pointer to it.
#define SNMP_MALLOC_TYPEDEF(td) (td *) calloc(1, sizeof(td))
Mallocs memory of sizeof(t), zeros it and returns a pointer to it.
#define SNMP_ZERO(s, l) do { if (s) memset(s, 0, l); } while(0)
Zeros l bytes of memory starting at s.
#define TOUPPER(c) (c >= 'a' && c <= 'z' ? c - ('a' - 'A') : c)
#define TOLOWER(c) (c >= 'A' && c <= 'Z' ? c + ('a' - 'A') : c)
#define HEX2VAL(s) ((isalpha(s) ? (TOLOWER(s)-'a'+10) : (TOLOWER(s)-'0')) & 0xf)
#define VAL2HEX(s) ( (s) + (((s) >= 10) ? ('a'-10) : '0') )
#define SNMP_MAX(a, b) ((a) > (b) ? (a) : (b))
Computers the maximum of a and b.
#define SNMP_MIN(a, b) ((a) > (b) ? (b) : (a))
Computers the minimum of a and b.
#define FALSE 0
#define TRUE 1
#define QUITFUN(e, l)
#define DIFFTIMEVAL(now, then, diff)
#define USM_LENGTH_OID_TRANSFORM 10
#define ISTRANSFORM(ttype, toid)
#define ENGINETIME_MAX 2147483647 /* ((2^31)-1) */
#define ENGINEBOOT_MAX 2147483647 /* ((2^31)-1) */

  Typedefs
typedef void * marker_t

  Functions
int snmp_realloc (u_char **buf, size_t *buf_len)
This function increase the size of the buffer pointed at by *buf, which is initially of size *buf_len.
void free_zero (void *buf, size_t size)
zeros memory before freeing it.
u_char * malloc_random (size_t *size)
Returns pointer to allocaed & set buffer on success, size contains number of random bytes filled.
u_char * malloc_zero (size_t size)
int memdup (u_char **to, const u_char *from, size_t size)
Duplicates a memory block.
u_int binary_to_hex (const u_char *input, size_t len, char **output)
converts binary to hexidecimal
int netsnmp_hex_to_binary (u_char **buf, size_t *buf_len, size_t *out_len, int allow_realloc, const char *hex, const char *delim)
convert an ASCII hex string (with specified delimiters) to binary
int snmp_hex_to_binary (u_char **buf, size_t *buf_len, size_t *out_len, int allow_realloc, const char *hex)
convert an ASCII hex string to binary
int hex_to_binary2 (const u_char *input, size_t len, char **output)
hex_to_binary2
int snmp_decimal_to_binary (u_char **buf, size_t *buf_len, size_t *out_len, int allow_realloc, const char *decimal)
int snmp_strcat (u_char **buf, size_t *buf_len, size_t *out_len, int allow_realloc, const u_char *s)
char * netsnmp_strdup_and_null (const u_char *from, size_t from_len)
copies a (possible) unterminated string of a given length into a new buffer and null terminates it as well (new buffer MAY be one byte longer to account for this
void dump_chunk (const char *debugtoken, const char *title, const u_char *buf, int size)
char * dump_snmpEngineID (const u_char *buf, size_t *buflen)
marker_t atime_newMarker (void)
create a new time marker.
void atime_setMarker (marker_t pm)
set a time marker.
long atime_diff (marker_t first, marker_t second)
Returns the difference (in msec) between the two markers.
u_long uatime_diff (marker_t first, marker_t second)
Returns the difference (in u_long msec) between the two markers.
u_long uatime_hdiff (marker_t first, marker_t second)
Returns the difference (in u_long 1/100th secs) between the two markers (functionally this is what sysUpTime needs).
int atime_ready (marker_t pm, int deltaT)
Test: Has (marked time plus delta) exceeded current time (in msec) ? Returns 0 if test fails or cannot be tested (no marker).
int uatime_ready (marker_t pm, unsigned int deltaT)
Test: Has (marked time plus delta) exceeded current time (in msec) ? Returns 0 if test fails or cannot be tested (no marker).
int marker_tticks (marker_t pm)
Return the number of timeTicks since the given marker.
int timeval_tticks (struct timeval *tv)
char * netsnmp_getenv (const char *name)
Non Windows: Returns a pointer to the desired environment variable or NULL if the environment variable does not exist.

Define Documentation

  #define DIFFTIMEVAL(now, then, diff)

Value:.nf { now.tv_sec--; now.tv_usec += 1000000L; diff.tv_sec = now.tv_sec - then.tv_sec; diff.tv_usec = now.tv_usec - then.tv_usec; if (diff.tv_usec > 1000000L){ diff.tv_usec -= 1000000L; diff.tv_sec++; } }

Definition at line 121 of file tools.h.

  #define ISTRANSFORM(ttype, toid)

Value:.nf !snmp_oid_compare(ttype, USM_LENGTH_OID_TRANSFORM, usm ## toid ## Protocol, USM_LENGTH_OID_TRANSFORM)

Definition at line 140 of file tools.h.

  #define QUITFUN(e, l)

Value:.nf if ( (e) != SNMPERR_SUCCESS) { rval = SNMPERR_GENERR; goto l ; }

Definition at line 108 of file tools.h.

  #define SNMP_FREE(s) do { if (s) { free((void *)s); s=NULL; } } while(0)

Frees a pointer only if it is !NULL and sets its value to NULL. Definition at line 54 of file tools.h.

Referenced by build_oid_segment(), fprint_description(), fprint_objid(), fprint_variable(), init_mib(), netsnmp_cache_reqinfo_extract(), netsnmp_cache_reqinfo_insert(), netsnmp_create_handler(), netsnmp_fixup_mib_directory(), netsnmp_free_all_list_data(), netsnmp_free_delegated_cache(), netsnmp_free_list_data(), netsnmp_getenv(), netsnmp_handler_free(), netsnmp_handler_registration_free(), netsnmp_register_old_api(), netsnmp_set_mib_directory(), netsnmp_set_row_column(), netsnmp_table_build_oid_from_index(), netsnmp_table_data_delete_row(), netsnmp_table_data_set_helper_handler(), netsnmp_table_dataset_delete_data(), netsnmp_table_iterator_helper_handler(), read_objid(), shutdown_mib(), snmp_unregister_callback(), and unregister_config_handler().

  #define SNMP_MALLOC_STRUCT(s) (struct s *) calloc(1, sizeof(struct s))

Mallocs memory of sizeof(struct s), zeros it and returns a pointer to it. Definition at line 65 of file tools.h.

Referenced by snmp_alarm_register(), and snmp_alarm_register_hr().

  #define SNMP_MALLOC_TYPEDEF(td) (td *) calloc(1, sizeof(td))

Mallocs memory of sizeof(t), zeros it and returns a pointer to it. Definition at line 69 of file tools.h.

Referenced by netsnmp_baby_steps_handler_get(), netsnmp_cache_create(), netsnmp_container_table_handler_get(), netsnmp_create_data_list(), netsnmp_create_delegated_cache(), netsnmp_create_handler(), netsnmp_create_table_data(), netsnmp_create_table_data_row(), netsnmp_create_table_data_set(), netsnmp_handler_registration_create(), netsnmp_mark_row_column_writable(), netsnmp_mode_end_call_add_mode_callback(), netsnmp_oid_stash_create_sized_node(), netsnmp_old_api_helper(), netsnmp_register_auto_data_table(), netsnmp_register_mib_table_row(), netsnmp_register_old_api(), netsnmp_register_save_list(), netsnmp_register_table_data_set(), netsnmp_set_row_column(), netsnmp_table_container_register(), netsnmp_table_data_set_helper_handler(), netsnmp_table_iterator_helper_handler(), netsnmp_table_set_add_default_row(), and table_helper_handler().

  #define SNMP_MAX(a, b) ((a) > (b) ? (a) : (b))

Computers the maximum of a and b. Definition at line 86 of file tools.h.

Referenced by netsnmp_register_table_data_set().

  #define SNMP_MIN(a, b) ((a) > (b) ? (b) : (a))

Computers the minimum of a and b. Definition at line 90 of file tools.h.

Referenced by netsnmp_oid_find_prefix(), netsnmp_register_table_data_set(), and netsnmp_table_data_helper_handler().

  #define SNMP_SWIPE_MEM(n, s) do { if (n) free((void *)n); n = s; s=NULL; } while(0)

Frees pointer n only if it is !NULL, sets n to s and sets s to NULL. Definition at line 58 of file tools.h.

  #define SNMP_ZERO(s, l) do { if (s) memset(s, 0, l); } while(0)

Zeros l bytes of memory starting at s. Definition at line 73 of file tools.h.

Function Documentation

  long atime_diff (marker_t first, marker_t second)

Returns the difference (in msec) between the two markers. Definition at line 792 of file tools.c.

Referenced by atime_ready(), and marker_tticks().

  marker_t atime_newMarker (void)

create a new time marker. NOTE: Caller must free time marker when no longer needed. Definition at line 768 of file tools.c.

Referenced by atime_ready(), marker_tticks(), netsnmp_stash_cache_update(), and uatime_ready().

  int atime_ready (marker_t pm, int deltaT)

Test: Has (marked time plus delta) exceeded current time (in msec) ? Returns 0 if test fails or cannot be tested (no marker). Definition at line 847 of file tools.c.

References atime_diff(), and atime_newMarker().

Referenced by netsnmp_cache_check_expired(), and netsnmp_stash_cache_update().

  void atime_setMarker (marker_t pm)

set a time marker. Definition at line 779 of file tools.c.

Referenced by netsnmp_stash_cache_update().

  u_int binary_to_hex (const u_char * input, size_t len, char ** output)

converts binary to hexidecimal Parameters:
    *input Binary data.
    len Length of binary data.
    **output NULL terminated string equivalent in hex.

Returns:
    olen Length of output string not including NULL terminator.

FIX Is there already one of these in the UCD SNMP codebase? The old one should be used, or this one should be moved to snmplib/snmp_api.c. Definition at line 285 of file tools.c.

  void free_zero (void * buf, size_t size)

zeros memory before freeing it. Parameters:
    *buf Pointer at bytes to free.
    size Number of bytes in buf.

Definition at line 183 of file tools.c.

Referenced by hex_to_binary2(), and malloc_random().

  int hex_to_binary2 (const u_char * input, size_t len, char ** output)

hex_to_binary2 Parameters:
    *input Printable data in base16.
    len Length in bytes of data.
    **output Binary data equivalent to input.

Returns:
    SNMPERR_GENERR on failure, otherwise length of allocated string.

Input of an odd length is right aligned.

FIX Another version of 'hex-to-binary' which takes odd length input strings. It also allocates the memory to hold the binary data. Should be integrated with the official hex_to_binary() function. Definition at line 322 of file tools.c.

References free_zero().

  u_char* malloc_random (size_t * size)

Returns pointer to allocaed & set buffer on success, size contains number of random bytes filled. buf is NULL and *size set to KMT error value upon failure.

Parameters:
    size Number of bytes to malloc() and fill with random bytes.

Returns:
    a malloced buffer

Definition at line 203 of file tools.c.

References free_zero().

  int marker_tticks (marker_t pm)

Return the number of timeTicks since the given marker. Definition at line 895 of file tools.c.

References atime_diff(), and atime_newMarker().

  int memdup (u_char ** to, const u_char * from, size_t size)

Duplicates a memory block. Copies a existing memory location from a pointer to another, newly malloced, pointer.

Parameters:
    to Pointer to allocate and copy memory to.
    from Pointer to copy memory from.
    size Size of the data to be copied.

Returns:
    SNMPERR_SUCCESS on success, SNMPERR_GENERR on failure.

Definition at line 234 of file tools.c.

Referenced by netsnmp_handler_registration_create(), netsnmp_handler_registration_dup(), netsnmp_register_old_api(), netsnmp_set_row_column(), netsnmp_table_data_clone_row(), netsnmp_table_data_set_clone_row(), and netsnmp_table_set_add_default_row().

  char* netsnmp_getenv (const char * name)

Non Windows: Returns a pointer to the desired environment variable or NULL if the environment variable does not exist. Windows: Returns a pointer to the desired environment variable if it exists. If it does not, the variable is looked up in the registry in HKCU-SNMP or HKLM-SNMP (whichever it finds first) and stores the result in the environment variable. It then returns a pointer to environment variable. Definition at line 923 of file tools.c.

References SNMP_FREE.

Referenced by init_mib(), netsnmp_fixup_mib_directory(), netsnmp_get_mib_directory(), and read_config_store().

  int netsnmp_hex_to_binary (u_char ** buf, size_t * buf_len, size_t * out_len, int allow_realloc, const char * hex, const char * delim)

convert an ASCII hex string (with specified delimiters) to binary Parameters:
    buf address of a pointer (pointer to pointer) for the output buffer. If allow_realloc is set, the buffer may be grown via snmp_realloc to accomodate the data.
    buf_len pointer to a size_t containing the initial size of buf.
    out_len On input, a pointer to a size_t indicating an offset into buf. The binary data will be stored at this offset. On output, this pointer will have updated the offset to be the first byte after the converted data.
    allow_realloc If true, the buffer can be reallocated. If false, and the buffer is not large enough to contain the string, an error will be returned.
    hex pointer to hex string to be converted. May be prefixed by '0x' or '0X'.
    delim point to a string of allowed delimiters between bytes. If not specified, any non-hex characters will be an error.

Return values:
    1 success
    0 error

Definition at line 423 of file tools.c.

References snmp_realloc().

Referenced by snmp_hex_to_binary().

  char* netsnmp_strdup_and_null (const u_char * from, size_t from_len)

copies a (possible) unterminated string of a given length into a new buffer and null terminates it as well (new buffer MAY be one byte longer to account for this Definition at line 253 of file tools.c.

Referenced by netsnmp_table_data_set_helper_handler().

  int snmp_hex_to_binary (u_char ** buf, size_t * buf_len, size_t * out_len, int allow_realloc, const char * hex)

convert an ASCII hex string to binary Note:
    This is a wrapper which calls netsnmp_hex_to_binary with a delimiter string of ' '.

See netsnmp_hex_to_binary for parameter descriptions.

Return values:
    1 success
    0 error

Definition at line 482 of file tools.c.

References netsnmp_hex_to_binary().

  int snmp_realloc (u_char ** buf, size_t * buf_len)

This function increase the size of the buffer pointed at by *buf, which is initially of size *buf_len. Contents are preserved **AT THE BOTTOM END OF THE BUFFER**. If memory can be (re-)allocated then it returns 1, else it returns 0.

Parameters:
    buf pointer to a buffer pointer
    buf_len pointer to current size of buffer in bytes

Note:
    The current re-allocation algorithm is to increase the buffer size by whichever is the greater of 256 bytes or the current buffer size, up to a maximum increase of 8192 bytes.

Definition at line 119 of file tools.c.

Referenced by _sprint_hexstring_line(), netsnmp_hex_to_binary(), sprint_realloc_asciistring(), sprint_realloc_ipaddress(), sprint_realloc_networkaddress(), and sprint_realloc_octet_string().

  u_long uatime_diff (marker_t first, marker_t second)

Returns the difference (in u_long msec) between the two markers. Definition at line 809 of file tools.c.

Referenced by uatime_ready().

  u_long uatime_hdiff (marker_t first, marker_t second)

Returns the difference (in u_long 1/100th secs) between the two markers (functionally this is what sysUpTime needs). Definition at line 827 of file tools.c.

  int uatime_ready (marker_t pm, unsigned int deltaT)

Test: Has (marked time plus delta) exceeded current time (in msec) ? Returns 0 if test fails or cannot be tested (no marker). Definition at line 869 of file tools.c.

References atime_newMarker(), and uatime_diff().