.TH "net-snmp agent related processing" 3 "24 Jan 2005" "net-snmp" \" -*- nroff -*-
.ad l
.nh
.SH NAME
net-snmp agent related processing \- 
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBaddrCache\fP"
.br
.ti -1c
.RI "struct \fB_agent_nsap\fP"
.br
.ti -1c
.RI "struct \fBagent_set_cache_s\fP"
.br
.in -1c
.SS "Defines"

.in +1c
.ti -1c
.RI "#define \fBSNMP_NEED_REQUEST_LIST\fP"
.br
.ti -1c
.RI "#define \fBSNMP_ADDRCACHE_SIZE\fP   10"
.br
.ti -1c
.RI "#define \fBSNMP_ADDRCACHE_MAXAGE\fP   300 /* in seconds */"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef _agent_nsap \fBagent_nsap\fP"
.br
.ti -1c
.RI "typedef agent_set_cache_s \fBagent_set_cache\fP"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum { \fBSNMP_ADDRCACHE_UNUSED\fP =  0, \fBSNMP_ADDRCACHE_USED\fP =  1 }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBnetsnmp_agent_check_packet\fP (\fBnetsnmp_session\fP *, struct netsnmp_transport_s *, void *, int)"
.br
.ti -1c
.RI "int \fBnetsnmp_agent_check_parse\fP (\fBnetsnmp_session\fP *, \fBnetsnmp_pdu\fP *, int)"
.br
.ti -1c
.RI "void \fBdelete_subnetsnmp_tree_cache\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBhandle_pdu\fP (netsnmp_agent_session *asp)"
.br
.RI "\fIThis function calls into netsnmp_set_mode_request_error, sets error_value given a reqinfo->mode value. \fP"
.ti -1c
.RI "int \fBnetsnmp_handle_request\fP (netsnmp_agent_session *asp, int status)"
.br
.ti -1c
.RI "int \fBnetsnmp_wrap_up_request\fP (netsnmp_agent_session *asp, int status)"
.br
.ti -1c
.RI "int \fBcheck_delayed_request\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBhandle_getnext_loop\fP (netsnmp_agent_session *asp)"
.br
.RI "\fIrepeatedly calls getnext handlers looking for an answer till all requests are satisified. \fP"
.ti -1c
.RI "int \fBhandle_set_loop\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBnetsnmp_check_queued_chain_for\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBnetsnmp_add_queued\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBnetsnmp_remove_from_delegated\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBnetsnmp_allocate_globalcacheid\fP (void)"
.br
.ti -1c
.RI "int \fBnetsnmp_get_local_cachid\fP (netsnmp_cachemap *cache_store, int globalid)"
.br
.ti -1c
.RI "netsnmp_cachemap * \fBnetsnmp_get_or_add_local_cachid\fP (netsnmp_cachemap **cache_store, int globalid, int localid)"
.br
.ti -1c
.RI "void \fBnetsnmp_free_cachemap\fP (netsnmp_cachemap *cache_store)"
.br
.ti -1c
.RI "agent_set_cache * \fBsave_set_cache\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBget_set_cache\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "NETSNMP_STATIC_INLINE void \fB_reorder_getbulk\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBgetNextSessID\fP ()"
.br
.ti -1c
.RI "int \fBagent_check_and_process\fP (int block)"
.br
.RI "\fIThis function checks for packets arriving on the SNMP port and processes them(snmp_read) if some are found, using the select(). \fP"
.ti -1c
.RI "void \fBnetsnmp_addrcache_initialise\fP (void)"
.br
.ti -1c
.RI "int \fBnetsnmp_addrcache_add\fP (const char *addr)"
.br
.ti -1c
.RI "void \fBnetsnmp_addrcache_age\fP (void)"
.br
.ti -1c
.RI "int \fBnetsnmp_agent_check_packet\fP (\fBnetsnmp_session\fP *session, netsnmp_transport *transport, void *transport_data, int transport_data_length)"
.br
.ti -1c
.RI "int \fBnetsnmp_register_agent_nsap\fP (netsnmp_transport *t)"
.br
.ti -1c
.RI "void \fBnetsnmp_deregister_agent_nsap\fP (int handle)"
.br
.ti -1c
.RI "int \fBinit_master_agent\fP (void)"
.br
.ti -1c
.RI "void \fBclear_nsap_list\fP (void)"
.br
.ti -1c
.RI "void \fBshutdown_master_agent\fP (void)"
.br
.ti -1c
.RI "netsnmp_agent_session * \fBinit_agent_snmp_session\fP (\fBnetsnmp_session\fP *session, \fBnetsnmp_pdu\fP *pdu)"
.br
.ti -1c
.RI "void \fBfree_agent_snmp_session\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBnetsnmp_check_for_delegated\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBnetsnmp_check_delegated_chain_for\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBnetsnmp_check_for_delegated_and_add\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBnetsnmp_remove_delegated_requests_for_session\fP (\fBnetsnmp_session\fP *sess)"
.br
.ti -1c
.RI "void \fBdump_sess_list\fP (void)"
.br
.ti -1c
.RI "void \fBnetsnmp_remove_and_free_agent_snmp_session\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "void \fBnetsnmp_free_agent_snmp_session_by_session\fP (\fBnetsnmp_session\fP *sess, void(*free_request)(netsnmp_request_list *))"
.br
.ti -1c
.RI "int \fBhandle_snmp_packet\fP (int op, \fBnetsnmp_session\fP *session, int reqid, \fBnetsnmp_pdu\fP *pdu, void *magic)"
.br
.RI "\fIhandles an incoming SNMP packet into the agent \fP"
.ti -1c
.RI "\fBnetsnmp_request_info\fP * \fBnetsnmp_add_varbind_to_cache\fP (netsnmp_agent_session *asp, int vbcount, \fBnetsnmp_variable_list\fP *varbind_ptr, netsnmp_subtree *tp)"
.br
.ti -1c
.RI "int \fBcheck_acm\fP (netsnmp_agent_session *asp, u_char type)"
.br
.ti -1c
.RI "int \fBnetsnmp_create_subtree_cache\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBnetsnmp_reassign_requests\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "void \fBnetsnmp_delete_request_infos\fP (\fBnetsnmp_request_info\fP *reqlist)"
.br
.ti -1c
.RI "void \fBnetsnmp_delete_subtree_cache\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "int \fBnetsnmp_check_requests_error\fP (\fBnetsnmp_request_info\fP *requests)"
.br
.ti -1c
.RI "int \fBnetsnmp_check_requests_status\fP (netsnmp_agent_session *asp, \fBnetsnmp_request_info\fP *requests, int look_for_specific)"
.br
.ti -1c
.RI "int \fBnetsnmp_check_all_requests_status\fP (netsnmp_agent_session *asp, int look_for_specific)"
.br
.ti -1c
.RI "int \fBhandle_var_requests\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "void \fBnetsnmp_check_outstanding_agent_requests\fP (void)"
.br
.ti -1c
.RI "int \fBnetsnmp_check_transaction_id\fP (int transaction_id)"
.br
.RI "\fIDecide if the requested transaction_id is still being processed within the agent. \fP"
.ti -1c
.RI "int \fBcheck_getnext_results\fP (netsnmp_agent_session *asp)"
.br
.RI "\fIreturns 1 if there are valid GETNEXT requests left. \fP"
.ti -1c
.RI "int \fBhandle_set\fP (netsnmp_agent_session *asp)"
.br
.ti -1c
.RI "NETSNMP_STATIC_INLINE int \fB_request_set_error\fP (\fBnetsnmp_request_info\fP *request, int mode, int error_value)"
.br
.RI "\fIset error for a request \fP"
.ti -1c
.RI "int \fBnetsnmp_request_set_error\fP (\fBnetsnmp_request_info\fP *request, int error_value)"
.br
.RI "\fIset error for a request \fP"
.ti -1c
.RI "NETSNMP_INLINE int \fBnetsnmp_request_set_error_all\fP (\fBnetsnmp_request_info\fP *requests, int error)"
.br
.RI "\fIset error for all requests \fP"
.ti -1c
.RI "u_long \fBnetsnmp_marker_uptime\fP (marker_t pm)"
.br
.ti -1c
.RI "u_long \fBnetsnmp_timeval_uptime\fP (struct timeval *tv)"
.br
.ti -1c
.RI "u_long \fBnetsnmp_get_agent_uptime\fP (void)"
.br
.ti -1c
.RI "NETSNMP_INLINE void \fBnetsnmp_agent_add_list_data\fP (\fBnetsnmp_agent_request_info\fP *ari, \fBnetsnmp_data_list\fP *node)"
.br
.ti -1c
.RI "NETSNMP_INLINE int \fBnetsnmp_agent_remove_list_data\fP (\fBnetsnmp_agent_request_info\fP *ari, const char *name)"
.br
.ti -1c
.RI "NETSNMP_INLINE void * \fBnetsnmp_agent_get_list_data\fP (\fBnetsnmp_agent_request_info\fP *ari, const char *name)"
.br
.ti -1c
.RI "NETSNMP_INLINE void \fBnetsnmp_free_agent_data_set\fP (\fBnetsnmp_agent_request_info\fP *ari)"
.br
.ti -1c
.RI "NETSNMP_INLINE void \fBnetsnmp_free_agent_data_sets\fP (\fBnetsnmp_agent_request_info\fP *ari)"
.br
.ti -1c
.RI "NETSNMP_INLINE void \fBnetsnmp_free_agent_request_info\fP (\fBnetsnmp_agent_request_info\fP *ari)"
.br
.ti -1c
.RI "int \fBnetsnmp_set_request_error\fP (\fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *request, int error_value)"
.br
.RI "\fIdeprecated, use netsnmp_request_set_error instead \fP"
.ti -1c
.RI "int \fBnetsnmp_set_mode_request_error\fP (int mode, \fBnetsnmp_request_info\fP *request, int error_value)"
.br
.RI "\fIdeprecated, use netsnmp_request_set_error instead \fP"
.ti -1c
.RI "int \fBnetsnmp_set_all_requests_error\fP (\fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests, int error_value)"
.br
.RI "\fIset error for all request \fP"
.in -1c
.SS "Variables"

