parsing various configuration files at run time
[The Net-SNMP library]

The read_config related functions are a fairly extensible system of parsing various configuration files at the run time. [詳細]


マクロ定義
#define	SNMP_CONFIG_DELIMETERS " \t="
関数
config_line *	register_prenetsnmp_mib_handler (const char type, const char token, void(parser)(const char , char ), void(releaser)(void), const char *help)
config_line *	register_app_prenetsnmp_mib_handler (const char token, void(parser)(const char , char ), void(releaser)(void), const char help)
config_line *	register_config_handler (const char type, const char token, void(parser)(const char , char ), void(releaser)(void), const char *help)
	register_config_handler registers handlers for certain tokens specified in certain types of files.
config_line *	register_app_config_handler (const char token, void(parser)(const char , char ), void(releaser)(void), const char help)
void	unregister_config_handler (const char type_param, const char token)
	uregister_config_handler un-registers handlers given a specific type_param and token.
void	unregister_app_config_handler (const char *token)
void	unregister_all_config_handlers ()
config_line *	read_config_get_handlers (const char *type)
void	read_config_with_type_when (const char filename, const char type, int when)
void	read_config_with_type (const char filename, const char type)
config_line *	read_config_find_handler (struct config_line line_handlers, const char token)
int	run_config_handler (struct config_line lptr, const char token, char *cptr, int when)
int	snmp_config_when (char *line, int when)
int	netsnmp_config (char *line)
void	netsnmp_config_remember_in_list (char line, struct read_config_memory *mem)
void	netsnmp_config_remember_free_list (struct read_config_memory **mem)
void	netsnmp_config_process_memory_list (struct read_config_memory **memp, int when, int clear)
void	netsnmp_config_remember (char *line)
void	netsnmp_config_process_memories (void)
void	netsnmp_config_process_memories_when (int when, int clear)
void	read_config (const char filename, struct config_line line_handler, int when)
void	free_config (void)
void	read_configs_optional (const char *optional_config, int when)
void	read_configs (void)
void	read_premib_configs (void)
void	set_configuration_directory (const char *dir)
const char *	get_configuration_directory ()
void	set_persistent_directory (const char *dir)
const char *	get_persistent_directory ()
void	set_temp_file_pattern (const char *pattern)
const char *	get_temp_file_pattern ()
void	read_config_files (int when)
void	read_config_print_usage (const char *lead)
void	read_config_store (const char type, const char line)
	read_config_store intended for use by applications to store permenant configuration information generated by sets or persistent counters.
void	read_app_config_store (const char *line)
void	snmp_save_persistent (const char *type)
void	snmp_clean_persistent (const char *type)
void	config_perror (const char *str)
void	config_pwarn (const char *str)
char *	skip_white (char *ptr)
char *	skip_not_white (char *ptr)
char *	skip_token (char *ptr)
char *	copy_nword (char from, char to, int len)
char *	copy_word (char from, char to)
char *	read_config_save_octet_string (char saveto, u_char str, size_t len)
char *	read_config_read_octet_string (char readfrom, u_char str, size_t len)
char *	read_config_save_objid (char saveto, oid objid, size_t len)
char *	read_config_read_objid (char readfrom, oid objid, size_t len)
char *	read_config_read_data (int type, char readfrom, void dataptr, size_t *len)
	read_config_read_data reads data of a given type from a token(s) on a configuration line.
char *	read_config_read_memory (int type, char readfrom, char dataptr, size_t *len)
char *	read_config_store_data (int type, char storeto, void dataptr, size_t *len)
	read_config_store_data stores data of a given type to a configuration line into the storeto buffer.
char *	read_config_store_data_prefix (char prefix, int type, char storeto, void dataptr, size_t len)
変数
config_files *	config_files = NULL
int	linecount
const char *	curfilename

説明

The read_config related functions are a fairly extensible system of parsing various configuration files at the run time.

The idea is that the calling application is able to register handlers for certain tokens specified in certain types of files. The read_configs function can then be called to look for all the files that it has registrations for, find the first word on each line, and pass the remainder to the appropriately registered handler.

For persistent configuration storage you will need to use the read_config_read_data, read_config_store, and read_config_store_data APIs in conjunction with first registering a callback so when the agent shutsdown for whatever reason data is written to your configuration files. The following explains in more detail the sequence to make this happen.

This is the callback registration API, you need to call this API with the appropriate parameters in order to configure persistent storage needs.

int snmp_register_callback(int major, int minor, SNMPCallback *new_callback, void *arg);

