.TH "generic linked-list data handling with a string as a key." 3 "13 Jul 2006" "Version 5.3.1" "net-snmp" \" -*- nroff -*-
.ad l
.nh
.SH NAME
generic linked-list data handling with a string as a key. \- 
.SS "Functions"

.in +1c
.ti -1c
.RI "NETSNMP_INLINE void \fBnetsnmp_free_list_data\fP (\fBnetsnmp_data_list\fP *\fBnode\fP)"
.br
.RI "\fIfrees the data and a name at a given data_list node. \fP"
.ti -1c
.RI "NETSNMP_INLINE void \fBnetsnmp_free_all_list_data\fP (\fBnetsnmp_data_list\fP *head)"
.br
.RI "\fIfrees all data and nodes in a list. \fP"
.ti -1c
.RI "NETSNMP_INLINE \fBnetsnmp_data_list\fP * \fBnetsnmp_create_data_list\fP (const char *name, void *data, Netsnmp_Free_List_Data *beer)"
.br
.RI "\fIadds creates a data_list node given a name, data and a free function ptr. \fP"
.ti -1c
.RI "NETSNMP_INLINE void \fBnetsnmp_add_list_data\fP (\fBnetsnmp_data_list\fP **head, \fBnetsnmp_data_list\fP *\fBnode\fP)"
.br
.RI "\fIdepreciated: use \fBnetsnmp_data_list_add_node()\fP \fP"
.ti -1c
.RI "NETSNMP_INLINE void \fBnetsnmp_data_list_add_node\fP (\fBnetsnmp_data_list\fP **head, \fBnetsnmp_data_list\fP *\fBnode\fP)"
.br
.RI "\fIadds data to a datalist \fP"
.ti -1c
.RI "NETSNMP_INLINE \fBnetsnmp_data_list\fP * \fBnetsnmp_data_list_add_data\fP (\fBnetsnmp_data_list\fP **head, const char *name, void *data, Netsnmp_Free_List_Data *beer)"
.br
.RI "\fIadds data to a datalist \fP"
.ti -1c
.RI "NETSNMP_INLINE void * \fBnetsnmp_get_list_data\fP (\fBnetsnmp_data_list\fP *head, const char *name)"
.br
.RI "\fIreturns a data_list node's data for a given name within a data_list \fP"
.ti -1c
.RI "NETSNMP_INLINE \fBnetsnmp_data_list\fP * \fBnetsnmp_get_list_node\fP (\fBnetsnmp_data_list\fP *head, const char *name)"
.br
.RI "\fIreturns a data_list node for a given name within a data_list \fP"
.ti -1c
.RI "int \fBnetsnmp_remove_list_node\fP (\fBnetsnmp_data_list\fP **realhead, const char *name)"
.br
.RI "\fIRemoves a named node from a data_list (and frees it). \fP"
.ti -1c
.RI "void \fBnetsnmp_register_save_list\fP (\fBnetsnmp_data_list\fP **datalist, const char *type, const char *token, Netsnmp_Save_List_Data *data_list_save_ptr, Netsnmp_Read_List_Data *data_list_read_ptr, Netsnmp_Free_List_Data *data_list_free_ptr)"
.br
.RI "\fIregisters to store a data_list set of data at persistent storage time \fP"
.ti -1c
.RI "int \fBnetsnmp_save_all_data_callback\fP (int major, int minor, void *serverarg, void *clientarg)"
.br
.RI "\fIintended to be registerd as a callback operation. \fP"
.ti -1c
.RI "int \fBnetsnmp_save_all_data\fP (\fBnetsnmp_data_list\fP *head, const char *type, const char *token, Netsnmp_Save_List_Data *data_list_save_ptr)"
.br
.RI "\fIintended to be called as a callback during persistent save operations. \fP"
.ti -1c
.RI "void \fBnetsnmp_read_data_callback\fP (const char *token, char *line)"
.br
.RI "\fIintended to be registerd as a .conf parser It should be registered using: \fP"
.in -1c
.SH "Function Documentation"
.PP 
.SS "NETSNMP_INLINE void netsnmp_add_list_data (\fBnetsnmp_data_list\fP ** head, \fBnetsnmp_data_list\fP * node)"
.PP
depreciated: use \fBnetsnmp_data_list_add_node()\fP 
.PP
Definition at line 83 of file data_list.c.
.PP
References netsnmp_data_list_add_node().
.PP
Referenced by netsnmp_agent_add_list_data(), netsnmp_data_list_add_data(), netsnmp_read_data_callback(), netsnmp_register_auto_data_table(), netsnmp_register_handler_by_name(), netsnmp_register_save_list(), and netsnmp_request_add_list_data().
.SS "NETSNMP_INLINE \fBnetsnmp_data_list\fP* netsnmp_create_data_list (const char * name, void * data, Netsnmp_Free_List_Data * beer)"
.PP
adds creates a data_list node given a name, data and a free function ptr. 
.PP
\fBParameters:\fP
.RS 4
\fIname\fP the name of the node to cache the data. 
.br
\fIdata\fP the data to be stored under that name 
.br
\fIbeer\fP A function that can free the data pointer (in the future) 
.RE
.PP
\fBReturns:\fP
.RS 4
a newly created data_list node which can be given to the netsnmp_add_list_data function. 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBdelayed_instance.c\fP.
.PP
Definition at line 60 of file data_list.c.
.PP
References netsnmp_data_list_s::data, netsnmp_data_list_s::free_func, netsnmp_data_list_s::name, NULL, and SNMP_MALLOC_TYPEDEF.
.PP
Referenced by _netsnmp_stash_cache_load(), _netsnmp_tdata_helper_handler(), netsnmp_cache_reqinfo_insert(), netsnmp_container_table_row_insert(), netsnmp_data_list_add_data(), netsnmp_insert_iterator_context(), netsnmp_insert_table_row(), netsnmp_instance_int_handler(), netsnmp_instance_long_handler(), netsnmp_instance_num_file_handler(), netsnmp_instance_ulong_handler(), netsnmp_read_data_callback(), netsnmp_register_auto_data_table(), netsnmp_register_handler_by_name(), netsnmp_register_save_list(), netsnmp_row_merge_status_get(), netsnmp_table_data_helper_handler(), netsnmp_table_data_set_helper_handler(), netsnmp_table_iterator_helper_handler(), netsnmp_watcher_helper_handler(), and table_helper_handler().
.SS "NETSNMP_INLINE \fBnetsnmp_data_list\fP* netsnmp_data_list_add_data (\fBnetsnmp_data_list\fP ** head, const char * name, void * data, Netsnmp_Free_List_Data * beer)"
.PP
adds data to a datalist 
.PP
\fBParameters:\fP
.RS 4
\fIhead\fP a pointer to the head node of a data_list 
.br
\fIname\fP the name of the node to cache the data. 
.br
\fIdata\fP the data to be stored under that name 
.br
\fIbeer\fP A function that can free the data pointer (in the future) 
.RE
.PP
\fBReturns:\fP
.RS 4
a newly created data_list node which was inserted in the list 
.RE
.PP

