unregister_app_config_handler man page on Scientific

Man page or keyword search:  
man Server   26626 pages
apropos Keyword Search (all sections)
Output format
Scientific logo
[printable version]

CONFIG_API(3)			   Net-SNMP			 CONFIG_API(3)

NAME
       register_config_handler, register_premib_handler unregister_config_han‐
       dler, register_mib_handlers,  read_configs,  read_premib_configs,  con‐
       fig_perror, config_pwarn - config_api functions

SYNOPSIS
       #include <net-snmp/config_api.h>

       struct config_line *
	 register_config_handler(const char *filePrefix,
			    const char *token,
			    void (*parser)(const char *, char *),
			    void (*releaser)(void),
			    const char *usageLine);

       struct config_line *
	 register_premib_handler(const char *filePrefix,
			    const char *token,
			    void (*parser)(const char *, char *),
			    void (*releaser)(void),
			    const char *usageLine);

       void register_mib_handlers(void);

       void unregister_config_handler(const char *filePrefix,
			    const char *token);

       void unregister_all_config_handlers(void);

   Application Handlers
       struct config_line *
	 register_app_config_handler(const char *token,
			    void (*parser)(const char *, char *),
			    void (*releaser)(void),
			    const char *usageLine);

       struct config_line *
	 register_app_premib_handler(const char *token,
			    void (*parser)(const char *, char *),
			    void (*releaser)(void),
			    const char *usageLine);

       void unregister_app_config_handler(const char *token);

   Reading Configuration Files
       void read_premib_configs(void);
       void read_configs(void);

   Help Strings and Errors
       void read_config_print_usage(char *lead);
       void config_pwarn(const char *string);
       void config_perror(const char *string);

DESCRIPTION
       The functions are a fairly extensible system of parsing various config‐
       uration files at the run time of	 an  application.   The	 configuration
       file flow is broken into the following phases:

	   1.  Registration of handlers.

	   2.  Reading of the configuration files for pre-MIB parsing require‐
	       ments.

	   3.  Reading and parsing of the textual MIB files.

	   4.  Reading of the configuration  files  for	 configuration	direc‐
	       tives.

	   5.  Optionally re-reading 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 named configuration files.  The
       read_configs()  function	 can  then  be called to look for all relevant
       configuration files, match the first word on each line against the list
       of  registered  tokens and pass the remainder of the line to the appro‐
       priate registered handler.

REGISTERING A HANDLER
       register_config_handler()
	      Registers a  configuration  handler  routine,  which  should  be
	      called  to  process  configuration  directives starting with the
	      specified token.	For example:

		     register_config_handler("snmp",   "exampleToken",	 exam‐
		     ple_handler, NULL, "ARG1 [ARG2]");

	      would  register  the  example_handler() function so that it will
	      get called every time the first word of a line in the  snmp.conf
	      configuration file(s) matches "exampleToken".
	      Calling  the  appropriate	 handlers to process the configuration
	      file directives is the  responsibility  of  read_configs()  (see
	      below).

       register_premib_handler()
	      Similar  to the register_config_handler() function, but the reg‐
	      istered handler routine will be called before the	 textual  MIBs
	      are read in.  This is typically used for tokens that will affect
	      the configuration of the MIB parser, and will normally  only  be
	      used within the SNMP library itself.

       register_mib_handlers()
	      Initialisation  routine  to  register  the internal SNMP library
	      configuration handlers.

       unregister_config_handler()
	      Removes the registered configuration handler for	the  specified
	      filePrefix and token.

       unregister_all_config_handlers()
	      Removes all registered configuration handlers.

   Token Handlers
       Handler functions should have the following signature:

	      void handler(const char *token, char *line);

       The  function  will  be	called with two arguments, the first being the
       token that triggered the call to this function  (i.e.  the  token  used
       when  registering  the  handler), and the second being the remainder of
       the configuration file line (i.e. everything following the white	 space
       following the matched token).

   Freeing Handlers
       If the token handler function dynamically allocates resources when pro‐
       cessing a configuration entry, then  these  may	need  to  be  released
       before  re-reading  the configuration files.  If the fourth parameter (
       releaser ) passed to register_config_handler  is	 non-NULL,  then  this
       specifies  a  function to be called before re-reading the configuration
       files.  This function should free any resources allocated by the	 token
       handler	function  and  reset  its  notion  of the configuration to its
       default.	 The token handler function can then safely be	called	again.
       No arguments are passed to the resource freeing handler.
       Note  that this function is not called when the handler is unregistered
       individually (but is called as part of unregister_all_config_handlers()
       ).

   Application Handlers
       register_app_config_handler()

       register_app_premib_handler()

       unregister_app_config_handler()
	      These functions are analagous to register_config_handler(), reg‐
	      ister_premib_handler() and  unregister_config_handler()  but  do
	      not  require  the	 file type argument (which is filled in by the
	      application).  It is intended that MIB modules written  for  the
	      agent  use  these functions to allow the agent to have more con‐
	      trol over which configuration  files  are	 read  (typically  the
	      snmpd.conf files).