.in +1c
.ti -1c
.RI "int \fBlog_addresses\fP = 0"
.br
.ti -1c
.RI "netsnmp_agent_session * \fBagent_delegated_list\fP = NULL"
.br
.ti -1c
.RI "netsnmp_agent_session * \fBnetsnmp_agent_queued_list\fP = NULL"
.br
.ti -1c
.RI "\fBnetsnmp_session\fP * \fBmain_session\fP = NULL"
.br
.ti -1c
.RI "timeval \fBstarttime\fP"
.br
.ti -1c
.RI "int \fBlog_addresses\fP"
.br
.in -1c
.SH "Function Documentation"
.PP 
.SS "NETSNMP_STATIC_INLINE int _request_set_error (\fBnetsnmp_request_info\fP * request, int mode, int error_value)"
.PP
set error for a request Definition at line 3240 of file snmp_agent.c.
.PP
References netsnmp_request_info_s::delegated, netsnmp_request_info_s::processed, netsnmp_request_info_s::requestvb, snmp_log(), netsnmp_request_info_s::status, and variable_list::type.
.PP
Referenced by netsnmp_request_set_error(), netsnmp_request_set_error_all(), netsnmp_set_mode_request_error(), and netsnmp_set_request_error().
.SS "int agent_check_and_process (int block)"
.PP
This function checks for packets arriving on the SNMP port and processes them(snmp_read) if some are found, using the select(). If block is non zero, the function call blocks until a packet arrives
.PP
\fBParameters:\fP
.RS 4
\fIblock\fP used to control blocking in the select() function, 1 = block forever, and 0 = don't block
.RE
.PP
\fBReturns:\fP
.RS 4
Returns a positive integer if packets were processed, and -1 if an error was found. 
.RE
.PP
Definition at line 557 of file snmp_agent.c.
.PP
References snmp_log().
.SS "int check_getnext_results (netsnmp_agent_session * asp)"
.PP
returns 1 if there are valid GETNEXT requests left. Returns 0 if not. Definition at line 2656 of file snmp_agent.c.
.PP
References netsnmp_request_info_s::inclusive, netsnmp_request_info_s::index, variable_list::name, variable_list::name_length, netsnmp_request_info_s::next, netsnmp_request_info_s::range_end, netsnmp_request_info_s::range_end_len, netsnmp_request_info_s::repeat, netsnmp_request_info_s::requestvb, snmp_oid_compare(), snmp_set_var_typed_value(), and variable_list::type.
.PP
Referenced by handle_getnext_loop().
.SS "int handle_getnext_loop (netsnmp_agent_session * asp)"
.PP
repeatedly calls getnext handlers looking for an answer till all requests are satisified. It's expected that one pass has been made before entering this function Definition at line 2761 of file snmp_agent.c.
.PP
References check_getnext_results(), and variable_list::next_variable.
.PP
Referenced by handle_pdu().
.SS "int handle_pdu (netsnmp_agent_session * asp)"
.PP
This function calls into netsnmp_set_mode_request_error, sets error_value given a reqinfo->mode value. It's used to send specific errors back to the agent to process accordingly.
.PP
If error_value is set to SNMP_NOSUCHOBJECT, SNMP_NOSUCHINSTANCE, or SNMP_ENDOFMIBVIEW the following is applicable: Sets the error_value to request->requestvb->type if reqinfo->mode value is set to MODE_GET. If the reqinfo->mode value is set to MODE_GETNEXT or MODE_GETBULK the code calls snmp_log logging an error message.
.PP
Otherwise, the request->status value is checked, if it's < 0 snmp_log is called with an error message and SNMP_ERR_GENERR is assigned to request->status. If the request->status value is >= 0 the error_value is set to request->status.
.PP
\fBParameters:\fP
.RS 4
\fIreqinfo\fP is a pointer to the netsnmp_agent_request_info struct. It contains the reqinfo->mode which is required to set error_value or log error messages.
.br
\fIrequest\fP is a pointer to the netsnmp_request_info struct. The error_value is set to request->requestvb->type
.br
\fIerror_value\fP is the exception value you want to set, below are possible values.
.IP "\(bu" 2
SNMP_NOSUCHOBJECT
.IP "\(bu" 2
SNMP_NOSUCHINSTANCE
.IP "\(bu" 2
SNMP_ENDOFMIBVIEW
.IP "\(bu" 2
SNMP_ERR_NOERROR
.IP "\(bu" 2
SNMP_ERR_TOOBIG
.IP "\(bu" 2
SNMP_ERR_NOSUCHNAME
.IP "\(bu" 2
SNMP_ERR_BADVALUE
.IP "\(bu" 2
SNMP_ERR_READONLY
.IP "\(bu" 2
SNMP_ERR_GENERR
.IP "\(bu" 2
SNMP_ERR_NOACCESS
.IP "\(bu" 2
SNMP_ERR_WRONGTYPE
.IP "\(bu" 2
SNMP_ERR_WRONGLENGTH
.IP "\(bu" 2
SNMP_ERR_WRONGENCODING
.IP "\(bu" 2
SNMP_ERR_WRONGVALUE
.IP "\(bu" 2
SNMP_ERR_NOCREATION
.IP "\(bu" 2
SNMP_ERR_INCONSISTENTVALUE
.IP "\(bu" 2
SNMP_ERR_RESOURCEUNAVAILABLE
.IP "\(bu" 2
SNMP_ERR_COMMITFAILED
.IP "\(bu" 2
SNMP_ERR_UNDOFAILED
.IP "\(bu" 2
SNMP_ERR_AUTHORIZATIONERROR
.IP "\(bu" 2
SNMP_ERR_NOTWRITABLE
.IP "\(bu" 2
SNMP_ERR_INCONSISTENTNAME
.PP
.RE
.PP
\fBReturns:\fP
.RS 4
Returns error_value under all conditions. 
.RE
.PP
Definition at line 3055 of file snmp_agent.c.
.PP
References handle_getnext_loop(), variable_list::next_variable, snmp_set_var_typed_value(), and variable_list::type.
.SS "int handle_snmp_packet (int op, \fBnetsnmp_session\fP * session, int reqid, \fBnetsnmp_pdu\fP * pdu, void * magic)"
.PP
handles an incoming SNMP packet into the agent Definition at line 1703 of file snmp_agent.c.
.PP
References snmp_pdu::command, snmp_session::s_snmp_errno, send_easy_trap(), and snmp_pdu::version.
.SS "\fBnetsnmp_request_info\fP* netsnmp_add_varbind_to_cache (netsnmp_agent_session * asp, int vbcount, \fBnetsnmp_variable_list\fP * varbind_ptr, netsnmp_subtree * tp)"
.PP
Definition at line 1804 of file snmp_agent.c.
.PP
References netsnmp_request_info_s::agent_req_info, netsnmp_request_info_s::delegated, netsnmp_request_info_s::inclusive, netsnmp_request_info_s::index, variable_list::name, variable_list::name_length, netsnmp_acm_check_subtree(), netsnmp_free_request_data_sets(), netsnmp_oid_find_prefix(), netsnmp_request_info_s::next, netsnmp_request_info_s::parent_data, netsnmp_request_info_s::prev, netsnmp_request_info_s::processed, netsnmp_request_info_s::range_end, netsnmp_request_info_s::range_end_len, netsnmp_request_info_s::requestvb, netsnmp_request_info_s::requestvb_start, netsnmp_request_info_s::status, netsnmp_request_info_s::subtree, and variable_list::type.
.SS "int netsnmp_check_transaction_id (int transaction_id)"
.PP
Decide if the requested transaction_id is still being processed within the agent. This is used to validate whether a delayed cache (containing possibly freed pointers) is still usable.
.PP
returns SNMPERR_SUCCESS if it's still valid, or SNMPERR_GENERR if not. Definition at line 2566 of file snmp_agent.c.
.PP
Referenced by netsnmp_handler_check_cache().
.SS "int netsnmp_request_set_error (\fBnetsnmp_request_info\fP * request, int error_value)"
.PP
set error for a request \fBParameters:\fP
.RS 4
\fIrequest\fP request which has error 
.br
\fIerror_value\fP error value for request 
.RE
.PP
Definition at line 3308 of file snmp_agent.c.
.PP
References _request_set_error(), netsnmp_request_info_s::agent_req_info, and netsnmp_agent_request_info_s::mode.
.SS "NETSNMP_INLINE int netsnmp_request_set_error_all (\fBnetsnmp_request_info\fP * requests, int error)"
.PP
set error for all requests \fBParameters:\fP
.RS 4
\fIrequests\fP request list 
.br
\fIerror_value\fP error value for requests 
.RE
.PP
\fBReturns:\fP
.RS 4
SNMPERR_SUCCESS, or an error code 
.RE
.PP
paranoid sanity checks Definition at line 3323 of file snmp_agent.c.
.PP
References _request_set_error(), netsnmp_request_info_s::agent_req_info, netsnmp_agent_request_info_s::mode, netsnmp_request_info_s::next, and snmp_log().
.PP
Referenced by netsnmp_set_all_requests_error().
.SS "int netsnmp_set_all_requests_error (\fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * requests, int error_value)"
.PP
set error for all request \fBDeprecated\fP
.RS 4
use netsnmp_request_set_error_all
.RE
.PP
\fBParameters:\fP
.RS 4
\fIreqinfo\fP agent_request_info pointer for requests 
.br
\fIrequests\fP request list 
.br
\fIerror_value\fP error value for requests 
.RE
.PP
\fBReturns:\fP
.RS 4
error_value 
.RE
.PP
Definition at line 3497 of file snmp_agent.c.
.PP
References netsnmp_request_set_error_all().
.PP
Referenced by netsnmp_cache_helper_handler(), and netsnmp_multiplexer_helper_handler().
.SS "int netsnmp_set_mode_request_error (int mode, \fBnetsnmp_request_info\fP * request, int error_value)"
.PP
deprecated, use netsnmp_request_set_error instead \fBDeprecated\fP
.RS 4
, use netsnmp_request_set_error instead
.RE
.PP
\fBParameters:\fP
.RS 4
\fImode\fP Net-SNMP agent processing mode 
.br
\fIrequest\fP request_info pointer 
.br
\fIerror_value\fP error value for requests 
.RE
.PP
\fBReturns:\fP
.RS 4
error_value 
.RE
.PP
Definition at line 3481 of file snmp_agent.c.
.PP
References _request_set_error().
.SS "int netsnmp_set_request_error (\fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * request, int error_value)"
.PP
deprecated, use netsnmp_request_set_error instead \fBDeprecated\fP
.RS 4
, use netsnmp_request_set_error instead
.RE
.PP
\fBParameters:\fP
.RS 4
\fIreqinfo\fP agent_request_info pointer for request 
.br
\fIrequest\fP request_info pointer 
.br
\fIerror_value\fP error value for requests 
.RE
.PP
\fBReturns:\fP
.RS 4
error_value 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBdelayed_instance.c\fP.
.PP
Definition at line 3462 of file snmp_agent.c.
.PP
References _request_set_error(), and netsnmp_agent_request_info_s::mode.
.PP
Referenced by netsnmp_old_api_helper(), netsnmp_table_data_helper_handler(), netsnmp_table_data_set_helper_handler(), and table_helper_handler().
.SS "int netsnmp_wrap_up_request (netsnmp_agent_session * asp, int status)"
.PP
Definition at line 1471 of file snmp_agent.c.
.PP
References variable_list::next_variable, and variable_list::type.