Provided by: erlang-manpages_25.2.3+dfsg-1_all bug

NAME

       snmpa - Interface Functions to the SNMP toolkit agent

DESCRIPTION

       The module snmpa contains interface functions to the SNMP agent.

DATA TYPES

       oid() = [byte()]
       atl_type() = read | write | read_write
       notification_delivery_info() = #snmpa_notification_delivery_info{}

       The oid() type is used to represent an ASN.1 OBJECT IDENTIFIER.

       The record snmpa_notification_delivery_info contains the following fields:

         tag = term():
           A user defined identity representing this notification send operation.

         mod = module():
           A  module  implementing  the  snmpa_notification_delivery_info_receiver behaviour. The
           info functions of this module will be called at various stages of delivery.

         extra = term():
           This is any extra info the user wants to have  supplied  when  the  functions  in  the
           callback module is called.

EXPORTS

       add_agent_caps(SysORID, SysORDescr) -> SysORIndex

              Types:

                 SysORID = oid()
                 SysORDescr = string()
                 SysORIndex = integer()

              This function can be used to add an AGENT-CAPABILITY statement to the sysORTable in
              the agent. The table is defined in the SNMPv2-MIB.

       del_agent_caps(SysORIndex) -> void()

              Types:

                 SysORIndex = integer()

              This function can be used to delete an AGENT-CAPABILITY statement to the sysORTable
              in the agent. This table is defined in the SNMPv2-MIB.

       get_agent_caps() -> [[SysORIndex, SysORID, SysORDescr, SysORUpTime]]

              Types:

                 SysORIndex = integer()
                 SysORId = oid()
                 SysORDescr = string()
                 SysORUpTime = integer()

              Returns  all AGENT-CAPABILITY statements in the sysORTable in the agent. This table
              is defined in the SNMPv2-MIB.

       get(Agent, Vars) -> Values | {error, Reason}
       get(Agent, Vars, Context) -> Values | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 Vars = [oid()]
                 Context = string()
                 Values = [term()]
                 Reason = {atom(), oid()}

              Performs a GET operation on the agent. All loaded MIB objects are visible  in  this
              operation.  The  agent calls the corresponding instrumentation functions just as if
              it was a GET request coming from a manager.

              Note that the request specific parameters  (such  as  current_request_id)  are  not
              accessible for the instrumentation functions if this function is used.

       get_next(Agent, Vars) -> Values | {error, Reason}
       get_next(Agent, Vars, Context) -> Values | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 Vars = [oid()]
                 Context = string()
                 Values = [{oid(), term()}]
                 Reason = {atom(), oid()}

              Performs  a  GET-NEXT operation on the agent. All loaded MIB objects are visible in
              this operation. The agent calls the corresponding instrumentation functions just as
              if it was a GET request coming from a manager.

              Note  that  the request specific parameters (such as snmpa:current_request_id/0 are
              not accessible for the instrumentation functions if this function is used.

       backup(BackupDir) -> ok | {error, Reason}
       backup(Agent, BackupDir) -> ok | {error, Reason}

              Types:

                 BackupDir = string()
                 Agent = pid() | atom()
                 Reason = backup_in_progress | term()

              Backup persistent/permanent data handled by the agent (such as  local-db,  mib-data
              and vacm).

              Data stored by mnesia is not handled.

              BackupDir cannot be identical to DbDir.

              Simultaneous  backup calls are not allowed. That is, two different processes cannot
              simultaneously successfully call this function. One of  them  will  be  first,  and
              succeed. The second will fail with the error reason backup_in_progress.

       info() -> [{Key, Value}]
       info(Agent) -> [{Key, Value}]

              Types:

                 Agent = pid() | atom()

              Returns  a  list (a dictionary) containing information about the agent. Information
              includes loaded MIBs, registered sub-agents,  some  information  about  the  memory
              allocation.

       load_mib(Mib) -> ok | {error, Reason}
       load_mib(Agent, Mib) -> ok | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 MibName = string()
                 Reason = already_loaded | term()

              Load  a single Mib into an agent. The MibName is the name of the Mib, including the
              path to where the compiled mib is found. For example:

                        Dir = code:priv_dir(my_app) ++ "/mibs/",
                        snmpa:load_mib(snmp_master_agent, Dir ++ "MY-MIB").

       load_mibs(Mibs) -> ok | {error, Reason}
       load_mibs(Mibs, Force) -> ok | {error, Reason}
       load_mibs(Agent, Mibs) -> ok | {error, Reason}
       load_mibs(Agent, Mibs, Force) -> ok | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 Mibs = [MibName]
                 Force = boolean()
                 MibName = string()
                 Reason = {'load aborted at', MibName, InternalReason}
                 InternalReason = already_loaded | term()

              Load Mibs into an agent. If the agent cannot load all MIBs (the  default  value  of
              the  Force  argument  is  false),  it  will indicate where loading was aborted. The
              MibName is the name of the Mib, including the path to where  the  compiled  mib  is
              found. For example,

                        Dir = code:priv_dir(my_app) ++ "/mibs/",
                        snmpa:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).

              If Force = true then the agent will continue attempting to load each mib even after
              failing to load a previous mib. Use with care.

       unload_mib(Mib) -> ok | {error, Reason}
       unload_mib(Agent, Mib) -> ok | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 MibName = string()
                 Reason = not_loaded | term()

              Unload a single Mib from an agent.

       unload_mibs(Mibs) -> ok | {error, Reason}
       unload_mibs(Mibs, Force) -> ok | {error, Reason}
       unload_mibs(Agent, Mibs) -> ok | {error, Reason}
       unload_mibs(Agent, Mibs, Force) -> ok | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 Mibs = [MibName]
                 Force = boolean()
                 MibName = string()
                 Reason = {'unload aborted at', MibName, InternalReason}
                 InternalReason = not_loaded | term()

              Unload Mibs from an agent. If it cannot unload all MIBs (the default value  of  the
              Force argument is false), it will indicate where unloading was aborted.

              If  Force  =  true  then the agent will continue attempting to unload each mib even
              after failing to unload a previous mib. Use with care.

       which_mibs() -> Mibs
       which_mibs(Agent) -> Mibs

              Types:

                 Agent = pid() | atom()
                 Mibs = [{MibName, MibFile}]
                 MibName = atom()
                 MibFile = string()

              Retrieve the list of all the mibs loaded into this agent.  Default  is  the  master
              agent.

       whereis_mib(MibName) -> {ok, MibFile} | {error, Reason}
       whereis_mib(Agent, MibName) -> {ok, MibFile} | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 MibName = atom()
                 MibFile = string()
                 Reason = term()

              Get the full path to the (compiled) mib-file.

       current_request_id() -> {value, RequestId} | false
       current_context() -> {value, Context} | false
       current_community() -> {value, Community} | false
       current_address() -> {value, Address} | false

              Types:

                 RequestId = integer()
                 Context = string()
                 Community = string()
                 Address = term()

              Get  the  request-id, context, community and address of the request currently being
              processed by the agent.

              Note that these functions is intended to be called by the instrumentation functions
              and only if they are executed in the context of the agent process (e.g. it does not
              work if called from a spawned process).

       enum_to_int(Name, Enum) -> {value, Int} | false
       enum_to_int(Db, Name, Enum) -> {value, Int} | false

              Types:

                 Db = term()
                 Name = atom()
                 Enum = atom()
                 Int = int()

              Converts the symbolic value Enum to the corresponding  integer  of  the  enumerated
              object or type Name in a MIB. The MIB must be loaded.

              false  is returned if the object or type is not defined in any loaded MIB, or if it
              does not define the symbolic value as enumerated.

              Db is a  reference  to  the  symbolic  store  database  (retrieved  by  a  call  to
              get_symbolic_store_db/0).

       int_to_enum(Name, Int) -> {value, Enum} | false
       int_to_enum(Db, Name, Int) -> {value, Enum} | false

              Types:

                 Db = term()
                 Name = atom()
                 Int = int()
                 Enum = atom()

              Converts  the  integer  Int  to  the corresponding symbolic value of the enumerated
              object or type Name in a MIB. The MIB must be loaded.

              false is returned if the object or type is not defined in any loaded MIB, or if  it
              does not define the symbolic value as enumerated.

              Db  is  a  reference  to  the  symbolic  store  database  (retrieved  by  a call to
              get_symbolic_store_db/0).

       name_to_oid(Name) -> {value, oid()} | false
       name_to_oid(Db, Name) -> {value, oid()} | false

              Types:

                 Db = term()
                 Name = atom()

              Looks up the OBJECT IDENTIFIER of a MIB object, given the symbolic name. Note,  the
              OBJECT IDENTIFIER is given for the object, not for an instance.

              false is returned if the object is not defined in any loaded MIB.

              Db  is  a  reference  to  the  symbolic  store  database  (retrieved  by  a call to
              get_symbolic_store_db/0).

       oid_to_name(OID) -> {value, Name} | false
       oid_to_name(Db, OID) -> {value, Name} | false

              Types:

                 Db = term()
                 OID = oid()
                 Name = atom()

              Looks up the symbolic name of a MIB object, given OBJECT IDENTIFIER.

              false is returned if the object is not defined in any loaded MIB.

              Db is a  reference  to  the  symbolic  store  database  (retrieved  by  a  call  to
              get_symbolic_store_db/0).

       which_aliasnames() -> Result

              Types:

                 Result = [atom()]

              Retrieve all alias-names known to the agent.

       which_tables() -> Result

              Types:

                 Result = [atom()]

              Retrieve all tables known to the agent.

       which_transports() -> Result

              Types:

                 Result = [{TDomain, TAddress} | {TDomain, TAddress, Kind}]
                 TDomain = transportDomainUdpIpv4 | transportDomainUdpIpv6
                 TAddress = {IpAddr, IpPort}
                 IpAddr = inet:ip_address()
                 IpPort = pos_integer()
                 Kind = req_responder | trap_sender

              Retrieve all configured transports.

       which_variables() -> Result

              Types:

                 Result = [atom()]

              Retrieve all variables known to the agent.

       which_notifications() -> Result

              Types:

                 Result = [{Name, MibName, Info}]
                 Name = atom()
                 MibName = atom()
                 Info = term()

              Retrieve all notifications (and traps) known to the agent.

       log_to_txt(LogDir)
       log_to_txt(LogDir, Block | Mibs)
       log_to_txt(LogDir, Mibs, Block | OutFile) -> ok | {ok, Cnt} | {error, Reason}
       log_to_txt(LogDir, Mibs, OutFile, Block | LogName) -> ok | {ok, Cnt} | {error, Reason}
       log_to_txt(LogDir,  Mibs,  OutFile,  LogName, Block | LogFile) -> ok | {ok, Cnt} | {error,
       Reason}
       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block | Start) -> ok  |  {ok,  Cnt}  |
       {error, Reason}
       log_to_txt(LogDir,  Mibs,  OutFile,  LogName,  LogFile,  Block, Start) -> ok | {ok, Cnt} |
       {error, Reason}
       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop)  ->  ok  |  {ok,  Cnt}  |
       {error, Reason}
       log_to_txt(LogDir,  Mibs, OutFile, LogName, LogFile, Block, Start, Stop) -> ok | {ok, Cnt}
       | {error, Reason}

              Types:

                 LogDir = string()
                 Mibs = [MibName]
                 MibName = string()
                 Block = boolean()
                 OutFile = string()
                 LogName = string()
                 LogFile = string()
                 Start = Stop = null | calendar:datetime() | {local_time, calendar:datetime()}  |
                 {universal_time, calendar:datetime()}
                 Cnt = {NumOK, NumERR}
                 NumOK = non_neg_integer()
                 NumERR = pos_integer()
                 Reason = disk_log_open_error() | file_open_error() | term()
                 disk_log_open_error() = {LogName, term()}
                 file_open_error() = {OutFile, term()}

              Converts  an  Audit  Trail  Log  to  a  readable  text  file.  OutFile  defaults to
              "./snmpa_log.txt".  LogName  defaults   to   "snmpa_log".   LogFile   defaults   to
              "snmpa.log".

              The  Block  option  indicates  if the log should be blocked during conversion. This
              could be useful when converting large logs  (when  otherwise  the  log  could  wrap
              during conversion). Defaults to true.

              See snmp:log_to_txt for more info.

       log_to_io(LogDir) -> ok | {ok, Cnt} | {error, Reason}
       log_to_io(LogDir, Block | Mibs) -> ok | {ok, Cnt} | {error, Reason}
       log_to_io(LogDir, Mibs, Block | LogName) -> ok | {ok, Cnt} | {error, Reason}
       log_to_io(LogDir, Mibs, LogName, Block | LogFile) -> ok | {ok, Cnt} | {error, Reason}
       log_to_io(LogDir,  Mibs,  LogName,  LogFile,  Block  |  Start) -> ok | {ok, Cnt} | {error,
       Reason}
       log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start)  ->  ok  |  {ok,  Cnt}  |  {error,
       Reason}
       log_to_io(LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
       log_to_io(LogDir,  Mibs, LogName, LogFile, Block, Start, Stop) -> ok | {ok, Cnt} | {error,
       Reason}

              Types:

                 LogDir = string()
                 Mibs = [MibName]
                 MibName = string()
                 Block = boolean()
                 LogName = string()
                 LogFile = string()
                 Start = Stop = null | calendar:datetime() | {local_time, calendar:datetime()}  |
                 {universal_time, calendar:datetime()}
                 Cnt = {NumOK, NumERR}
                 NumOK = non_neg_integer()
                 NumERR = pos_integer()
                 Reason = disk_log_open_error() | file_open_error() | term()
                 disk_log_open_error() = {LogName, term()}
                 file_open_error() = {OutFile, term()}

              Converts  an  Audit  Trail Log to a readable format and prints it on stdio. LogName
              defaults to "snmpa_log". LogFile defaults to "snmpa.log".

              The Block option indicates if the log should be  blocked  during  conversion.  This
              could  be  useful  when  converting  large  logs (when otherwise the log could wrap
              during conversion). Defaults to true.

              See snmp:log_to_io for more info.

       change_log_size(NewSize) -> ok | {error, Reason}

              Types:

                 NewSize = {MaxBytes, MaxFiles}
                 MaxBytes = integer()
                 MaxFiles = integer()
                 Reason = term()

              Changes the log size of the Audit Trail Log. The application must be configured  to
              use  the  audit  trail  log  function.  Please  refer  to  disk_log(3erl) in Kernel
              Reference Manual for a description of how to change the log size.

              The change is permanent, as long as the log is not deleted.  That  means,  the  log
              size is remembered across reboots.

       set_log_type(NewType) -> {ok, OldType} | {error, Reason}
       set_log_type(Agent, NewType) -> {ok, OldType} | {error, Reason}

              Types:

                 NewType = OldType = atl_type()
                 Agent = pid() | atom()
                 Reason = term()

              Changes the run-time Audit Trail log type.

              Note  that  this  has  no  effect  on  the  application configuration as defined by
              configuration files, so a node restart will revert the config  to  whatever  is  in
              those files.

              This function is primarily useful in testing/debugging scenarios.

       mib_of(Oid) -> {ok, MibName} | {error, Reason}
       mib_of(Agent, Oid) -> {ok, MibName} | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 Oid = oid()
                 MibName = atom()
                 Reason = term()

              Finds  the  mib corresponding to the Oid. If it is a variable, the Oid must be <Oid
              for var>.0 and if it is a table, Oid must be <table>.<entry>.<col>.<any>

       me_of(Oid) -> {ok, Me} | {error, Reason}
       me_of(Agent, Oid) -> {ok, Me} | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 Oid = oid()
                 Me = #me{}
                 Reason = term()

              Finds the mib entry corresponding to the Oid. If it is a variable, the Oid must  be
              <Oid for var>.0 and if it is a table, Oid must be <table>.<entry>.<col>.<any>

       invalidate_mibs_cache() -> void()
       invalidate_mibs_cache(Agent) -> void()

              Types:

                 Agent = pid() | atom()

              Invalidate the mib server cache.

              The entire contents of the cache will be deleted.

       enable_mibs_cache() -> void()
       enable_mibs_cache(Agent) -> void()

              Types:

                 Agent = pid() | atom()

              Enable the mib server cache.

       disable_mibs_cache() -> void()
       disable_mibs_cache(Agent) -> void()

              Types:

                 Agent = pid() | atom()

              Disable the mib server cache.

       which_mibs_cache_size() -> void()
       which_mibs_cache_size(Agent) -> void()

              Types:

                 Agent = pid() | atom()

              Retrieve the size of the mib server cache.

       gc_mibs_cache() -> {ok, NumElementsGCed} | {error, Reason}
       gc_mibs_cache(Agent) -> {ok, NumElementsGCed} | {error, Reason}
       gc_mibs_cache(Age) -> {ok, NumElementsGCed} | {error, Reason}
       gc_mibs_cache(Agent, Age) -> {ok, NumElementsGCed} | {error, Reason}
       gc_mibs_cache(Age, GcLimit) -> {ok, NumElementsGCed} | {error, Reason}
       gc_mibs_cache(Agent, Age, GcLimit) -> {ok, NumElementsGCed} | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 Age = integer() > 0
                 GcLimit = integer() > 0 | infinity
                 NumElementsGCed = integer() >= 0
                 Reason = term()

              Perform mib server cache gc.

              Manually  performs  a mib server cache gc. This can be done regardless of the value
              of the autogc option. The NumElementsGCed value indicates how many  elements  where
              actually removed from the cache.

       enable_mibs_cache_autogc() -> void()
       enable_mibs_cache_autogc(Agent) -> void()

              Types:

                 Agent = pid() | atom()

              Enable automatic gc of the mib server cache.

       disable_mibs_cache_autogc() -> void()
       disable_mibs_cache_autogc(Agent) -> void()

              Types:

                 Agent = pid() | atom()

              Disable automatic gc of the mib server cache.

       update_mibs_cache_age(NewAge) -> ok | {error, Reason}
       update_mibs_cache_age(Agent, NewAge) -> ok | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 NewAge = integer() > 0
                 Reason = term()

              Change the mib server cache age property.

       update_mibs_cache_gclimit(NewGcLimit) -> ok | {error, Reason}
       update_mibs_cache_gclimit(Agent, NewGCLimit) -> ok | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 NewGcLimit = integer() > 0 | infinity
                 Reason = term()

              Change the mib server cache gclimit property.

       register_notification_filter(Id, Mod, Data) -> ok | {error, Reason}
       register_notification_filter(Agent, Id, Mod, Data) -> ok | {error, Reason}
       register_notification_filter(Id, Mod, Data, Where) -> ok | {error, Reason}
       register_notification_filter(Agent, Id, Mod, Data, Where) -> ok | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 Id = filter_id()
                 filter_id() = term()
                 Mod = atom()
                 Data = term()
                 Where = filter_position()
                 Reason = term()
                 filter_position() = first | last | {insert_before, filter_id()} | {insert_after,
                 filter_id()}

              Registers a notification filter.

              Mod is a module implementing the snmpa_notification_filter behaviour.

              Data will be passed on to the filter when calling the functions of the behaviour.

       unregister_notification_filter(Id) -> ok | {error, Reason}
       unregister_notification_filter(Agent, Id) -> ok | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 Id = filter_id()
                 filter_id() = term()

              Unregister a notification filter.

       which_notification_filter() -> Filters
       which_notification_filter(Agent) -> Filters

              Types:

                 Agent = pid() | atom()
                 Filters = [filter_id()]
                 filter_id() = term()

              List all notification filters in an agent.

       set_request_limit(NewLimit) -> {ok, OldLimit} | {error, Reason}
       set_request_limit(Agent, NewLimit) -> {ok, OldLimit} | {error, Reason}

              Types:

                 NewLimit = OldLimit = infinity | integer() >= 0
                 Agent = pid() | atom()
                 Reason = term()

              Changes the request limit.

              Note that this has no  effect  on  the  application  configuration  as  defined  by
              configuration  files,  so  a  node restart will revert the config to whatever is in
              those files.

              This function is primarily useful in load regulation scenarios.

       register_subagent(Agent, SubTreeOid, Subagent) -> ok | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 SubTreeOid = oid()
                 SubAgent = pid()

              Registers a sub-agent under a sub-tree of another agent.

              It is easy to make mistakes when registering sub-agents and this activity should be
              done  carefully.  For  example, a strange behaviour would result from the following
              configuration:

              snmp_agent:register_subagent(MAPid,[1,2,3,4],SA1),
              snmp_agent:register_subagent(SA1,[1,2,3], SA2).

              SA2 will not get requests starting with object identifier [1,2,3]  since  SA1  does
              not.

       unregister_subagent(Agent, SubagentOidOrPid) -> ok | {ok, SubAgentPid} | {error, Reason}

              Types:

                 Agent = pid() | atom()
                 SubTreeOidorPid = oid() | pid()

              Unregister  a  sub-agent. If the second argument is a pid, then that sub-agent will
              be unregistered from all trees in Agent.

       send_notification2(Agent, Notification, SendOpts) -> void()

              Types:

                 Agent = pid() | atom()
                 Notification = atom()
                 SendOpts = [send_option()]
                 send_option() = {receiver,  receiver()}  |  {name,  notify_name()}  |  {context,
                 context_name()} | {varbinds, varbinds()} | {local_engine_id, string()} | {extra,
                 extra_info()}
                 receiver()     =     no_receiver      |      {tag(),      tag_receiver()}      |
                 notification_delivery_info()
                 tag() = term(()
                 tag_receiver() = pid() | registered_name() | {Mod, Func, Args}
                 registered_name() = atom()
                 Mod = atom()
                 Func = atom()
                 Args = list()
                 notify_name() = string()
                 context_name() = string()
                 varbinds() = [varbind()]
                 varbind()  =  {variable(),  value()}  | {{process_oid(), variable()}, value()} |
                 {column(), row_index(), value()} |
                 variable() = aliasname() | oid()
                 aliasname() = atom()
                 process_oid() = keep (default) | truncate
                 value() = term()
                 column() = atom()
                 row_index() = [int()]
                 extra_info() = term()

              Send the notification Notification to the management targets  defined  for  notify-
              name  (name)  in  the  snmpNotifyTable  in SNMP-NOTIFICATION-MIB from the specified
              context.

              If no name is specified (or  if  it  is  ""),  the  notification  is  sent  to  all
              management targets.

              If no context is specified, the default context, "", is used.

              The  send  option  receiver  specifies  where information about delivery of Inform-
              Requests  should  be  sent.  The  agent  sends  Inform-Requests   and   waits   for
              acknowledgments from the management targets. The receiver can have three values:

                * no_receiver - No information is delivered.

                * notification_delivery_info() - The information is delivered via a function call
                  according to this data. See the DATA TYPES section above for details.

                * {tag(), tag_receiver()} - The information is delivered either via  messages  or
                  via a function call according to the value of tag_receiver().

                  Delivery is done differently depending on the value of tag_receiver():

                  * pid()  |  registered_name()  -  The  info  will be delivered in the following
                    messages:

                    * {snmp_targets, tag(), Addresses}

                      This informs the user which target addresses the notification was sent to.

                    * {snmp_notification, tag(), {got_response, Address}}

                      This  informs  the  user  that  this  target   address   acknowledged   the
                      notification.

                    * {snmp_notification, tag(), {no_response, Address}}

                      This  informs  the  user  that  this target address did not acknowledge the
                      notification.

                    The notification is sent as an  Inform-Request  to  each  target  address  in
                    Addresses  and  if  there are no targets for which an Inform-Request is sent,
                    Addresses is the empty list [].

                    The tag_receiver() will first be sent the snmp_targets message, and then  for
                    each address in Addresses list, one of the two snmp_notification messages.

                  * {Mod, Func, Args} - The info will be delivered via the function call:

                    Mod:Func([Msg | Args])

                    where Msg has the same content and purpose as the messages descrived above.

              The  'process  oid'  "tag"  that  can  be provided with the variable name / oids is
              intended to be used for oid  post  processing.  The  value  'keep',  which  is  the
              default,  leaves  the  oid  as  is.  The value 'truncate', will cause the oid to be
              "truncated". That is, any trailing ".0" will be removed.

          Note:
              There is a way to exclude a varbind from the notification. In the  normal  varbinds
              list,  providing  the  special value '$ignore-oid' (instead of a normal value) will
              exclude this varbind from the notification.

              A  define  for  this  has  been  added  to   the   snmp_types.hrl   include   file,
              NOTIFICATION_IGNORE_VB_VALUE.

          Note:
              The  extra  info  is  not  normally  interpreted by the agent, instead it is passed
              through to the net-if process. It is up to the implementor of that process to  make
              use of this data.

              The  version of net-if provided by this application makes no use of this data, with
              one exception: Any tuple containing the atom  snmpa_default_notification_extra_info
              may be used by the agent and is therefore reserved.

              See  the  net-if  incoming  messages for sending a  trap and  notification for more
              info.

       send_notification(Agent, Notification, Receiver)
       send_notification(Agent, Notification, Receiver, Varbinds)
       send_notification(Agent, Notification, Receiver, NotifyName, Varbinds)
       send_notification(Agent, Notification, Receiver,  NotifyName,  ContextName,  Varbinds)  ->
       void()
       send_notification(Agent,   Notification,   Receiver,  NotifyName,  ContextName,  Varbinds,
       LocalEngineID) -> void()

              Types:

                 Agent = pid() | atom()
                 Notification = atom()
                 Receiver = no_receiver | {Tag, Recv} | notification_delivery_info()
                 Tag = term()
                 Recv = receiver()
                 receiver() = pid() | atom() | {Mod, Func, Args}
                 Mod = atom()
                 Func = atom()
                 Args = list()
                 NotifyName = string()
                 ContextName = string()
                 Varbinds = varbinds()
                 varbinds() = [varbind()]
                 varbind() = {Variable, Value} | {Column, RowIndex, Value} | {OID, Value}
                 Variable = atom()
                 Column = atom()
                 OID = oid()
                 Value = term()
                 RowIndex = [int()]
                 LocalEngineID = string()

              Sends  the  notification  Notification  to  the  management  targets  defined   for
              NotifyName  in  the  snmpNotifyTable  in  SNMP-NOTIFICATION-MIB  from the specified
              context.

              If no NotifyName is specified (or if it is ""), the notification  is  sent  to  all
              management targets (Addresses below).

              If no ContextName is specified, the default "" context is used.

              The  parameter  Receiver  specifies  where  information  about  delivery of Inform-
              Requests  should  be  sent.  The  agent  sends  Inform-Requests   and   waits   for
              acknowledgments from the managers. Receiver can have three values:

                * no_receiver - No information is delivered.

                * notification_delivery_info() - The information is delivered via a function call
                  according to this data. See the DATA TYPES section above for details.

                * {Tag, Recv} - The information  is  delivered  either  via  messages  or  via  a
                  function call according to the value of Recv.

              If Receiver has the value {Tag, Recv}, the delivery is done according to Recv:

                * pid() | atom() - The info will be delivered in the following messages:

                  * {snmp_targets, Tag, Addresses}

                    This inform the user which target addresses the notification was sent to.

                  * {snmp_notification, Tag, {got_response, Address}}

                    This informs the user that this target address acknowledged the notification.

                  * {snmp_notification, Tag, {no_response, Address}}

                    This   informs  the  user  that  this  target  address  did  not  acknowledge
                    notification.

                  The notification is sent  as  an  Inform-Request  to  each  target  address  in
                  Addresses  and  if  there  are  no targets for which an Inform-Request is sent,
                  Addresses is the empty list [].

                  The receiver will first be sent the snmp_targets message,  and  then  for  each
                  address in Addresses list, one of the two snmp_notification messages.

                * {Mod, Func, Args} - The info will be delivered via the function call:

                  Mod:Func([Msg | Args])

                  where Msg has the same content and purpose as the messages descrived above.

              Address is a management target address and Addresses is a list of management target
              addresses. They are defined as followes:

                      Addresses  = [address()]
                      Address    = address()
                      address()  = v1_address() | v3_address()
                      v1_address() = {TDomain, TAddress}
                      v3_address() = {{TDomain, TAddress}, V3MsgData}
                      TDomain    = tdoamin()
                      TAddress   = taddress()
                      tdomain()  = The oid of snmpUDPDomain
                                   This is the only supported transport domain.
                      taddress() = [A1, A2, A3, A4, P1, P3]
                                   The 4 first bytes makes up the IP-address and the last 2,
                                   the UDP-port number.
                      V3MsgData  = v3_msg_data()
                      v3_msg_data() = term()

              If Receiver is a notification_delivery_info() record, then  the  information  about
              the  notification  delivery  will  be  delivered  to  the receiver via the callback
              functions  defined  by  the   snmpa_notification_delivery_info_receiver   behaviour
              according to the content of the notification_delivery_info() record.

              The  optional argument Varbinds defines values for the objects in the notification.
              If no value is given for an object, the Agent performs a get-operation to  retrieve
              the value.

              Varbinds is a list of Varbind, where each Varbind is one of:

                * {Variable,  Value},  where  Variable  is the symbolic name of a scalar variable
                  referred to in the notification specification.

                * {Column, RowIndex, Value}, where Column  is  the  symbolic  name  of  a  column
                  variable.  RowIndex  is a list of indices for the specified element. If this is
                  the case, the OBJECT IDENTIFIER  sent  in  the  notification  is  the  RowIndex
                  appended  to  the  OBJECT  IDENTIFIER  for the table column. This is the OBJECT
                  IDENTIFIER which specifies the element.

                * {OID, Value}, where OID is the OBJECT IDENTIFIER for an instance of an  object,
                  scalar variable, or column variable.

              For  example,  to  specify that sysLocation should have the value "upstairs" in the
              notification, we could use one of:

                * {sysLocation, "upstairs"} or

                * {[1,3,6,1,2,1,1,6,0], "upstairs"} or

                * {?sysLocation_instance, "upstairs"} (provided that the generated .hrl  file  is
                  included)

              If  a variable in the notification is a table element, the RowIndex for the element
              must be given in the Varbinds list. In this case, the OBJECT IDENTIFIER sent in the
              notification  is  the  OBJECT  IDENTIFIER that identifies this element. This OBJECT
              IDENTIFIER could be used in a get operation later.

              This function is asynchronous, and does not return any  information.  If  an  error
              occurs,  user_err/2  of  the  error report module is called and the notification is
              discarded.

          Note:
              Note that the use of the LocalEngineID argument is only intended for special cases,
              if  the  agent  is  to "emulate" multiple EngineIDs! By default, the agent uses the
              value of SnmpEngineID (see SNMP-FRAMEWORK-MIB).

              ExtraInfo is not normally used in any way by the agent. It is intended to be passed
              along  to  the  net-if  process,  which  is  a  component that a user can implement
              themself. The users own net-if may then make use of ExtraInfo. The net-if  provided
              with this application does not process ExtraInfo.

              There     is     one     exception.     Any     tuple     containing    the    atom
              snmpa_default_notification_extra_info  will,  in  this   context,   be   considered
              belonging to this application, and may be processed by the agent.

       discovery(TargetName, Notification) -> {ok, ManagerEngineID} | {error, Reason}
       discovery(TargetName, Notification, Varbinds) -> {ok, ManagerEngineID} | {error, Reason}
       discovery(TargetName,  Notification,  DiscoHandler)  ->  {ok,  ManagerEngineID}  | {error,
       Reason}
       discovery(TargetName, Notification, ContextName,  Varbinds)  ->  {ok,  ManagerEngineID}  |
       {error, Reason}
       discovery(TargetName,  Notification,  Varbinds,  DiscoHandler)  -> {ok, ManagerEngineID} |
       {error, Reason}
       discovery(TargetName,  Notification,  ContextName,   Varbinds,   DiscoHandler)   ->   {ok,
       ManagerEngineID} | {error, Reason}
       discovery(TargetName,  Notification,  ContextName,  Varbinds,  DiscoHandler, ExtraInfo) ->
       {ok, ManagerEngineID} | {error, Reason}

              Types:

                 TargetName = string()
                 Notification = atom()
                 ContextName = string() (defaults to "")
                 Varbinds = varbinds()
                 varbinds() = [varbind()]
                 DiscoHandler = snmpa_discovery_handler()
                 ExtraInfo = term()
                 snmpa_discovery_handler()  =  Module  implementing  the  snmpa_discovery_handler
                 behaviour
                 ManagerEngineID = string()
                 varbind() = {Variable, Value} | {Column, RowIndex, Value} | {OID, Value}
                 Variable = atom()
                 Column = atom()
                 OID = oid()
                 Value = term()
                 RowIndex = [int()]
                 Reason = term()

              Initiate  the discovery process with the manager identified by TargetName using the
              notification Notification.

              This function is synchronous, which means that it will return  when  the  discovery
              process has been completed or failed.

              The DiscoHandler module is used during the discovery process. See discovery handler
              for more info.

              The ExtraInfo argument is passed on to the callback functions of the DiscoHandler.

          Note:
              If we are not at security-level noAuthNoPriv, this could be complicated, since  the
              agent will then continue with stage 2, before which the usm-related updates must be
              done.

          Note:
              The default discovery handler will require additional actions by the caller and the
              discovery will not work if the security-level is higher then noAuthNoPriv.

       convert_config(OldConfig) -> AgentConfig

              Types:

                 OldConfig = list()
                 AgentConfig = list()

              This  off-line  utility  function  can  be used to convert the old snmp application
              config (pre snmp-4.0) to the new snmp agent config (as of snmp-4.0).

              For information about the old config (OldConfig) see the OTP R9C documentation.

              For information about the current agent config (AgentConfig), see  the  Configuring
              the application chapter of the SNMP user's guide.

       restart_worker() -> void()
       restart_worker(Agent) -> void()

              Types:

                 Agent = pid() | atom()

              Restart the worker process of a multi-threaded agent.

              This  is a utility function, that can be useful when e.g. debugging instrumentation
              functions.

       restart_set_worker() -> void()
       restart_set_worker(Agent) -> void()

              Types:

                 Agent = pid() | atom()

              Restart the set worker process of a multi-threaded agent.

              This is a utility function, that can be useful when e.g. debugging  instrumentation
              functions.

       print_mib_info() -> void()

              Prints  the  content of all the (snmp) tables and variables for all mibs handled by
              the snmp agent.

       print_mib_tables() -> void()

              Prints the content of all the (snmp) tables for all mibs handled by the snmp agent.

       print_mib_variables() -> void()

              Prints the content of all the (snmp) variables for all mibs  handled  by  the  snmp
              agent.

       verbosity(Ref,Verbosity) -> void()

              Types:

                 Ref = pid() | sub_agents | master_agent | net_if | mib_server | symbolic_store |
                 note_store | local_db
                 Verbosity = verbosity() | {subagents, verbosity()}
                 verbosity() = silence | info | log | debug | trace

              Sets verbosity for the  designated  process.  For  the  lowest  verbosity  silence,
              nothing is printed. The higher the verbosity, the more is printed.

SEE ALSO

       calendar(3erl), erlc(1)