You will need to set major to SNMP_CALLBACK_LIBRARY, minor to SNMP_CALLBACK_STORE_DATA. arg is whatever you want.

Your callback function's prototype is: int (SNMPCallback) (int majorID, int minorID, void *serverarg, void *clientarg);

The majorID, minorID and clientarg are what you passed in the callback registration above. When the callback is called you have to essentially transfer all your state from memory to disk. You do this by generating configuration lines into a buffer. The lines are of the form token followed by token parameters.

Finally storing is done using read_config_store(type, buffer); type is the application name this can be obtained from:

netsnmp_ds_get_string(NETSNMP_DS_LIBRARY_ID, NETSNMP_DS_LIB_APPTYPE);

Now, reading back the data: This is done by registering a config handler for your token using the register_config_handler function. Your handler will be invoked and you can parse in the data using the read_config_read APIs.

関数

char* read_config_read_data	(	int	type,
		char *	readfrom,
		void *	dataptr,
		size_t *	len
	)

read_config_read_data reads data of a given type from a token(s) on a configuration line.

The supported types are:

ASN_INTEGER
ASN_TIMETICKS
ASN_UNSIGNED
ASN_OCTET_STR
ASN_BIT_STR
ASN_OBJECT_ID

引数:

	type	the asn data type to be read in.
	readfrom	the configuration line data to be read.
	dataptr	an allocated pointer expected to match the type being read (int , u_int , char , oid )
	len	is the length of an asn oid or octet/bit string, not required for the asn integer, unsigned integer, and timeticks types

戻り値:: the next token in the configuration line. NULL if none left or if an unknown type.

read_config.c の 1830 行で定義されています。

参照先 NULL・read_config_read_objid()・read_config_read_octet_string()・skip_token().

参照元 netsnmp_read_data_callback().

void read_config_store	(	const char *	type,
		const char *	line
	)

read_config_store intended for use by applications to store permenant configuration information generated by sets or persistent counters.

Appends line to a file named either ENV(SNMP_PERSISTENT_FILE) or "<PERSISTENT_DIRECTORY>/<type>.conf". Adds a trailing newline to the stored file if necessary.

引数:

	type	is the application name
	line	is the configuration line written to the application name's configuration file

戻り値:: void

read_config.c の 1266 行で定義されています。

参照先 get_persistent_directory()・netsnmp_ds_get_boolean()・netsnmp_getenv()・NULL・snmp_log().

参照元 netsnmp_oid_stash_store()・netsnmp_save_all_data()・read_app_config_store()・snmp_save_persistent().

char* read_config_store_data	(	int	type,
		char *	storeto,
		void *	dataptr,
		size_t *	len
	)

read_config_store_data stores data of a given type to a configuration line into the storeto buffer.

Calls read_config_store_data_prefix with the prefix parameter set to a char space. The supported types are:

ASN_INTEGER
ASN_TIMETICKS
ASN_UNSIGNED
ASN_OCTET_STR
ASN_BIT_STR
ASN_OBJECT_ID

引数:

	type	the asn data type to be stored
	storeto	a pre-allocated char buffer which will contain the data to be stored
	dataptr	contains the value to be stored, the supported pointers: (int , u_int , char , oid )
	len	is the length of the value to be stored (not required for the asn integer, unsigned integer, and timeticks types)

戻り値:: character pointer to the end of the line. NULL if an unknown type.

read_config.c の 1969 行で定義されています。

参照先 read_config_store_data_prefix().

struct config_line* register_config_handler	(	const char *	type,
		const char *	token,
		void()(const char , char *)	parser,
		void(*)(void)	releaser,
		const char *	help
	)

register_config_handler registers handlers for certain tokens specified in certain types of files.

Allows a module writer use/register multiple configuration files based off of the type parameter. A module writer may want to set up multiple configuration files to separate out related tasks/variables or just for management of where to put tokens as the module or modules get more complex in regard to handling token registrations.

引数:

	type_param	the configuration file used, e.g., if snmp.conf is the file where the token is located use "snmp" here. Multiple colon separated tokens might be used. If NULL or "" then the configuration file used will be <application>.conf.
	token	the token being parsed from the file. Must be non-NULL.
	parser	the handler function pointer that use the specified token and the rest of the line to do whatever is required Should be non-NULL in order to make use of this API.
	releaser	if non-NULL, the function specified is called if and when the configuration files are re-read. This function should free any resources allocated by the token handler function.
	help	if non-NULL, used to display help information on the expected arguments after the token.