| .TH "Memory Utility Routines" 3 "17 Oct 2003" "net-snmp" \" -*- nroff -*- |
| .ad l |
| .nh |
| .SH NAME |
| Memory Utility Routines \- |
| .SS "Defines" |
| |
| .in +1c |
| .ti -1c |
| .RI "#define \fBSNMP_FREE\fP(s) if (s) { free((void *)s); s=NULL; }" |
| .br |
| .RI "\fIFrees a pointer only if it is !NULL and sets its value to NULL.\fP" |
| .ti -1c |
| .RI "#define \fBSNMP_MALLOC_STRUCT\fP(s) (struct s *) calloc(1, sizeof(struct s))" |
| .br |
| .RI "\fIMallocs memory of sizeof(struct s), zeros it and returns a pointer to it.\fP" |
| .ti -1c |
| .RI "#define \fBSNMP_MALLOC_TYPEDEF\fP(td) (td *) calloc(1, sizeof(td))" |
| .br |
| .RI "\fIMallocs memory of sizeof(t), zeros it and returns a pointer to it.\fP" |
| .ti -1c |
| .RI "#define \fBSNMP_MAX\fP(a, b) ((a) > (b) ? (a) : (b))" |
| .br |
| .RI "\fIComputers the maximum of a and b.\fP" |
| .ti -1c |
| .RI "#define \fBSNMP_MIN\fP(a, b) ((a) > (b) ? (b) : (a))" |
| .br |
| .RI "\fIComputers the minimum of a and b.\fP" |
| .in -1c |
| .SS "Functions" |
| |
| .in +1c |
| .ti -1c |
| .RI "int \fBsnmp_realloc\fP (u_char **buf, size_t *buf_len)" |
| .br |
| .RI "\fIThis function increase the size of the buffer pointed at by *buf, which is initially of size *buf_len.\fP" |
| .ti -1c |
| .RI "void \fBfree_zero\fP (void *buf, size_t size)" |
| .br |
| .RI "\fIzeros memory before freeing it.\fP" |
| .ti -1c |
| .RI "u_char * \fBmalloc_random\fP (size_t *size)" |
| .br |
| .RI "\fIReturns pointer to allocaed & set buffer on success, size contains number of random bytes filled.\fP" |
| .ti -1c |
| .RI "int \fBmemdup\fP (u_char **to, const u_char *from, size_t size)" |
| .br |
| .RI "\fIDuplicates a memory block.\fP" |
| .ti -1c |
| .RI "u_int \fBbinary_to_hex\fP (const u_char *input, size_t len, char **output)" |
| .br |
| .RI "\fIconverts binary to hexidecimal\fP" |
| .ti -1c |
| .RI "int \fBhex_to_binary2\fP (const u_char *input, size_t len, char **output)" |
| .br |
| .RI "\fIhex_to_binary2\fP" |
| .ti -1c |
| .RI "char * \fBnetsnmp_strdup_and_null\fP (const u_char *from, size_t from_len)" |
| .br |
| .RI "\fIcopies 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\fP" |
| .ti -1c |
| .RI "marker_t \fBatime_newMarker\fP (void)" |
| .br |
| .RI "\fIcreate a new time marker.\fP" |
| .ti -1c |
| .RI "void \fBatime_setMarker\fP (marker_t pm)" |
| .br |
| .RI "\fIset a time marker.\fP" |
| .ti -1c |
| .RI "long \fBatime_diff\fP (marker_t first, marker_t second)" |
| .br |
| .RI "\fIReturns the difference (in msec) between the two markers.\fP" |
| .ti -1c |
| .RI "u_long \fBuatime_diff\fP (marker_t first, marker_t second)" |
| .br |
| .RI "\fIReturns the difference (in u_long msec) between the two markers.\fP" |
| .ti -1c |
| .RI "u_long \fBuatime_hdiff\fP (marker_t first, marker_t second)" |
| .br |
| .RI "\fIReturns the difference (in u_long 1/100th secs) between the two markers (functionally this is what sysUpTime needs).\fP" |
| .ti -1c |
| .RI "int \fBatime_ready\fP (marker_t pm, int deltaT)" |
| .br |
| .RI "\fITest: Has (marked time plus delta) exceeded current time (in msec) ? Returns 0 if test fails or cannot be tested (no marker).\fP" |
| .ti -1c |
| .RI "int \fBuatime_ready\fP (marker_t pm, unsigned int deltaT)" |
| .br |
| .RI "\fITest: Has (marked time plus delta) exceeded current time (in msec) ? Returns 0 if test fails or cannot be tested (no marker).\fP" |
| .ti -1c |
| .RI "int \fBmarker_tticks\fP (marker_t pm)" |
| .br |
| .RI "\fIReturn the number of timeTicks since the given marker.\fP" |
| .in -1c |
| .SH "DEFINE DOCUMENTATION" |
| .PP |
| .SS "#define DIFFTIMEVAL(now, then, diff)" |
| .PP |
| \fBValue:\fP |
| .PP |
| .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++; \ |
| } \ |
| } |
| .fi |
| .PP |
| Definition at line 111 of file tools.h. |
| .SS "#define ISTRANSFORM(ttype, toid)" |
| .PP |
| \fBValue:\fP |
| .PP |
| .nf |
| !snmp_oid_compare(ttype, USM_LENGTH_OID_TRANSFORM, \ |
| usm ## toid ## Protocol, USM_LENGTH_OID_TRANSFORM) |
| .fi |
| .PP |
| Definition at line 130 of file tools.h. |
| .SS "#define QUITFUN(e, l)" |
| .PP |
| \fBValue:\fP |
| .PP |
| .nf |
| if ( (e) != SNMPERR_SUCCESS) { \ |
| rval = SNMPERR_GENERR; \ |
| goto l ; \ |
| } |
| .fi |
| .PP |
| Definition at line 98 of file tools.h. |
| .SS "#define SNMP_FREE(s) if (s) { free((void *)s); s=NULL; }" |
| .PP |
| Frees a pointer only if it is !NULL and sets its value to NULL. |
| .PP |
| Definition at line 52 of file tools.h. |
| .PP |
| Referenced by build_oid_segment(), fprint_description(), fprint_objid(), fprint_variable(), init_mib(), netsnmp_fixup_mib_directory(), netsnmp_free_all_list_data(), netsnmp_free_delegated_cache(), netsnmp_free_list_data(), netsnmp_handler_dup(), netsnmp_handler_free(), netsnmp_handler_registration_free(), netsnmp_register_old_api(), 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(), and shutdown_mib(). |
| .SS "#define SNMP_MALLOC_STRUCT(s) (struct s *) calloc(1, sizeof(struct s))" |
| .PP |
| Mallocs memory of sizeof(struct s), zeros it and returns a pointer to it. |
| .PP |
| Definition at line 59 of file tools.h. |
| .SS "#define SNMP_MALLOC_TYPEDEF(td) (td *) calloc(1, sizeof(td))" |
| .PP |
| Mallocs memory of sizeof(t), zeros it and returns a pointer to it. |
| .PP |
| Definition at line 62 of file tools.h. |
| .PP |
| Referenced by netsnmp_create_data_list(), netsnmp_create_delegated_cache(), netsnmp_create_handler(), netsnmp_create_handler_registration(), netsnmp_create_table_data(), netsnmp_create_table_data_row(), netsnmp_create_table_data_set(), netsnmp_get_cache_handler(), 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(). |
| .SS "#define SNMP_MAX(a, b) ((a) > (b) ? (a) : (b))" |
| .PP |
| Computers the maximum of a and b. |
| .PP |
| Definition at line 76 of file tools.h. |
| .PP |
| Referenced by netsnmp_register_table_data_set(). |
| .SS "#define SNMP_MIN(a, b) ((a) > (b) ? (b) : (a))" |
| .PP |
| Computers the minimum of a and b. |
| .PP |
| Definition at line 80 of file tools.h. |
| .PP |
| Referenced by netsnmp_oid_find_prefix(), netsnmp_register_table_data_set(), netsnmp_set_data_cache(), and netsnmp_table_data_helper_handler(). |
| .SH "FUNCTION DOCUMENTATION" |
| .PP |
| .SS "long atime_diff (marker_t first, marker_t second)" |
| .PP |
| Returns the difference (in msec) between the two markers. |
| .PP |
| Definition at line 698 of file tools.c. |
| .PP |
| Referenced by atime_ready(), and marker_tticks(). |
| .SS "marker_t atime_newMarker (void)" |
| .PP |
| create a new time marker. |
| .PP |
| NOTE: Caller must free time marker when no longer needed. |
| .PP |
| Definition at line 674 of file tools.c. |
| .PP |
| Referenced by atime_ready(), marker_tticks(), netsnmp_cache_helper_handler(), netsnmp_stash_cache_update(), and uatime_ready(). |
| .SS "int atime_ready (marker_t pm, int deltaT)" |
| .PP |
| Test: Has (marked time plus delta) exceeded current time (in msec) ? Returns 0 if test fails or cannot be tested (no marker). |
| .PP |
| Definition at line 753 of file tools.c. |
| .PP |
| References atime_diff(), and atime_newMarker(). |
| .PP |
| Referenced by netsnmp_cache_helper_handler(), netsnmp_stash_cache_update(), and release_cached_resources(). |
| .SS "void atime_setMarker (marker_t pm)" |
| .PP |
| set a time marker. |
| .PP |
| Definition at line 685 of file tools.c. |
| .PP |
| Referenced by netsnmp_cache_helper_handler(), and netsnmp_stash_cache_update(). |
| .SS "u_int binary_to_hex (const u_char * input, size_t len, char ** output)" |
| .PP |
| converts binary to hexidecimal |
| .PP |
| \fBParameters: \fP |
| .in +1c |
| .TP |
| \fB\fIinput\fP\fP |
| Binary data. |
| .TP |
| \fB\fIlen\fP\fP |
| Length of binary data. |
| .TP |
| \fB\fIoutput\fP\fP |
| NULL terminated string equivalent in hex. |
| .PP |
| \fBReturns: \fP |
| .in +1c |
| 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. |
| .PP |
| Definition at line 243 of file tools.c. |
| .SS "void free_zero (void * buf, size_t size)" |
| .PP |
| zeros memory before freeing it. |
| .PP |
| \fBParameters: \fP |
| .in +1c |
| .TP |
| \fB\fIbuf\fP\fP |
| Pointer at bytes to free. |
| .TP |
| \fB\fIsize\fP\fP |
| Number of bytes in buf. |
| .PP |
| Definition at line 141 of file tools.c. |
| .PP |
| Referenced by hex_to_binary2(), and malloc_random(). |
| .SS "int hex_to_binary2 (const u_char * input, size_t len, char ** output)" |
| .PP |
| hex_to_binary2 |
| .PP |
| \fBParameters: \fP |
| .in +1c |
| .TP |
| \fB\fIinput\fP\fP |
| Printable data in base16. |
| .TP |
| \fB\fIlen\fP\fP |
| Length in bytes of data. |
| .TP |
| \fB\fIoutput\fP\fP |
| Binary data equivalent to input. |
| .PP |
| \fBReturns: \fP |
| .in +1c |
| SNMPERR_GENERR on failure, otherwise length of allocated string.Input of an odd length is right aligned. |
| .PP |
| 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. |
| .PP |
| Definition at line 280 of file tools.c. |
| .PP |
| References free_zero(). |
| .SS "u_char* malloc_random (size_t * size)" |
| .PP |
| Returns pointer to allocaed & set buffer on success, size contains number of random bytes filled. |
| .PP |
| buf is NULL and *size set to KMT error value upon failure. |
| .PP |
| \fBParameters: \fP |
| .in +1c |
| .TP |
| \fB\fIsize\fP\fP |
| Number of bytes to malloc() and fill with random bytes. |
| .PP |
| \fBReturns: \fP |
| .in +1c |
| a malloced buffer |
| .PP |
| Definition at line 161 of file tools.c. |
| .PP |
| References free_zero(). |
| .SS "int marker_tticks (marker_t pm)" |
| .PP |
| Return the number of timeTicks since the given marker. |
| .PP |
| Definition at line 801 of file tools.c. |
| .PP |
| References atime_diff(), and atime_newMarker(). |
| .SS "int memdup (u_char ** to, const u_char * from, size_t size)" |
| .PP |
| Duplicates a memory block. |
| .PP |
| Copies a existing memory location from a pointer to another, newly malloced, pointer. |
| .PP |
| \fBParameters: \fP |
| .in +1c |
| .TP |
| \fB\fIto\fP\fP |
| Pointer to allocate and copy memory to. |
| .TP |
| \fB\fIfrom\fP\fP |
| Pointer to copy memory from. |
| .TP |
| \fB\fIsize\fP\fP |
| Size of the data to be copied. |
| .PP |
| \fBReturns: \fP |
| .in +1c |
| SNMPERR_SUCCESS on success, SNMPERR_GENERR on failure. |
| .PP |
| \fBExamples: \fP |
| .in +1c |
| \fBdelayed_instance.c\fP. |
| .PP |
| Definition at line 192 of file tools.c. |
| .PP |
| Referenced by netsnmp_create_handler_registration(), 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(). |
| .SS "char* netsnmp_strdup_and_null (const u_char * from, size_t from_len)" |
| .PP |
| 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 |
| .PP |
| Definition at line 211 of file tools.c. |
| .PP |
| Referenced by netsnmp_table_data_set_helper_handler(). |
| .SS "int snmp_realloc (u_char ** buf, size_t * buf_len)" |
| .PP |
| This function increase the size of the buffer pointed at by *buf, which is initially of size *buf_len. |
| .PP |
| Contents are preserved **AT THE BOTTOM END OF THE BUFFER**. If memory can be (re-)allocated then it returns 1, else it returns 0. |
| .PP |
| \fBParameters: \fP |
| .in +1c |
| .TP |
| \fB\fIbuf\fP\fP |
| pointer to a buffer pointer |
| .TP |
| \fB\fIbuf_len\fP\fP |
| pointer to current size of buffer in bytes |
| .PP |
| Definition at line 71 of file tools.c. |
| .PP |
| Referenced by sprint_realloc_asciistring(), sprint_realloc_hexstring(), sprint_realloc_ipaddress(), sprint_realloc_networkaddress(), and sprint_realloc_octet_string(). |
| .SS "u_long uatime_diff (marker_t first, marker_t second)" |
| .PP |
| Returns the difference (in u_long msec) between the two markers. |
| .PP |
| Definition at line 715 of file tools.c. |
| .PP |
| Referenced by uatime_ready(). |
| .SS "u_long uatime_hdiff (marker_t first, marker_t second)" |
| .PP |
| Returns the difference (in u_long 1/100th secs) between the two markers (functionally this is what sysUpTime needs). |
| .PP |
| Definition at line 733 of file tools.c. |
| .SS "int uatime_ready (marker_t pm, unsigned int deltaT)" |
| .PP |
| Test: Has (marked time plus delta) exceeded current time (in msec) ? Returns 0 if test fails or cannot be tested (no marker). |
| .PP |
| Definition at line 775 of file tools.c. |
| .PP |
| References atime_newMarker(), and uatime_diff(). |
