documentation. Can't get enough.
- make docs now installs man pages into the man dir, which are then installed.
git-svn-id: file:///home/hardaker/lib/sf-bkups/net-snmp-convert-svnrepo/trunk@6901 06827809-a52a-0410-b366-d66718629ded
diff --git a/man/netsnmp_handler.3 b/man/netsnmp_handler.3
new file mode 100644
index 0000000..01debd8
--- /dev/null
+++ b/man/netsnmp_handler.3
@@ -0,0 +1,419 @@
+.TH "Agent handler API" 3 "19 Apr 2002" "net-snmp" \" -*- nroff -*-
+.ad l
+.nh
+.SH NAME
+Agent handler API \- The basic theory goes something like this: In the past, with the original mib module api (which derived from the original CMU SNMP code) the underlying mib modules were passed very little information (only the truly most basic information about a request).
+More...
+.SS "Modules"
+
+.in +1c
+.ti -1c
+.RI "\fBtable: Helps you implement a table.\fP"
+.br
+.RI "\fIThis handler helps you implement a table by doing some of the processing for you.\fP"
+.PP
+.in +1c
+
+.ti -1c
+.RI "\fBserialize: Calls sub handlers one request at a time.\fP"
+.br
+.RI "\fIThis functionally passes in one request at a time into lower handlers rather than a whole bunch of requests at once.\fP"
+.PP
+.in +1c
+
+.ti -1c
+.RI "\fBread_only: make your handler read_only automatically\fP"
+.br
+.RI "\fIThe only purpose of this handler is to return an appropriate error for any requests passed to it in a SET mode.\fP"
+.PP
+.in +1c
+
+.ti -1c
+.RI "\fBold_api: Calls mib module code written in the old style of code.\fP"
+.br
+.RI "\fIThis is a backwards compatilibity module that allows code written in the old API to be run under the new handler based architecture.\fP"
+.PP
+.in +1c
+
+.ti -1c
+.RI "\fBmultiplexer: splits mode requests into calls to different handlers.\fP"
+.br
+.RI "\fIThe multiplexer helper lets you split the calling chain depending on the calling mode (get vs getnext vs set).\fP"
+.PP
+.in +1c
+
+.ti -1c
+.RI "\fBinstance: process scalars and other instances easily.\fP"
+.br
+.ti -1c
+.RI "\fBdebug: print out debugging information about the handler chain being called.\fP"
+.br
+.RI "\fIThis is a useful module for run-time debugging of requests as the pass this handler in a calling chain.\fP"
+.PP
+.in +1c
+
+.ti -1c
+.RI "\fBbulk_to_next: convert GETBULK requests into GETNEXT requests for the handler.\fP"
+.br
+.RI "\fIThe only purpose of this handler is to convert a GETBULK request to a GETNEXT request.\fP"
+.PP
+
+.in -1c
+.SS "Functions"
+
+.in +1c
+.ti -1c
+.RI "netsnmp_mib_handler * \fBnetsnmp_create_handler\fP (const char *name, Netsnmp_Node_Handler *handler_access_method)"
+.br
+.RI "\fIcreates a netsnmp_mib_handler structure given a name and a access method.\fP"
+.ti -1c
+.RI "netsnmp_handler_registration * \fBnetsnmp_create_handler_registration\fP (const char *name, Netsnmp_Node_Handler *handler_access_method, oid *reg_oid, size_t reg_oid_len, int modes)"
+.br
+.RI "\fIcreates a handler registration structure given a name, a access_method function, a registration location oid and the modes the handler supports.\fP"
+.ti -1c
+.RI "int \fBnetsnmp_register_handler\fP (netsnmp_handler_registration *reginfo)"
+.br
+.RI "\fIregister a handler, as defined by the netsnmp_handler_registration pointer.\fP"
+.ti -1c
+.RI "int \fBnetsnmp_register_handler_nocallback\fP (netsnmp_handler_registration *reginfo)"
+.br
+.RI "\fIregister a handler, as defined by the netsnmp_handler_registration pointer.\fP"
+.ti -1c
+.RI "int \fBnetsnmp_inject_handler\fP (netsnmp_handler_registration *reginfo, netsnmp_mib_handler *handler)"
+.br
+.RI "\fIinject a new handler into the calling chain of the handlers definedy by the netsnmp_handler_registration pointer.\fP"
+.ti -1c
+.RI "int \fBnetsnmp_call_handlers\fP (netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests)"
+.br
+.ti -1c
+.RI "int \fBnetsnmp_call_handler\fP (netsnmp_mib_handler *next_handler, netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests)"
+.br
+.RI "\fIcalls a handler with with appropriate NULL checking of arguments, etc.\fP"
+.ti -1c
+.RI "int \fBnetsnmp_call_next_handler\fP (netsnmp_mib_handler *current, netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests)"
+.br
+.RI "\fIcalls the next handler in the chain after the current one with with appropriate NULL checking, etc.\fP"
+.ti -1c
+.RI "void \fBnetsnmp_handler_free\fP (netsnmp_mib_handler *handler)"
+.br
+.RI "\fIfree's the resourceses associated with a given handler.\fP"
+.ti -1c
+.RI "netsnmp_mib_handler * \fBnetsnmp_handler_dup\fP (netsnmp_mib_handler *handler)"
+.br
+.RI "\fIdulpicates a handler.\fP"
+.ti -1c
+.RI "void \fBnetsnmp_handler_registration_free\fP (netsnmp_handler_registration *reginfo)"
+.br
+.RI "\fIfree the resources associated with a handler registration object.\fP"
+.ti -1c
+.RI "netsnmp_handler_registration * \fBnetsnmp_handler_registration_dup\fP (netsnmp_handler_registration *reginfo)"
+.br
+.RI "\fIduplicates the handler registration object.\fP"
+.ti -1c
+.RI "netsnmp_delegated_cache * \fBnetsnmp_create_delegated_cache\fP (netsnmp_mib_handler *handler, netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests, void *localinfo)"
+.br
+.RI "\fIcreates a cache of information which can be saved for future reference.\fP"
+.ti -1c
+.RI "netsnmp_delegated_cache * \fBnetsnmp_handler_check_cache\fP (netsnmp_delegated_cache *dcache)"
+.br
+.RI "\fIcheck's a given cache and returns it if it is still valid (ie, the agent still considers it to be an outstanding request.\fP"
+.ti -1c
+.RI "void \fBnetsnmp_free_delegated_cache\fP (netsnmp_delegated_cache *dcache)"
+.br
+.RI "\fIfrees a cache once you're finished using it.\fP"
+.ti -1c
+.RI "void \fBnetsnmp_handler_mark_requests_as_delegated\fP (netsnmp_request_info *requests, int isdelegated)"
+.br
+.RI "\fImarks a list of requests as delegated (or not if isdelegaded = 0).\fP"
+.ti -1c
+.RI "void \fBnetsnmp_request_add_list_data\fP (netsnmp_request_info *request, netsnmp_data_list *node)"
+.br
+.RI "\fIadd data to a request that can be extracted later by submodules.\fP"
+.ti -1c
+.RI "void * \fBnetsnmp_request_get_list_data\fP (netsnmp_request_info *request, const char *name)"
+.br
+.RI "\fIextract data from a request that was added previously by a parent module.\fP"
+.ti -1c
+.RI "void \fBnetsnmp_free_request_data_set\fP (netsnmp_request_info *request)"
+.br
+.RI "\fIFree the extra data stored in a request.\fP"
+.ti -1c
+.RI "void \fBnetsnmp_free_request_data_sets\fP (netsnmp_request_info *request)"
+.br
+.RI "\fIFree the extra data stored in a bunch of requests (all data in the chain).\fP"
+.ti -1c
+.RI "netsnmp_mib_handler * \fBnetsnmp_find_handler_by_name\fP (netsnmp_handler_registration *reginfo, const char *name)"
+.br
+.RI "\fIReturns a handler from a chain based on the name.\fP"
+.ti -1c
+.RI "void * \fBnetsnmp_find_handler_data_by_name\fP (netsnmp_handler_registration *reginfo, const char *name)"
+.br
+.RI "\fIReturns a handler's void * pointer from a chain based on the name.\fP"
+.ti -1c
+.RI "netsnmp_mib_handler * \fBclone_handler\fP (netsnmp_mib_handler *it)"
+.br
+.RI "\fIclones a mib handler (it's name and access methods onlys; not myvoid).\fP"
+.ti -1c
+.RI "void \fBnetsnmp_register_handler_by_name\fP (const char *name, netsnmp_mib_handler *handler)"
+.br
+.RI "\fIregisters a given handler by name so that it can be found easily later.\fP"
+.ti -1c
+.RI "void \fBnetsnmp_inject_handler_into_subtree\fP (struct subtree *tp, const char *name, netsnmp_mib_handler *handler)"
+.br
+.ti -1c
+.RI "void \fBparse_injectHandler_conf\fP (const char *token, char *cptr)"
+.br
+.ti -1c
+.RI "void \fBnetsnmp_init_handler_conf\fP (void)"
+.br
+.in -1c
+.SH "DETAILED DESCRIPTION"
+.PP
+The basic theory goes something like this: In the past, with the original mib module api (which derived from the original CMU SNMP code) the underlying mib modules were passed very little information (only the truly most basic information about a request).
+.PP
+This worked well at the time but in todays world of subagents, device instrumentation, low resource consumption, etc, it just isn't flexible enough. 'handlers' are here to fix all that.
+.PP
+With the rewrite of the agent internals for the net-snmp 5.0 release, we introduce a modular calling scheme that allows agent modules to be written in a very flexible manner, and more importantly allows reuse of code in a decent way (and without the memory and speed overheads of OO languages like C++).
+.PP
+Functionally, the notion of what a handler does is the same as the older api: A handler is \fBcreated\fP and then \fBregistered\fP with the main agent at a given OID in the OID tree and gets called any time a request is made that it should respond to. You probably should use one of the convenience helpers instead of doing anything else yourself though:
+.PP
+Most importantly, though, is that the handlers are built on the notion of modularity and reuse. Specifically, rather than do all the really hard work (like parsing table indexes out of an incoming oid request) in each module, the API is designed to make it easy to write 'helper' handlers that merely process some aspect of the request before passing it along to the final handler that returns the real answer. Most people will want to make use of the instance, table, table_iterator, table_data, or table_dataset helpers to make their life easier. These 'helpers' interpert important aspects of the request and pass them on to you.
+.PP
+For instance, the table helper is designed to hand you a list of extracted index values from an incoming request. THe table_iterator helper is built on top of the table helper, and is designed to help you iterate through data stored elsewhere (like in a kernel) that is not in OID lexographical order (ie, don't write your own index/oid sorting routine, use this helper instead). The beauty of the
+.SH "FUNCTION DOCUMENTATION"
+.PP
+.SS "netsnmp_mib_handler* clone_handler (netsnmp_mib_handler * it)"
+.PP
+clones a mib handler (it's name and access methods onlys; not myvoid).
+.PP
+Definition at line 578 of file agent_handler.c.
+.SS "int netsnmp_call_handler (netsnmp_mib_handler * next_handler, netsnmp_handler_registration * reginfo, netsnmp_agent_request_info * reqinfo, netsnmp_request_info * requests)\fC [inline]\fP"
+.PP
+calls a handler with with appropriate NULL checking of arguments, etc.
+.PP
+Definition at line 277 of file agent_handler.c.
+.PP
+Referenced by netsnmp_call_next_handler(), and netsnmp_multiplexer_helper_handler().
+.PP
+.SS "int netsnmp_call_handlers (netsnmp_handler_registration * reginfo, netsnmp_agent_request_info * reqinfo, netsnmp_request_info * requests)"
+.PP
+.PP
+For internal use only.
+.PP
+Definition at line 219 of file agent_handler.c.
+.SS "int netsnmp_call_next_handler (netsnmp_mib_handler * current, netsnmp_handler_registration * reginfo, netsnmp_agent_request_info * reqinfo, netsnmp_request_info * requests)\fC [inline]\fP"
+.PP
+calls the next handler in the chain after the current one with with appropriate NULL checking, etc.
+.PP
+Definition at line 310 of file agent_handler.c.
+.PP
+Referenced by netsnmp_bulk_to_next_helper(), netsnmp_debug_helper(), netsnmp_read_only_helper(), netsnmp_serialize_helper_handler(), netsnmp_table_data_helper_handler(), netsnmp_table_data_set_helper_handler(), and table_helper_handler().
+.PP
+.SS "netsnmp_delegated_cache* netsnmp_create_delegated_cache (netsnmp_mib_handler * handler, netsnmp_handler_registration * reginfo, netsnmp_agent_request_info * reqinfo, netsnmp_request_info * requests, void * localinfo)\fC [inline]\fP"
+.PP
+creates a cache of information which can be saved for future reference.
+.PP
+Use \fBnetsnmp_handler_check_cache\fP() later to make sure it's still valid before referencing it in the future.
+.PP
+\fBExamples: \fP
+.in +1c
+\fBdelayed_instance.c\fP.
+.PP
+Definition at line 453 of file agent_handler.c.
+.SS "netsnmp_mib_handler* netsnmp_create_handler (const char * name, Netsnmp_Node_Handler * handler_access_method)"
+.PP
+creates a netsnmp_mib_handler structure given a name and a access method.
+.PP
+The returned handler should then be \fBregistered.\fP
+.PP
+\fBSee also: \fP
+.in +1c
+\fBnetsnmp_create_handler_registration\fP() , \fBnetsnmp_register_handler\fP()
+.PP
+Definition at line 78 of file agent_handler.c.
+.PP
+Referenced by clone_handler(), get_old_api_handler(), netsnmp_create_handler_registration(), netsnmp_get_bulk_to_next_handler(), netsnmp_get_debug_handler(), netsnmp_get_multiplexer_handler(), netsnmp_get_read_only_handler(), netsnmp_get_serialize_handler(), netsnmp_get_table_data_handler(), netsnmp_get_table_data_set_handler(), and netsnmp_get_table_handler().
+.PP
+.SS "netsnmp_handler_registration* netsnmp_create_handler_registration (const char * name, Netsnmp_Node_Handler * handler_access_method, oid * reg_oid, size_t reg_oid_len, int modes)"
+.PP
+creates a handler registration structure given a name, a access_method function, a registration location oid and the modes the handler supports.
+.PP
+If modes == 0, then modes will automatically be set to the default value of only HANDLER_CAN_DEFAULT, which is by default read-only GET and GETNEXT requests.
+.PP
+\fBNote: \fP
+.in +1c
+This ends up calling netsnmp_create_handler(name, handler_access_method)
+.PP
+\fBSee also: \fP
+.in +1c
+\fBnetsnmp_create_handler\fP() , \fBnetsnmp_register_handler\fP()
+.PP
+\fBExamples: \fP
+.in +1c
+\fBdata_set.c\fP, and \fBdelayed_instance.c\fP.
+.PP
+Definition at line 95 of file agent_handler.c.
+.PP
+Referenced by netsnmp_config_parse_table_set().
+.PP
+.SS "netsnmp_mib_handler* netsnmp_find_handler_by_name (netsnmp_handler_registration * reginfo, const char * name)"
+.PP
+Returns a handler from a chain based on the name.
+.PP
+Definition at line 550 of file agent_handler.c.
+.PP
+Referenced by netsnmp_find_handler_data_by_name().
+.PP
+.SS "void* netsnmp_find_handler_data_by_name (netsnmp_handler_registration * reginfo, const char * name)"
+.PP
+Returns a handler's void * pointer from a chain based on the name.
+.PP
+This probably shouldn't be used by the general public as the void * data may change as a handler evolves. Handlers should really advertise some function for you to use instead.
+.PP
+Definition at line 566 of file agent_handler.c.
+.PP
+Referenced by netsnmp_find_table_registration_info().
+.PP
+.SS "void netsnmp_free_delegated_cache (netsnmp_delegated_cache * dcache)\fC [inline]\fP"
+.PP
+frees a cache once you're finished using it.
+.PP
+\fBExamples: \fP
+.in +1c
+\fBdelayed_instance.c\fP.
+.PP
+Definition at line 489 of file agent_handler.c.
+.SS "void netsnmp_free_request_data_set (netsnmp_request_info * request)\fC [inline]\fP"
+.PP
+Free the extra data stored in a request.
+.PP
+Definition at line 532 of file agent_handler.c.
+.SS "void netsnmp_free_request_data_sets (netsnmp_request_info * request)\fC [inline]\fP"
+.PP
+Free the extra data stored in a bunch of requests (all data in the chain).
+.PP
+Definition at line 540 of file agent_handler.c.
+.SS "netsnmp_delegated_cache* netsnmp_handler_check_cache (netsnmp_delegated_cache * dcache)\fC [inline]\fP"
+.PP
+check's a given cache and returns it if it is still valid (ie, the agent still considers it to be an outstanding request.
+.PP
+Returns NULL if it's no longer valid.
+.PP
+\fBExamples: \fP
+.in +1c
+\fBdelayed_instance.c\fP.
+.PP
+Definition at line 476 of file agent_handler.c.
+.SS "netsnmp_mib_handler* netsnmp_handler_dup (netsnmp_mib_handler * handler)"
+.PP
+dulpicates a handler.
+.PP
+Definition at line 340 of file agent_handler.c.
+.PP
+Referenced by netsnmp_handler_registration_dup().
+.PP
+.SS "void netsnmp_handler_free (netsnmp_mib_handler * handler)"
+.PP
+free's the resourceses associated with a given handler.
+.PP
+Definition at line 326 of file agent_handler.c.
+.PP
+Referenced by netsnmp_handler_registration_free().
+.PP
+.SS "void netsnmp_handler_mark_requests_as_delegated (netsnmp_request_info * requests, int isdelegated)"
+.PP
+marks a list of requests as delegated (or not if isdelegaded = 0).
+.PP
+Definition at line 501 of file agent_handler.c.
+.SS "netsnmp_handler_registration* netsnmp_handler_registration_dup (netsnmp_handler_registration * reginfo)"
+.PP
+duplicates the handler registration object.
+.PP
+Definition at line 394 of file agent_handler.c.
+.SS "void netsnmp_handler_registration_free (netsnmp_handler_registration * reginfo)"
+.PP
+free the resources associated with a handler registration object.
+.PP
+Definition at line 381 of file agent_handler.c.
+.PP
+Referenced by netsnmp_handler_registration_dup(), netsnmp_register_mib_table_row(), and netsnmp_register_old_api().
+.PP
+.SS "void netsnmp_init_handler_conf (void)"
+.PP
+.PP
+For internal use only.
+.PP
+Definition at line 684 of file agent_handler.c.
+.SS "int netsnmp_inject_handler (netsnmp_handler_registration * reginfo, netsnmp_mib_handler * handler)"
+.PP
+inject a new handler into the calling chain of the handlers definedy by the netsnmp_handler_registration pointer.
+.PP
+The new handler is injected at the top of the list and hence will be the new handler to be called first.
+.PP
+Definition at line 206 of file agent_handler.c.
+.PP
+Referenced by netsnmp_inject_handler_into_subtree(), netsnmp_register_handler(), netsnmp_register_read_only_table_data(), netsnmp_register_serialize(), netsnmp_register_table(), netsnmp_register_table_data(), and netsnmp_register_table_data_set().
+.PP
+.SS "void netsnmp_inject_handler_into_subtree (struct subtree * tp, const char * name, netsnmp_mib_handler * handler)"
+.PP
+.PP
+For internal use only.
+.PP
+Definition at line 599 of file agent_handler.c.
+.PP
+Referenced by parse_injectHandler_conf().
+.PP
+.SS "int netsnmp_register_handler (netsnmp_handler_registration * reginfo)"
+.PP
+register a handler, as defined by the netsnmp_handler_registration pointer.
+.PP
+Definition at line 118 of file agent_handler.c.
+.PP
+Referenced by netsnmp_register_old_api(), netsnmp_register_serialize(), and netsnmp_register_table().
+.PP
+.SS "void netsnmp_register_handler_by_name (const char * name, netsnmp_mib_handler * handler)"
+.PP
+registers a given handler by name so that it can be found easily later.
+.PP
+Definition at line 588 of file agent_handler.c.
+.PP
+Referenced by netsnmp_init_bulk_to_next_helper(), netsnmp_init_debug_helper(), netsnmp_init_read_only_helper(), and netsnmp_init_serialize().
+.PP
+.SS "int netsnmp_register_handler_nocallback (netsnmp_handler_registration * reginfo)"
+.PP
+register a handler, as defined by the netsnmp_handler_registration pointer.
+.PP
+Definition at line 163 of file agent_handler.c.
+.PP
+Referenced by netsnmp_register_mib_table_row().
+.PP
+.SS "void netsnmp_request_add_list_data (netsnmp_request_info * request, netsnmp_data_list * node)\fC [inline]\fP"
+.PP
+add data to a request that can be extracted later by submodules.
+.PP
+\fBExamples: \fP
+.in +1c
+\fBdelayed_instance.c\fP.
+.PP
+Definition at line 511 of file agent_handler.c.
+.PP
+Referenced by netsnmp_old_api_helper(), netsnmp_table_data_helper_handler(), and table_helper_handler().
+.PP
+.SS "void* netsnmp_request_get_list_data (netsnmp_request_info * request, const char * name)\fC [inline]\fP"
+.PP
+extract data from a request that was added previously by a parent module.
+.PP
+\fBExamples: \fP
+.in +1c
+\fBdelayed_instance.c\fP.
+.PP
+Definition at line 523 of file agent_handler.c.
+.PP
+Referenced by netsnmp_extract_array_context(), netsnmp_extract_table_data_set(), netsnmp_extract_table_info(), netsnmp_extract_table_row(), and netsnmp_old_api_helper().
+.PP
+.SS "void parse_injectHandler_conf (const char * token, char * cptr)"
+.PP
+.PP
+For internal use only.
+.PP
+Definition at line 641 of file agent_handler.c.
\ No newline at end of file
