net-snmp 5.7
Defines | Functions | Variables
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. More...

Defines

#define dirent   direct
#define NAMLEN(dirent)   (dirent)->d_namlen
#define SNMP_CONFIG_DELIMETERS   " \t="

Functions

 netsnmp_feature_child_of (read_config_all, libnetsnmp)
struct config_lineregister_prenetsnmp_mib_handler (const char *type, const char *token, void(*parser)(const char *, char *), void(*releaser)(void), const char *help)
struct config_lineregister_app_prenetsnmp_mib_handler (const char *token, void(*parser)(const char *, char *), void(*releaser)(void), const char *help)
struct config_lineregister_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.
struct config_lineregister_const_config_handler (const char *type, const char *token, void(*parser)(const char *, const char *), void(*releaser)(void), const char *help)
struct config_lineregister_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 (void)
struct config_lineread_config_get_handlers (const char *type)
int read_config_with_type_when (const char *filename, const char *type, int when)
int read_config_with_type (const char *filename, const char *type)
struct config_lineread_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)
int read_config (const char *filename, struct config_line *line_handler, int when)
void free_config (void)
int 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)
void set_persistent_directory (const char *dir)
const char * get_persistent_directory (void)
void set_temp_file_pattern (const char *pattern)
const char * get_temp_file_pattern (void)
int read_config_files_of_type (int when, struct config_files *ctmp)
int 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 netsnmp_config_error (const char *str,...)
void netsnmp_config_warn (const char *str,...)
void config_perror (const char *str)
void config_pwarn (const char *str)
char * skip_white (char *ptr)
const char * skip_white_const (const char *ptr)
char * skip_not_white (char *ptr)
const char * skip_not_white_const (const char *ptr)
char * skip_token (char *ptr)
const char * skip_token_const (const char *ptr)
char * copy_nword (char *from, char *to, int len)
const char * copy_nword_const (const 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 (const char *readfrom, u_char **str, size_t *len)
 Reads an octet string that was saved by the read_config_save_octet_string() function.
const char * read_config_read_octet_string_const (const 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)
const char * read_config_read_objid_const (const 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)

Variables

int linecount
int prev_linecount
const char * curfilename
const char * prev_filename

Detailed Description

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.


Function Documentation

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
Parameters:
typethe asn data type to be read in.
readfromthe configuration line data to be read.
dataptran allocated pointer expected to match the type being read (int *, u_int *, char **, oid **)
lenis the length of an asn oid or octet/bit string, not required for the asn integer, unsigned integer, and timeticks types
Returns:
the next token in the configuration line. NULL if none left or if an unknown type.

Definition at line 2110 of file read_config.c.

char* read_config_read_octet_string ( const char *  readfrom,
u_char **  str,
size_t *  len 
)

Reads an octet string that was saved by the read_config_save_octet_string() function.

Parameters:
[in]readfromPointer to the input data to be parsed.
[in,out]strPointer to the output buffer pointer. The data written to the output buffer will be '\0'-terminated. If *str == NULL, an output buffer will be allocated that is one byte larger than the data stored.
[in,out]lenIf str != NULL, *len is the size of the buffer *str points at. If str == NULL, the value passed via *len is ignored. Before this function returns the number of bytes read will be stored in *len. If a buffer overflow occurs, *len will be set to 0.
Returns:
A pointer to the next character in the input to be parsed if parsing succeeded; NULL when the end of the input string has been reached or if an error occurred.

Definition at line 1905 of file read_config.c.

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 "<NETSNMP_PERSISTENT_DIRECTORY>/<type>.conf". Adds a trailing newline to the stored file if necessary.

Parameters:
typeis the application name
lineis the configuration line written to the application name's configuration file
Returns:
void

Definition at line 1463 of file read_config.c.

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
Parameters:
typethe asn data type to be stored
storetoa pre-allocated char buffer which will contain the data to be stored
dataptrcontains the value to be stored, the supported pointers: (int *, u_int *, char **, oid **)
lenis the length of the value to be stored (not required for the asn integer, unsigned integer, and timeticks types)
Returns:
character pointer to the end of the line. NULL if an unknown type.

Definition at line 2264 of file read_config.c.

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

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

Library API routines concerned with configuration and control of the behaviour of the library, agent and other applications.

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.

Parameters:
typethe 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.
tokenthe token being parsed from the file. Must be non-NULL.
parserthe 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.
releaserif 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.
helpif non-NULL, used to display help information on the expected arguments after the token.
Returns:
Pointer to a new config line entry or NULL on error.

Definition at line 307 of file read_config.c.

void unregister_config_handler ( const char *  type_param,
const char *  token 
)

uregister_config_handler un-registers handlers given a specific type_param and token.

Parameters:
type_paramthe configuration file used where the token is located. Used to lookup the config file entry
tokenthe token that is being unregistered
Returns:
void

Definition at line 352 of file read_config.c.