Memory Utility Routines

Defines
#define	SNMP_MAXPATH   1024
#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_STRORNULL(x)   ( x ? x : "(null)")
#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	NETSNMP_REMOVE_CONST(t, e)   ((t)(uintptr_t)(e))
	Cast away constness without that gcc -Wcast-qual prints a compiler warning, similar to const_cast<> in C++.
#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	SNMP_MACRO_VAL_TO_STR(s)   SNMP_MACRO_VAL_TO_STR_PRIV(s)
	Expands to string with value of the s.
#define	SNMP_MACRO_VAL_TO_STR_PRIV(s)   #s
#define	FALSE   0
#define	TRUE   1
#define	QUITFUN(e, l)
#define	DIFFTIMEVAL(now, then, diff)
#define	NETSNMP_TIMERADD(a, b, res)
	Compute res = a + b.
#define	NETSNMP_TIMERSUB(a, b, res)
	Compute res = a - b.
#define	USM_LENGTH_OID_TRANSFORM   10
#define	ISTRANSFORM(ttype, toid)
#define	ENGINETIME_MAX   2147483647
#define	ENGINEBOOT_MAX   2147483647
#define	snmp_cstrcat(b, l, o, a, s)   snmp_strcat(b,l,o,a,(const u_char *)s)
Typedefs
typedef void *	marker_t
	A pointer to an opaque time marker value.
typedef const void *	const_marker_t
Functions
NETSNMP_IMPORT 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)
NETSNMP_IMPORT int	memdup (u_char **to, const void *from, size_t size)
	Duplicates a memory block.
void	netsnmp_check_definedness (const void *packet, size_t length)
	When running under Valgrind, check whether all bytes in the range [packet, packet+length) are defined.
NETSNMP_IMPORT u_int	netsnmp_binary_to_hex (u_char **dest, size_t *dest_len, int allow_realloc, const u_char *input, size_t len)
	converts binary to hexidecimal
NETSNMP_IMPORT 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 *offset, int allow_realloc, const char *hex, const char *delim)
	convert an ASCII hex string (with specified delimiters) to binary
NETSNMP_IMPORT int	snmp_hex_to_binary (u_char **buf, size_t *buf_len, size_t *offset, int allow_realloc, const char *hex)
	convert an ASCII hex string to binary
NETSNMP_IMPORT int	hex_to_binary2 (const u_char *input, size_t len, char **output)
	hex_to_binary2
NETSNMP_IMPORT int	snmp_decimal_to_binary (u_char **buf, size_t *buf_len, size_t *out_len, int allow_realloc, const char *decimal)
NETSNMP_IMPORT int	snmp_strcat (u_char **buf, size_t *buf_len, size_t *out_len, int allow_realloc, const u_char *s)
NETSNMP_IMPORT 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
NETSNMP_IMPORT 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)
NETSNMP_IMPORT marker_t	atime_newMarker (void)
	create a new time marker.
NETSNMP_IMPORT void	atime_setMarker (marker_t pm)
	set a time marker.
NETSNMP_IMPORT long	atime_diff (const_marker_t first, const_marker_t second)
	Returns the difference (in msec) between the two markers.
u_long	uatime_diff (const_marker_t first, const_marker_t second)
	Returns the difference (in u_long msec) between the two markers.
NETSNMP_IMPORT u_long	uatime_hdiff (const_marker_t first, const_marker_t second)
	Returns the difference (in u_long 1/100th secs) between the two markers (functionally this is what sysUpTime needs)
NETSNMP_IMPORT int	atime_ready (const_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 (const_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 (const_marker_t pm)
	Return the number of timeTicks since the given marker.
int	timeval_tticks (const 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.
int	netsnmp_addrstr_hton (char *ptr, size_t len)
NETSNMP_IMPORT int	netsnmp_string_time_to_secs (const char *time_string)
	Takes a time string like 4h and converts it to seconds.

---

Define Documentation

#define DIFFTIMEVAL	(		now,
			then,
			diff
	)

Value:

{                                                       \
        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 152 of file tools.h.

#define ISTRANSFORM	(		ttype,
			toid
	)

Value:

!snmp_oid_compare(ttype, USM_LENGTH_OID_TRANSFORM,              \
                usm ## toid ## Protocol, USM_LENGTH_OID_TRANSFORM)

Definition at line 207 of file tools.h.

#define NETSNMP_REMOVE_CONST	(		t,
			e
	)		((t)(uintptr_t)(e))

Cast away constness without that gcc -Wcast-qual prints a compiler warning, similar to const_cast<> in C++.

Parameters:

[in]	t	A pointer type.
[in]	e	An expression of a type that can be assigned to the type (const t).

Definition at line 92 of file tools.h.

#define NETSNMP_TIMERADD	(		a,
			b,
			res
	)

Value:

{                                                    \
    (res)->tv_sec  = (a)->tv_sec  + (b)->tv_sec;     \
    (res)->tv_usec = (a)->tv_usec + (b)->tv_usec;    \
    if ((res)->tv_usec >= 1000000L) {                \
        (res)->tv_usec -= 1000000L;                  \
        (res)->tv_sec++;                             \
    }                                                \
}

Compute res = a + b.

Precondition:

a and b must be normalized 'struct timeval' values.

Note:

res may be the same variable as one of the operands. In other words, &a == &res || &b == &res may hold.

Definition at line 172 of file tools.h.

#define NETSNMP_TIMERSUB	(		a,
			b,
			res
	)