.PP
Definition at line 137 of file data_list.c.
.PP
References netsnmp_add_list_data(), netsnmp_create_data_list(), NULL, and snmp_log().
.SS "NETSNMP_INLINE void netsnmp_data_list_add_node (\fBnetsnmp_data_list\fP ** head, \fBnetsnmp_data_list\fP * node)"
.PP
adds data to a datalist 
.PP
\fBParameters:\fP
.RS 4
\fIhead\fP a pointer to the head node of a data_list 
.br
\fInode\fP a node to stash in the data_list 
.RE
.PP

.PP
Definition at line 93 of file data_list.c.
.PP
References netsnmp_data_list_s::name, netsnmp_data_list_s::next, NULL, and snmp_log().
.PP
Referenced by netsnmp_add_list_data().
.SS "NETSNMP_INLINE void netsnmp_free_all_list_data (\fBnetsnmp_data_list\fP * head)"
.PP
frees all data and nodes in a list. 
.PP
\fBParameters:\fP
.RS 4
\fIhead\fP the top node of the list to be freed. 
.RE
.PP

.PP
Definition at line 42 of file data_list.c.
.PP
References netsnmp_free_list_data(), netsnmp_data_list_s::next, and SNMP_FREE.
.PP
Referenced by netsnmp_clear_handler_list(), netsnmp_free_agent_data_sets(), netsnmp_free_agent_request_info(), netsnmp_free_request_data_sets(), and netsnmp_stash_to_next_helper().
.SS "NETSNMP_INLINE void netsnmp_free_list_data (\fBnetsnmp_data_list\fP * node)"
.PP
frees the data and a name at a given data_list node. 
.PP
Note that this doesn't free the node itself. 
.PP
\fBParameters:\fP
.RS 4
\fInode\fP the node for which the data should be freed 
.RE
.PP

