--- name: "read_config" section: "3" platform: "linux" package: "libsnmp4.1-dev" version: "4.1.1-2.2" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/read_config" --- # read\_config(3) ## NAME register\_config\_handler, register\_premib\_handler unregister\_config\_handler, register\_mib\_handlers, read\_configs, read\_premib\_configs, config\_perror, config\_pwarn ## SYNOPSIS **#include \** **struct config\_line \***\ **register\_config\_handler(char \*filePrefix, char \*token,**\ **void (\*parser)(char \*, char \*) handler,** \ **void (\*releaser) (void) freefunc,**\ **char \*usageLine)** **struct config\_line \***\ **register\_premib\_handler(char \*filePrefix, char \*token,**\ **void (\*parser)(char \*, char \*) handler,** \ **void (\*releaser) (void) freefunc,**\ **char \*usageLine)** **struct config\_line \***\ **snmpd\_register\_config\_handler(char \*token,**\ **void (\*parser)(char \*, char \*) handler,** \ **void (\*releaser) (void) freefunc,**\ **char \*usageLine)** **void unregister\_config\_handler(char \*filePrefix,** \ **char \*token)** **void read\_config\_print\_usage(char \*lead)** **void read\_configs(void)** **void read\_premib\_configs(void)** ## DESCRIPTION The functions are a fairly extensible system of parsing various configuration files at the run time of an application. The configuration file flow is broken into the following phases: registration of handlers. reading of the configuration files for pre-mib parsing requirements. reading of the textual mib files. reading of the configuration files for configuration directives. optionally re-reading of the configuration files at a future date. 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. ## Token Handlers Handler functions should be of the following type: void handler(char \*token, char \*line); The function will be called with two arguments, the first being the token that triggered the call to this function (which would be one of the tokens that the function had been registered for), and the second being the remainder of the configuration file line beyond the white space following the token. ## Resource Freeing Handlers If the read\_config configuration system is called a second time to re-read the configuration files, the optional second handler *freefunc* will be called, if registered as non-NULL, to free any resources and reset its notions to defaults before the config handlers are called again. It is not called with any arguments. ## Registering A Handler - register\_config\_handler() The handler above could then be registered for the configuration file *snmp.conf,* with the token *genericToken* and the help string (discussed later) *ARG1 ARG2* using the following call to the **register\_config\_handler()** function: register\_config\_handler("snmp", "genericToken", handler, NULL, "ARG1 ARG2"); - This would register the **handler()** function so that it will get called every time the first word in the *snmp.conf* configuration file(s) matches "genericToken" (see **read\_configs()** below). - register\_premib\_handler() The **register\_premib\_handler()** function works identically to the **register\_config\_handler()** function but is intended for config file tokens that need to be read in before the textual mibs are read in, probably because they will be used to configure the mib parser. It is rarely the case that anything but the snmp library itself should need to use this function. - snmpd\_register\_config\_handler() This function performs exactly the same job as the **register\_config\_handler()** function, but doesn't require the file type argument (which is filled in by the snmpd agent). It is intended that mib modules written for the agent use this function instead of the **register\_config\_handler()** function directly to allow the agent to have more control over which files the mib modules will read (which should be the *snmpd.conf* files). - unregister\_config\_handler() Removes the registered configuration handler for the *filePrefix* and *token* - ## Help Strings The *usageLine* token passed to the register\_config\_handler(), and similar calls, is used to display help information when the **read\_config\_print\_usage()** function is called. This function is used by all of the applications when the **-H** flag is passed to the command line. It prints a summary of all of the configuration file lines, and the associated files, that the configuration system understands. The usageLine parameter should be a list of arguments expected after the token, and not a lengthy description (which should go into a manual page instead). The *lead* prefix will be prepended to each line that the function prints to stderr, where it displays its output. The **init\_snmp()** function should be called before the **read\_config\_print\_usage()** function is called, so that the library can register its configuration file directives as well for the **read\_config\_print\_usage()** function to display. ## Reading Configuration Files - init\_snmp() The **init\_snmp()** function call should be called after registrations to appropriately register parser configuration tokens, parse the configuration file tokens registered with **register\_premib\_handler(),** read in the textual mib files using **init\_mib(),** and finally parse the configuration file tokens registered with **register\_config\_handler().** If the **init\_snmp()** function is used, none of the following functions need to be called by the application: - register\_mib\_handlers() The snmp library's routine to register it's configuration file handlers. - read\_premib\_configs() The routine that parses the configuration files for tokens registered to be dealt with before the textual mibs are read in. See **read\_configs()** below. - read\_configs() Reads all the configuration files it can find in the *SNMPCONFPATH* environment variable (or its default value) for tokens and appropriately calls the handlers registered to it, or prints a "Unknown token" warning message. It looks for any file that it has previously received a registration request for. ## Configuration Files Read The configuration files read are found by using the colon separated *SNMPCONFPATH* environment variable (or its default value, which will be /etc/snmp, followed by /usr/lib/snmp, followed by $HOME/.snmp) and reading in the files found that match both the prefix registered and the two suffixes *.conf* and *.local.conf.* The idea behind the two different suffixes is that the first file can be rdisted across a large number of machines and the second file can be used to configure local settings for one particular machine. They do not need to be present, and will only be read if found. ## Error Handling Functions The two functions **config\_pwarn()** and **config\_perror()** both take an error string as an argument and print it to stderr along with the file and line number that caused the error. A call to the second function will also force read\_configs() to eventually return with an error code indicating to it's calling function that it should abort the operation of the application. ## ENVIRONMENT VARIABLES - SNMPCONFPATH A colon separated list of directories to search for configuration files in. Default: /etc/snmp:/usr/lib/snmp:$HOME/.snmp ## SEE ALSO [mib\_api(3)](/mib_api/3.md), [snmp\_api(3)](/snmp_api/3.md)