Value:

{                                                               \
    (res)->tv_sec  = (a)->tv_sec  - (b)->tv_sec - 1;            \
    (res)->tv_usec = (a)->tv_usec - (b)->tv_usec + 1000000L;    \
    if ((res)->tv_usec >= 1000000L) {                           \
        (res)->tv_usec -= 1000000L;                             \
        (res)->tv_sec++;                                        \
    }                                                           \
}

Compute res = a - b.

Precondition:

a and b must be normalized 'struct timeval' values.

Note:

res may be the same variable as one of the operands. In other words, &a == &res || &b == &res may hold.

Definition at line 190 of file tools.h.

#define QUITFUN	(		e,
			l
	)

Value:

if ( (e) != SNMPERR_SUCCESS) {  \
                rval = SNMPERR_GENERR;  \
                goto l ;                \
        }

Definition at line 139 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 57 of file tools.h.

#define SNMP_MACRO_VAL_TO_STR

(

s

)

SNMP_MACRO_VAL_TO_STR_PRIV(s)

Expands to string with value of the s.

If s is macro, the resulting string is value of the macro. Example: #define TEST 1234 SNMP_MACRO_VAL_TO_STR(TEST) expands to "1234" SNMP_MACRO_VAL_TO_STR(TEST+1) expands to "1234+1"

Definition at line 120 of file tools.h.

#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 68 of file tools.h.

#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 72 of file tools.h.

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

Computers the maximum of a and b.

Definition at line 106 of file tools.h.

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

Computers the minimum of a and b.

Definition at line 110 of file tools.h.

#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 61 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 76 of file tools.h.

---

Typedef Documentation

typedef void* marker_t

A pointer to an opaque time marker value.

Definition at line 276 of file tools.h.

---

Function Documentation

NETSNMP_IMPORT long atime_diff	(	const_marker_t	first,
		const_marker_t	second
	)

Returns the difference (in msec) between the two markers.

Definition at line 908 of file tools.c.

NETSNMP_IMPORT marker_t atime_newMarker

(

void

)

create a new time marker.

NOTE: Caller must free time marker when no longer needed.

Definition at line 884 of file tools.c.

NETSNMP_IMPORT int atime_ready	(	const_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 948 of file tools.c.

NETSNMP_IMPORT void atime_setMarker

(

marker_t

pm

)

set a time marker.

Definition at line 895 of file tools.c.

NETSNMP_IMPORT 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 410 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 221 of file tools.c.

NETSNMP_IMPORT 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 437 of file tools.c.

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 242 of file tools.c.

int marker_tticks

(

const_marker_t

pm

)

Return the number of timeTicks since the given marker.

Definition at line 998 of file tools.c.

NETSNMP_IMPORT int memdup	(	u_char **	to,
		const void *	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 274 of file tools.c.

NETSNMP_IMPORT u_int netsnmp_binary_to_hex	(	u_char **	dest,
		size_t *	dest_len,
		int	allow_realloc,
		const u_char *	input,
		size_t	len
	)

converts binary to hexidecimal

Parameters:

*input	Binary data.
len	Length of binary data.
**dest	NULL terminated string equivalent in hex.
*dest_len	size of destination buffer
allow_realloc	flag indicating if buffer can be realloc'd

Returns:

olen Length of output string not including NULL terminator.

Definition at line 356 of file tools.c.

void netsnmp_check_definedness	(	const void *	packet,
		size_t	length
	)

When running under Valgrind, check whether all bytes in the range [packet, packet+length) are defined.

Let Valgrind print a backtrace if one or more bytes with uninitialized values have been found. This function can help to find the cause of undefined value errors if --track-origins=yes is not sufficient. Does nothing when not running under Valgrind.

Note: this requires a fairly recent valgrind.

Definition at line 300 of file tools.c.

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\Net-SNMP or HKLM\Net-SNMP (whichever it finds first) and stores the result in the environment variable. It then returns a pointer to environment variable.

Definition at line 1028 of file tools.c.

int netsnmp_hex_to_binary	(	u_char **	buf,
		size_t *	buf_len,
		size_t *	offset,
		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.
offset	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 538 of file tools.c.

NETSNMP_IMPORT 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 326 of file tools.c.

NETSNMP_IMPORT int netsnmp_string_time_to_secs

(

const char *

time_string

)

Takes a time string like 4h and converts it to seconds.

The string time given may end in 's' for seconds (the default anyway if no suffix is specified), 'm' for minutes, 'h' for hours, 'd' for days, or 'w' for weeks. The upper case versions are also accepted.

Parameters:

time_string

The time string to convert.

Returns:

seconds converted from the string

-1 : on failure

Definition at line 1196 of file tools.c.

NETSNMP_IMPORT int snmp_hex_to_binary	(	u_char **	buf,
		size_t *	buf_len,
		size_t *	offset,
		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 598 of file tools.c.

NETSNMP_IMPORT 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 157 of file tools.c.

u_long uatime_diff	(	const_marker_t	first,
		const_marker_t	second
	)

Returns the difference (in u_long msec) between the two markers.

Definition at line 921 of file tools.c.

NETSNMP_IMPORT u_long uatime_hdiff	(	const_marker_t	first,
		const_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 935 of file tools.c.

int uatime_ready	(	const_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 971 of file tools.c.