.PP
Definition at line 26 of file data_list.c.
.PP
References netsnmp_data_list_s::data, netsnmp_data_list_s::free_func, netsnmp_data_list_s::name, and SNMP_FREE.
.PP
Referenced by netsnmp_free_agent_data_set(), netsnmp_free_all_list_data(), netsnmp_free_request_data_set(), and netsnmp_remove_list_node().
.SS "NETSNMP_INLINE void* netsnmp_get_list_data (\fBnetsnmp_data_list\fP * head, const char * name)"
.PP
returns a data_list node's data for a given name within a data_list 
.PP
\fBParameters:\fP
.RS 4
\fIhead\fP the head node of a data_list 
.br
\fIname\fP the name to find 
.RE
.PP
\fBReturns:\fP
.RS 4
a pointer to the data cached at that node 
.RE
.PP

.PP
Definition at line 162 of file data_list.c.
.PP
References netsnmp_data_list_s::name, netsnmp_data_list_s::next, and NULL.
.PP
Referenced by netsnmp_agent_get_list_data(), netsnmp_config_parse_add_row(), netsnmp_config_parse_table_set(), netsnmp_read_data_callback(), netsnmp_request_get_list_data(), and parse_injectHandler_conf().
.SS "NETSNMP_INLINE \fBnetsnmp_data_list\fP* netsnmp_get_list_node (\fBnetsnmp_data_list\fP * head, const char * name)"
.PP
returns a data_list node for a given name within a data_list 
.PP
\fBParameters:\fP
.RS 4
\fIhead\fP the head node of a data_list 
.br
\fIname\fP the name to find 
.RE
.PP
\fBReturns:\fP
.RS 4
a pointer to the data_list node 
.RE
.PP

.PP
Definition at line 180 of file data_list.c.
.PP
References netsnmp_data_list_s::name, netsnmp_data_list_s::next, and NULL.
.SS "void netsnmp_read_data_callback (const char * token, char * line)"
.PP
intended to be registerd as a .conf parser It should be registered using: 
.PP
register_app_config_handler('token', netsnmp_read_data_callback, XXX)
.PP
where INFO_POINTER is a pointer to a netsnmp_data_list_saveinfo object containing apporpriate registration information 
.PP
Definition at line 332 of file data_list.c.
.PP
References netsnmp_data_list_saveinfo_s::data_list_free_ptr, netsnmp_data_list_saveinfo_s::data_list_read_ptr, netsnmp_data_list_saveinfo_s::datalist, netsnmp_add_list_data(), netsnmp_create_data_list(), netsnmp_get_list_data(), NULL, read_config_read_data(), and snmp_log().
.PP
Referenced by netsnmp_register_save_list().
.SS "void netsnmp_register_save_list (\fBnetsnmp_data_list\fP ** datalist, const char * type, const char * token, Netsnmp_Save_List_Data * data_list_save_ptr, Netsnmp_Read_List_Data * data_list_read_ptr, Netsnmp_Free_List_Data * data_list_free_ptr)"
.PP
registers to store a data_list set of data at persistent storage time 
.PP
\fBParameters:\fP
.RS 4
\fIdatalist\fP the data to be saved 
.br
\fItype\fP the name of the application to save the data as. If left NULL the default application name that was registered during the init_snmp call will be used (recommended). 
.br
\fItoken\fP the unique token identifier string to use as the first word in the persistent file line. 
.br
\fIdata_list_save_ptr\fP a function pointer which will be called to save the rest of the data to a buffer. 
.br
\fIdata_list_read_ptr\fP a function pointer which can read the remainder of a saved line and return the application specific void * pointer. 
.br
\fIdata_list_free_ptr\fP a function pointer which will be passed to the data node for freeing it in the future when/if the list/node is cleaned up or destroyed.
.RE
.PP
\fBTodo\fP
.RS 4
netsnmp_register_save_list should handle the same token name being saved from different types? 
.RE
.PP