READING CONFIGURATION FILES
       read_premib_configs()

       read_configs()
	      These routines process the configuration files found in the con‐
	      figuration search path (see below).  For each entry, the handler
	      registered for that configuration token is called.

       read_premib_configs() is run before the MIB files are read in, and pro‐
       cesses those configuration tokens registered using register_premib_han‐
       dler()  (or  register_app_premib_handler()  ).	All  other entries are
       ignored.

       read_configs() is run after the MIB files have been read in,  and  pro‐
       cesses those configuration tokens registered using register_config_han‐
       dler() (or register_app_config_handler() ).  If it encounters a config‐
       uration	token for which no handler has been registered (either pre- or
       post-mib), then it will display a warning message,  and	continue  pro‐
       cessing with the next line of the configuration file.

   Configuration Search Path
       The  configuration  files  to  be read are found by searching a list of
       configuration directories for appropriately named files.	 In each  such
       directory, the library will look for files named
	snmp.conf,
	snmp.local.conf,  app.conf,  app.local.conf, (where app is the appica‐
       tion-specific filePrefix used to register configuration handlers).   It
       is  not	necessary  for any or all of these files to be present in each
       directory.  Missing files will be silently skipped.
       The idea behind the two different suffixes is that the first  file  can
       be shared (via rdist or an NFS mount) across a large number of machines
       and the second file can be used to configure  local  settings  for  one
       particular machine.

       The  default  list  of  directories to search is /etc/snmp, followed by
       /usr/share/snmp,	  followed   by	  /usr/lib(64)/snmp,	followed    by
       $HOME/.snmp.   This  list  can  be changed by setting the environmental
       variable SNMPCONFPATH to be a (colon separated) list of directories  to
       search.

   init_snmp()
       The  normal mode of operation would be to register the application-spe‐
       cific configuration handlers, and then invoke init_snmp().  This	 would
       call the routines listed above to register the internal library config‐
       uration handlers, process any configuration tokens registered with reg‐
       ister_premib_handler(), read in the textual MIB files using init_mib(),
       and finally parse the configuration file tokens registered with	regis‐
       ter_config_handler().

       If the init_snmp() function is used, none of these functions need to be
       explicitly called by the application.

HELP STRINGS AND ERRORS
       The usageLine parameter passed to register_config_handler() and similar
       calls,	is  used  to  display  help  information  when	the  read_con‐
       fig_print_usage() function is called.  This function is used by all  of
       the  applications  when	the -H flag is passed on the command line.  It
       prints a summary of all of the configuration file lines, and the	 asso‐
       ciated 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_con‐
       fig_print_usage() function is called, so that the library can  register
       its   configuration   file   directives	 as  well  for	the  read_con‐
       fig_print_usage() function to display.

   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 indi‐
       cating 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 configu‐
		 ration		   files	     in.	      Default:
		 /etc/snmp:/usr/share/snmp:/usr/lib(64)/snmp:$HOME/.snmp

SEE ALSO
       mib_api(3), snmp_api(3)

4.2 Berkeley Distribution	  07 Mar 2002			 CONFIG_API(3)
[top]

List of man pages available for Scientific

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net