.PP
Definition at line 231 of file data_list.c.
.PP
References netsnmp_data_list_saveinfo_s::data_list_free_ptr, netsnmp_data_list_saveinfo_s::data_list_read_ptr, netsnmp_data_list_saveinfo_s::data_list_save_ptr, netsnmp_data_list_saveinfo_s::datalist, netsnmp_add_list_data(), netsnmp_create_data_list(), netsnmp_ds_get_string(), netsnmp_read_data_callback(), netsnmp_save_all_data_callback(), NULL, register_config_handler(), snmp_log(), SNMP_MALLOC_TYPEDEF, snmp_register_callback(), netsnmp_data_list_saveinfo_s::token, and netsnmp_data_list_saveinfo_s::type.
.SS "int netsnmp_remove_list_node (\fBnetsnmp_data_list\fP ** realhead, const char * name)"
.PP
Removes a named node from a data_list (and frees it). 
.PP
\fBParameters:\fP
.RS 4
\fIrealhead\fP a pointer to the head node of a data_list 
.br
\fIname\fP the name to find and remove 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on successful find-and-delete, 1 otherwise. 
.RE
.PP

.PP
Definition at line 198 of file data_list.c.
.PP
References netsnmp_free_list_data(), netsnmp_data_list_s::next, and NULL.
.PP
Referenced by netsnmp_agent_remove_list_data(), and netsnmp_request_remove_list_data().
.SS "int netsnmp_save_all_data (\fBnetsnmp_data_list\fP * head, const char * type, const char * token, Netsnmp_Save_List_Data * data_list_save_ptr)"
.PP
intended to be called as a callback during persistent save operations. 
.PP
See the netsnmp_save_all_data_callback for where this is typically used. 
.PP
Definition at line 297 of file data_list.c.
.PP
References netsnmp_data_list_s::data, netsnmp_data_list_s::name, netsnmp_data_list_s::next, read_config_save_octet_string(), read_config_store(), and SNMP_MAXBUF.
.PP
Referenced by netsnmp_save_all_data_callback().
.SS "int netsnmp_save_all_data_callback (int major, int minor, void * serverarg, void * clientarg)"
.PP
intended to be registerd as a callback operation. 
.PP
It should be registered using:
.PP
snmp_register_callback(SNMP_CALLBACK_LIBRARY, SNMP_CALLBACK_STORE_DATA, netsnmp_save_all_data_callback, INFO_POINTER);
.PP
where INFO_POINTER is a pointer to a netsnmp_data_list_saveinfo object containing apporpriate registration information 
.PP
Definition at line 280 of file data_list.c.
.PP
References netsnmp_data_list_saveinfo_s::data_list_save_ptr, netsnmp_data_list_saveinfo_s::datalist, netsnmp_save_all_data(), snmp_log(), netsnmp_data_list_saveinfo_s::token, and netsnmp_data_list_saveinfo_s::type.
.PP
Referenced by netsnmp_register_save_list().