Provided by: erlang-manpages_20.2.2+dfsg-1ubuntu2_all bug

NAME

       snmpm - Interface functions to the SNMP toolkit manager

DESCRIPTION

       The module snmpm contains interface functions to the SNMP manager.

COMMON DATA TYPES

       The following data types are used in the functions below:

       oid() = [byte()]  -  The oid() type is used to represent an ASN.1 OBJECT IDENTIFIER
       snmp_reply() = {error_status(), error_index(), varbinds()}
       error_status() = noError | atom()
       error_index() = integer()
       varbinds() = [varbind()]
       atl_type() = read | write | read_write
       target_name() = string()  -  Is a unique *non-empty* string
       vars_and_vals() = [var_and_val()]
       var_and_val() = {oid(), value_type(), value()} | {oid(), value()}
       value_type() = o ('OBJECT IDENTIFIER') |
                      i ('INTEGER') |
                      u ('Unsigned32') |
                      g ('Unsigned32') |
                      s ('OCTET SRING') |
                      b ('BITS') |
                      ip ('IpAddress') |
                      op ('Opaque') |
                      c32 ('Counter32') |
                      c64 ('Counter64') |
                      tt ('TimeTicks')
       value() = term()
       community() = string()
       sec_model() = any | v1 | v2c | usm
       sec_name() = string()
       sec_level() = noAuthNoPriv | authNoPriv | authPriv

       See also the  data types in snmpa_conf.

EXPORTS

       monitor() -> Ref

              Types:

                 Ref = reference()

              Monitor the SNMP manager. In case of a crash, the calling (monitoring) process will
              get a 'DOWN' message (see the erlang module for more info).

       demonitor(Ref) -> void()

              Types:

                 Ref = reference()

              Turn off monitoring of the SNMP manager.

       notify_started(Timeout) -> Pid

              Types:

                 Timeout = integer()
                 Pid = pid()

              Request a notification (message) when the SNMP manager has started.

              The Timeout is the time the request is valid. The value  has  to  be  greater  then
              zero.

              The Pid is the process handling the supervision of the SNMP manager start. When the
              manager has started a completion message will be  sent  to  the  client  from  this
              process:  {snmpm_started,  Pid}.  If  the  SNMP  manager was not started in time, a
              timeout message will be sent to the client: {snmpm_start_timeout, Pid}.

              A client application that is dependent on the SNMP manager will use  this  function
              in  order  to be notified of when the manager has started. There are two situations
              when this is useful:

                * During the start of a system, when a client application could  start  prior  to
                  the  SNMP  manager but is dependent upon it, and therefor has to wait for it to
                  start.

                * When the SNMP manager has crashed, the dependent client application has to wait
                  for the SNMP manager to be restarted before it can reconnect.

              The  function  returns the pid() of a handler process, that does the supervision on
              behalf of the client application. Note that the client  application  is  linked  to
              this handler.

              This function is used in conjunction with the monitor function.

       cancel_notify_started(Pid) -> void()

              Types:

                 Pid = pid()

              Cancel a previous request to be notified of SNMP manager start.

       register_user(Id, Module, Data) -> ok | {error, Reason}
       register_user(Id, Module, Data, DefaultAgentConfig) -> ok | {error, Reason}

              Types:

                 Id = term()
                 Module = snmpm_user()
                 Data = term()
                 DefaultAgentConfig = [default_agent_config()]
                 default_agent_config() = {Item, Val}
                 Item = community | timeout | max_message_size | version | sec_model | sec_name |
                 sec_level
                 Val = term()
                 Reason = term()
                 snmpm_user() = Module implementing the snmpm_user behaviour

              Register the manager entity (=user) responsible for specific agent(s).

              Module is the callback module (snmpm_user behaviour) which will be called  whenever
              something  happens  (detected agent, incoming reply or incoming trap/notification).
              Note that this could have already been done as a consequence of  the  node  config.
              (see users.conf).

              The  argument  DefaultAgentConfig is used as default values when this user register
              agents.

              The type of Val depends on Item:

              community = string()
              timeout = integer() | snmp_timer()
              max_message_size = integer()
              version = v1 | v2 | v3
              sec_model = any | v1 | v2c | usm
              sec_name = string()
              sec_level = noAuthNoPriv | authNoPriv | authPriv

       register_user_monitor(Id, Module, Data) -> ok | {error, Reason}
       register_user_monitor(Id, Module, Data, DefaultAgentConfig) -> ok | {error, Reason}

              Types:

                 Id = term()
                 Module = snmpm_user()
                 DefaultAgentConfig = [default_agent_config()]
                 default_agent_config() = {Item, Val}
                 Item = community | timeout | max_message_size | version | sec_model | sec_name |
                 sec_level
                 Val = term()
                 Data = term()
                 Reason = term()
                 snmpm_user() = Module implementing the snmpm_user behaviour

              Register the monitored manager entity (=user) responsible for specific agent(s).

              The process performing the registration will be monitored. Which means that if that
              process  should  die,  all  agents  registered  by  that  user  process   will   be
              unregistered. All outstanding requests will be canceled.

              Module  is the callback module (snmpm_user behaviour) which will be called whenever
              something happens (detected agent, incoming reply or  incoming  trap/notification).
              Note  that  this  could have already been done as a consequence of the node config.
              (see users.conf).

              The argument DefaultAgentConfig is used as default values when this  user  register
              agents.

              The type of Val depends on Item:

              community = string()
              timeout = integer() | snmp_timer()
              max_message_size = integer()
              version = v1 | v2 | v3
              sec_model = any | v1 | v2c | usm
              sec_name = string()
              sec_level = noAuthNoPriv | authNoPriv | authPriv

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

              Types:

                 Id = term()

              Unregister the user.

       which_users() -> Users

              Types:

                 Users = [UserId]
                 UserId = term()

              Get a list of the identities of all registered users.

       register_agent(UserId, TargetName, Config) -> ok | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 Config = [agent_config()]
                 agent_config() = {Item, Val}
                 Item  =  engine_id  |  address | port | community | timeout | max_message_size |
                 version | sec_model | sec_name | sec_level | tdomain
                 Val = term()
                 Reason = term()

              Explicitly  instruct  the  manager  to  handle  this  agent,  with  UserId  as  the
              responsible user.

              Called  to  instruct the manager that this agent shall be handled. This function is
              used when the user knows in advance which agents the  manager  shall  handle.  Note
              that  there  is an alternate way to do the same thing: Add the agent to the manager
              config files (see agents.conf).

              TargetName is a non-empty string, uniquely identifying the agent.

              The type of Val depends on Item:

              [mandatory] engine_id = string()
              [mandatory] tadress = transportAddress()  % Depends on tdomain
              [optional]  port = inet:port_number()
              [optional]  tdomain = transportDomain()
              [optional]  community = string()
              [optional]  timeout = integer() | snmp_timer()
              [optional]  max_message_size = integer()
              [optional]  version = v1 | v2 | v3
              [optional]  sec_model = any | v1 | v2c | usm
              [optional]  sec_name = string()
              [optional]  sec_level = noAuthNoPriv | authNoPriv | authPriv

              Note that if no tdomain is given, the  default  value,  transportDomainUdpIpv4,  is
              used.

              Note  that  if no port is given and if taddress does not contain a port number, the
              default value is used.

       unregister_agent(UserId, TargetName) -> ok | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()

              Unregister the agent.

       agent_info(TargetName, Item) -> {ok, Val} | {error, Reason}

              Types:

                 TargetName = target_name()
                 Item = atom()
                 Reason = term()

              Retrieve agent config.

       update_agent_info(UserId, TargetName, Info) -> ok | {error, Reason}
       update_agent_info(UserId, TargetName, Item, Val) -> ok | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 Info = [{item(), item_value()}]
                 Item = item()
                 item() = atom()
                 Val = item_value()
                 item_value() = term()
                 Reason = term()

              Update agent config. The function update_agent_info/3 should be used  when  several
              values needs to be updated atomically.

              See function register_agent for more info about what kind of items are allowed.

       which_agents() -> Agents
       which_agents(UserId) -> Agents

              Types:

                 UserId = term()
                 Agents = [TargetName]
                 TargetName = target_name()

              Get a list of all registered agents or all agents registered by a specific user.

       register_usm_user(EngineID, UserName, Conf) -> ok | {error, Reason}

              Types:

                 EngineID = string()
                 UserName = string()
                 Conf = [usm_config()]
                 usm_config() = {Item, Val}
                 Item = sec_name | auth | auth_key | priv | priv_key
                 Val = term()
                 Reason = term()

              Explicitly  instruct  the  manager  to  handle this USM user. Note that there is an
              alternate way to do the same thing: Add the usm user to the  manager  config  files
              (see usm.conf).

              The type of Val depends on Item:

              sec_name = string()
              auth = usmNoAuthProtocol | usmHMACMD5AuthProtocol | usmHMACSHAAuthProtocoltimeout
              auth_key = [integer()]   (length 16 if auth = usmHMACMD5AuthProtocol,
                                        length 20 if auth = usmHMACSHAAuthProtocol)
              priv = usmNoPrivProtocol | usmDESPrivProtocol | usmAesCfb128Protocol
              priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb128Protocol).

       unregister_usm_user(EngineID, UserName) -> ok | {error, Reason}

              Types:

                 EngineID = string()
                 UserName = string()
                 Reason = term()

              Unregister this USM user.

       usm_user_info(EngineID, UserName, Item) -> {ok, Val} | {error, Reason}

              Types:

                 EngineID = string()
                 UsmName = string()
                 Item = sec_name | auth | auth_key | priv | priv_key
                 Reason = term()

              Retrieve usm user config.

       update_usm_user_info(EngineID, UserName, Item, Val) -> ok | {error, Reason}

              Types:

                 EngineID = string()
                 UsmName = string()
                 Item = sec_name | auth | auth_key | priv | priv_key
                 Val = term()
                 Reason = term()

              Update usm user config.

       which_usm_users() -> UsmUsers

              Types:

                 UsmUsers = [{EngineID,UserName}]
                 EngineID = string()
                 UsmName = string()

              Get a list of all registered usm users.

       which_usm_users(EngineID) -> UsmUsers

              Types:

                 UsmUsers = [UserName]
                 UserName = string()

              Get a list of all registered usm users with engine-id EngineID.

       sync_get2(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}
       sync_get2(UserId,  TargetName,  Oids,  SendOpts)  ->  {ok, SnmpReply, Remaining} | {error,
       Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 Oids = [oid()]
                 SendOpts = send_opts()
                 send_opts() = [send_opt()]
                 send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()}  |
                 {community,  community()}  |  {sec_model,  sec_model()} | {sec_name, string()} |
                 {sec_level, sec_level()} | {max_message_size, pos_integer()}
                 SnmpReply = snmp_reply()
                 Remaining = integer()
                 Reason  =  {send_failed,  ReqId,  ActualReason}  |  {invalid_sec_info,  SecInfo,
                 SnmpInfo} | term()
                 ReqId = term()
                 ActualReason = term()
                 SecInfo = [sec_info()]
                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
                 sec_tag() = atom()
                 ExpectedValue = ReceivedValue = term()
                 SnmpInfo = term()

              Synchronous get-request.

              Remaining is the remaining time of the given (or default) timeout time.

              When  Reason  is {send_failed, ...} it means that the net_if process failed to send
              the message. This could happen because of any  number  of  reasons,  i.e.  encoding
              error. ActualReason is the actual reason in this case.

              The  send  option  extra specifies an opaque data structure passed on to the net-if
              process. The net-if process included in this application makes, with one exception,
              no  use of this info, so the only use for it in such a option (when using the built
              in  net-if)  would  be  tracing.  The  one  usage  exception  is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

              Some   of   the   send  options  (community,  sec_model,  sec_name,  sec_level  and
              max_message_size) are override options. That is, for this  request,  they  override
              any configuration done when the agent was registered.

              For SnmpInfo, see the user callback function handle_report.

       sync_get(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}
       sync_get(UserId,  TargetName,  ContextName,  Oids) -> {ok, SnmpReply, Remaining} | {error,
       Reason}
       sync_get(UserId, TargetName, Oids,  Timeout)  ->  {ok,  SnmpReply,  Remaining}  |  {error,
       Reason}
       sync_get(UserId,  TargetName,  ContextName, Oids, Timeout) -> {ok, SnmpReply, Remaining} |
       {error, Reason}
       sync_get(UserId, TargetName, ContextName, Oids, Timeout,  ExtraInfo)  ->  {ok,  SnmpReply,
       Remaining} | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 ContextName = string()
                 Oids = [oid()]
                 Timeout = integer()
                 ExtraInfo = term()
                 SnmpReply = snmp_reply()
                 Remaining = integer()
                 Reason  =  {send_failed,  ReqId,  R}  |  {invalid_sec_info, SecInfo, SnmpInfo} |
                 term()
                 R = term()
                 SecInfo = [sec_info()]
                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
                 sec_tag() = atom()
                 ExpectedValue = ReceivedValue = term()
                 SnmpInfo = term()

              Synchronous get-request.

              Remaining is the remaining time of the given or default timeout time.

              When Reason is {send_failed, ...} it means that the net_if process failed  to  send
              the  message.  This  could  happen  because of any number of reasons, i.e. encoding
              error. R is the actual reason in this case.

              ExtraInfo is an opaque data structure passed on to the net-if process.  The  net-if
              process  included  in  this  application  makes, with one exception, no use of this
              info, so the only use for it in such a configuration (when using the built in  net-
              if)   would   be   tracing.   The   one   usage   exception   is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

              For SnmpInfo, see the user callback function handle_report.

       async_get2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
       async_get2(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 Oids = [oid()]
                 SendOpts = send_opts()
                 send_opts() = [send_opt()]
                 send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()}  |
                 {community,  community()}  |  {sec_model,  sec_model()} | {sec_name, string()} |
                 {sec_level, sec_level()} | {max_message_size, pos_integer()}
                 ReqId = term()
                 Reason = term()

              Asynchronous get-request.

              The reply, if it arrives, will be delivered to the  user  through  a  call  to  the
              snmpm_user callback function handle_pdu.

              The  send  option  timeout specifies for how long the request is valid (after which
              the manager is free to delete it).

              The send option extra specifies an opaque data structure passed on  to  the  net-if
              process. The net-if process included in this application makes, with one exception,
              no use of this info, so the only use for it in such a option (when using the  built
              in  net-if)  would  be  tracing.  The  one  usage  exception  is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

              Some  of  the  send  options  (community,  sec_model,   sec_name,   sec_level   and
              max_message_size)  are  override  options. That is, for this request, they override
              any configuration done when the agent was registered.

       async_get(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
       async_get(UserId, TargetName, ContextName, Oids) -> {ok, ReqId} | {error, Reason}
       async_get(UserId, TargetName, Oids, Expire) -> {ok, ReqId} | {error, Reason}
       async_get(UserId, TargetName, ContextName, Oids, Expire) -> {ok, ReqId} | {error, Reason}
       async_get(UserId, TargetName, ContextName, Oids,  Expire,  ExtraInfo)  ->  {ok,  ReqId}  |
       {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 ContextName = string()
                 Oids = [oid()]
                 Expire = integer()
                 ExtraInfo = term()
                 ReqId = term()
                 Reason = term()

              Asynchronous get-request.

              The  reply,  if  it  arrives,  will  be delivered to the user through a call to the
              snmpm_user callback function handle_pdu.

              The Expire time indicates for how long  the  request  is  valid  (after  which  the
              manager is free to delete it).

              ExtraInfo  is  an opaque data structure passed on to the net-if process. The net-if
              process included in this application makes, with one  exception,  no  use  of  this
              info,  so the only use for it in such a configuration (when using the built in net-
              if)  would  be  tracing.   The   one   usage   exception   is:   Any   tuple   with
              snmpm_extra_info_tag as its first element is reserved for internal use.

       sync_get_next2(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}
       sync_get_next2(UserId, TargetName, Oids, SendOpts) -> {ok, SnmpReply, Remaining} | {error,
       Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 Oids = [oid()]
                 SendOpts = send_opts()
                 send_opts() = [send_opt()]
                 send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()}  |
                 {community,  community()}  |  {sec_model,  sec_model()} | {sec_name, string()} |
                 {sec_level, sec_level()} | {max_message_size, pos_integer()}
                 SnmpReply = snmp_reply()
                 Remaining = integer()
                 Reason  =  {send_failed,  ReqId,  ActualReason}  |  {invalid_sec_info,  SecInfo,
                 SnmpInfo} | term()
                 ReqId = term()
                 ActualReason = term()
                 SecInfo = [sec_info()]
                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
                 sec_tag() = atom()
                 ExpectedValue = ReceivedValue = term()
                 SnmpInfo = term()

              Synchronous get-next-request.

              Remaining is the remaining time of the given (or default) timeout time.

              When  Reason  is {send_failed, ...} it means that the net_if process failed to send
              the message. This could happen because of any  number  of  reasons,  i.e.  encoding
              error. ActualReason is the actual reason in this case.

              The  send  option  extra specifies an opaque data structure passed on to the net-if
              process. The net-if process included in this application makes, with one exception,
              no  use of this info, so the only use for it in such a option (when using the built
              in  net-if)  would  be  tracing.  The  one  usage  exception  is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

              Some   of   the   send  options  (community,  sec_model,  sec_name,  sec_level  and
              max_message_size) are override options. That is, for this  request,  they  override
              any configuration done when the agent was registered.

              For SnmpInfo, see the user callback function handle_report.

       sync_get_next(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}
       sync_get_next(UserId,  TargetName,  ContextName,  Oids)  ->  {ok,  SnmpReply, Remaining} |
       {error, Reason}
       sync_get_next(UserId, TargetName, Oids, Timeout) -> {ok, SnmpReply, Remaining}  |  {error,
       Reason}
       sync_get_next(UserId,   TargetName,   ContextName,   Oids,  Timeout)  ->  {ok,  SnmpReply,
       Remaining} | {error, Reason}
       sync_get_next(UserId,  TargetName,  ContextName,  Oids,  Timeout,   ExtraInfo)   ->   {ok,
       SnmpReply, Remaining} | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 ContextName = string()
                 Oids = [oid()]
                 Timeout = integer()
                 ExtraInfo = term()
                 SnmpReply = snmp_reply()
                 Remaining = integer()
                 Reason  =  {send_failed,  ReqId,  R}  |  {invalid_sec_info, SecInfo, SnmpInfo} |
                 term()
                 R = term()

              Synchronous get-next-request.

              Remaining time of the given or default timeout time.

              When Reason is {send_failed, ...} it means that the net_if process failed  to  send
              the  message.  This  could  happen  because of any number of reasons, i.e. encoding
              error. R is the actual reason in this case.

              ExtraInfo is an opaque data structure passed on to the net-if process.  The  net-if
              process  included  in  this  application  makes, with one exception, no use of this
              info, so the only use for it in such a configuration (when using the built in  net-
              if)   would   be   tracing.   The   one   usage   exception   is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

       async_get_next2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
       async_get_next2(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 Oids = [oid()]
                 send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()}  |
                 {community,  community()}  |  {sec_model,  sec_model()} | {sec_name, string()} |
                 {sec_level, sec_level()} | {max_message_size, pos_integer()}
                 ReqId = integer()
                 Reason = term()

              Asynchronous get-next-request.

              The reply will be delivered to the user through a call to the  snmpm_user  callback
              function handle_pdu.

              The  send  option  timeout specifies for how long the request is valid (after which
              the manager is free to delete it).

              The send option extra specifies an opaque data structure passed on  to  the  net-if
              process. The net-if process included in this application makes, with one exception,
              no use of this info, so the only use for it in such a option (when using the  built
              in  net-if)  would  be  tracing.  The  one  usage  exception  is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

              Some  of  the  send  options  (community,  sec_model,   sec_name,   sec_level   and
              max_message_size)  are  override  options. That is, for this request, they override
              any configuration done when the agent was registered.

       async_get_next(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
       async_get_next(UserId, TargetName, ContextName, Oids) -> {ok, ReqId} | {error, Reason}
       async_get_next(UserId, TargetName, Oids, Expire) -> {ok, ReqId} | {error, Reason}
       async_get_next(UserId, TargetName, ContextName, Oids, Expire) ->  {ok,  ReqId}  |  {error,
       Reason}
       async_get_next(UserId,  TargetName, ContextName, Oids, Expire, ExtraInfo) -> {ok, ReqId} |
       {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 ContextName = string()
                 Oids = [oid()]
                 Expire = integer()
                 ExtraInfo = term()
                 ReqId = integer()
                 Reason = term()

              Asynchronous get-next-request.

              The reply will be delivered to the user through a call to the  snmpm_user  callback
              function handle_pdu.

              The  Expire  time  indicates  for  how  long  the request is valid (after which the
              manager is free to delete it).

              ExtraInfo is an opaque data structure passed on to the net-if process.  The  net-if
              process  included  in  this  application  makes, with one exception, no use of this
              info, so the only use for it in such a configuration (when using the built in  net-
              if)   would   be   tracing.   The   one   usage   exception   is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

       sync_set2(UserId, TargetName, VarsAndVals) -> {ok, SnmpReply, Remaining} | {error, Reason}
       sync_set2(UserId, TargetName, VarsAndVals,  SendOpts)  ->  {ok,  SnmpReply,  Remaining}  |
       {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 VarsAndVals = vars_and_vals()
                 SendOpts = send_opts()
                 send_opts() = [send_opt()]
                 send_opt()  = {context, string()} | {timeout, pos_integer()} | {extra, term()} |
                 {community, community()} | {sec_model, sec_model()}  |  {sec_name,  string()}  |
                 {sec_level, sec_level()} | {max_message_size, pos_integer()}
                 SnmpReply = snmp_reply()
                 Remaining = integer()
                 Reason  =  {send_failed,  ReqId,  ActualReason}  |  {invalid_sec_info,  SecInfo,
                 SnmpInfo} | term()
                 ReqId = term()
                 ActualReason = term()
                 SecInfo = [sec_info()]
                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
                 sec_tag() = atom()
                 ExpectedValue = ReceivedValue = term()
                 SnmpInfo = term()

              Synchronous set-request.

              Remaining is the remaining time of the given (or default) timeout time.

              When Reason is {send_failed, ...} it means that the net_if process failed  to  send
              the  message.  This  could  happen  because of any number of reasons, i.e. encoding
              error. ActualReason is the actual reason in this case.

              When var_and_val() is {oid(), value()}, the manager makes an educated  guess  based
              on the loaded mibs.

              The  send  option  extra specifies an opaque data structure passed on to the net-if
              process. The net-if process included in this application makes, with one exception,
              no  use of this info, so the only use for it in such a option (when using the built
              in  net-if)  would  be  tracing.  The  one  usage  exception  is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

              Some   of   the   send  options  (community,  sec_model,  sec_name,  sec_level  and
              max_message_size) are override options. That is, for this  request,  they  override
              any configuration done when the agent was registered.

              For SnmpInfo, see the user callback function handle_report.

       sync_set(UserId, TargetName, VarsAndVals) -> {ok, SnmpReply, Remaining} | {error, Reason}
       sync_set(UserId,  TargetName,  ContextName,  VarsAndVals)  -> {ok, SnmpReply, Remaining} |
       {error, Reason}
       sync_set(UserId, TargetName, VarsAndVals, Timeout) -> {ok, SnmpReply, Remaining} | {error,
       Reason}
       sync_set(UserId,   TargetName,  ContextName,  VarsAndVals,  Timeout)  ->  {ok,  SnmpReply,
       Remaining} | {error, Reason}
       sync_set(UserId,  TargetName,  ContextName,  VarsAndVals,  Timeout,  ExtraInfo)  ->   {ok,
       SnmpReply, Remaining} | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 ContextName = string()
                 VarsAndVals = vars_and_vals()
                 Timeout = integer()
                 ExtraInfo = term()
                 SnmpReply = snmp_reply()
                 Remaining = integer()
                 Reason  =  {send_failed,  ReqId,  ActualReason}  |  {invalid_sec_info,  SecInfo,
                 SnmpInfo} | term()
                 ActualReason = term()

              Synchronous set-request.

              Remaining time of the given or default timeout time.

              When Reason is {send_failed, ...} it means that the net_if process failed  to  send
              the  message.  This  could  happen  because of any number of reasons, i.e. encoding
              error. R is the actual reason in this case.

              When var_and_val() is {oid(), value()}, the manager makes an educated  guess  based
              on the loaded mibs.

              ExtraInfo  is  an opaque data structure passed on to the net-if process. The net-if
              process included in this application makes, with one  exception,  no  use  of  this
              info,  so the only use for it in such a configuration (when using the built in net-
              if)  would  be  tracing.   The   one   usage   exception   is:   Any   tuple   with
              snmpm_extra_info_tag as its first element is reserved for internal use.

       async_set2(UserId, TargetName, VarsAndVals) -> {ok, ReqId} | {error, Reason}
       async_set2(UserId, TargetName, VarsAndVals, SendOpts) -> {ok, ReqId} | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 VarsAndVals = vars_and_vals()
                 SendOpts = send_opts()
                 send_opts() = [send_opt()]
                 send_opt()  = {context, string()} | {timeout, pos_integer()} | {extra, term()} |
                 {community, community()} | {sec_model, sec_model()}  |  {sec_name,  string()}  |
                 {sec_level, sec_level()} | {max_message_size, pos_integer()}
                 ReqId = term()
                 Reason = term()

              Asynchronous set-request.

              The  reply  will be delivered to the user through a call to the snmpm_user callback
              function handle_pdu.

              The send option timeout specifies for how long the request is  valid  (after  which
              the manager is free to delete it).

              When  var_and_val()  is {oid(), value()}, the manager makes an educated guess based
              on the loaded mibs.

              The send option extra specifies an opaque data structure passed on  to  the  net-if
              process. The net-if process included in this application makes, with one exception,
              no use of this info, so the only use for it in such a option (when using the  built
              in  net-if)  would  be  tracing.  The  one  usage  exception  is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

              Some  of  the  send  options  (community,  sec_model,   sec_name,   sec_level   and
              max_message_size)  are  override  options. That is, for this request, they override
              any configuration done when the agent was registered.

       async_set(UserId, TargetName, VarsAndVals) -> {ok, ReqId} | {error, Reason}
       async_set(UserId, TargetName, ContextName, VarsAndVals) -> {ok, ReqId} | {error, Reason}
       async_set(UserId, TargetName, VarsAndVals, Expire) -> {ok, ReqId} | {error, Reason}
       async_set(UserId, TargetName, ContextName, VarsAndVals, Expire) -> {ok, ReqId}  |  {error,
       Reason}
       async_set(UserId,  TargetName, ContextName, VarsAndVals, Expire, ExtraInfo) -> {ok, ReqId}
       | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 VarsAndVals = vars_and_vals()
                 Expire = integer()
                 ExtraInfo = term()
                 ReqId = term()
                 Reason = term()

              Asynchronous set-request.

              The reply will be delivered to the user through a call to the  snmpm_user  callback
              function handle_pdu.

              The  Expire  time  indicates  for  how  long  the request is valid (after which the
              manager is free to delete it).

              When var_and_val() is {oid(), value()}, the manager makes an educated  guess  based
              on the loaded mibs.

              ExtraInfo  is  an opaque data structure passed on to the net-if process. The net-if
              process included in this application makes, with one  exception,  no  use  of  this
              info,  so the only use for it in such a configuration (when using the built in net-
              if)  would  be  tracing.   The   one   usage   exception   is:   Any   tuple   with
              snmpm_extra_info_tag as its first element is reserved for internal use.

       sync_get_bulk2(UserId,  TragetName,  NonRep, MaxRep, Oids) -> {ok, SnmpReply, Remaining} |
       {error, Reason}
       sync_get_bulk2(UserId, TragetName, NonRep, MaxRep,  Oids,  SendOpts)  ->  {ok,  SnmpReply,
       Remaining} | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 NonRep = integer()
                 MaxRep = integer()
                 Oids = [oid()]
                 SendOpts = send_opts()
                 send_opts() = [send_opt()]
                 send_opt()  = {context, string()} | {timeout, pos_integer()} | {extra, term()} |
                 {community, community()} | {sec_model, sec_model()}  |  {sec_name,  string()}  |
                 {sec_level, sec_level()} | {max_message_size, pos_integer()}
                 SnmpReply = snmp_reply()
                 Remaining = integer()
                 Reason  =  {send_failed,  ReqId,  ActualReason}  |  {invalid_sec_info,  SecInfo,
                 SnmpInfo} | term()
                 ReqId = term()
                 ActualReason = term()
                 SecInfo = [sec_info()]
                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
                 sec_tag() = atom()
                 ExpectedValue = ReceivedValue = term()
                 SnmpInfo = term()

              Synchronous get-bulk-request (See RFC1905).

              Remaining is the remaining time of the given (or default) timeout time.

              When Reason is {send_failed, ...} it means that the net_if process failed  to  send
              the  message.  This  could  happen  because of any number of reasons, i.e. encoding
              error. ActualReason is the actual reason in this case.

              The send option extra specifies an opaque data structure passed on  to  the  net-if
              process. The net-if process included in this application makes, with one exception,
              no use of this info, so the only use for it in such a option (when using the  built
              in  net-if)  would  be  tracing.  The  one  usage  exception  is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

              Some  of  the  send  options  (community,  sec_model,   sec_name,   sec_level   and
              max_message_size)  are  override  options. That is, for this request, they override
              any configuration done when the agent was registered.

              For SnmpInfo, see the user callback function handle_report.

       sync_get_bulk(UserId, TragetName, NonRep, MaxRep, Oids) -> {ok,  SnmpReply,  Remaining}  |
       {error, Reason}
       sync_get_bulk(UserId,  TragetName,  NonRep,  MaxRep, ContextName, Oids) -> {ok, SnmpReply,
       Remaining} | {error, Reason}
       sync_get_bulk(UserId, TragetName,  NonRep,  MaxRep,  Oids,  Timeout)  ->  {ok,  SnmpReply,
       Remaining} | {error, Reason}
       sync_get_bulk(UserId,  TragetName,  NonRep,  MaxRep,  ContextName,  Oids, Timeout) -> {ok,
       SnmpReply, Remaining} | {error, Reason}
       sync_get_bulk(UserId, TragetName, NonRep, MaxRep, ContextName, Oids,  Timeout,  ExtraInfo)
       -> {ok, SnmpReply, Remaining} | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 NonRep = integer()
                 MaxRep = integer()
                 ContextName = string()
                 Oids = [oid()]
                 Timeout = integer()
                 ExtraInfo = term()
                 SnmpReply = snmp_reply()
                 Remaining = integer()
                 Reason  =  {send_failed,  ReqId,  R}  |  {invalid_sec_info, SecInfo, SnmpInfo} |
                 term()

              Synchronous get-bulk-request (See RFC1905).

              Remaining time of the given or default timeout time.

              When Reason is {send_failed, ...} it means that the net_if process failed  to  send
              the  message.  This  could  happen  because of any number of reasons, i.e. encoding
              error. R is the actual reason in this case.

              ExtraInfo is an opaque data structure passed on to the net-if process.  The  net-if
              process  included  in  this  application  makes, with one exception, no use of this
              info, so the only use for it in such a configuration (when using the built in  net-
              if)   would   be   tracing.   The   one   usage   exception   is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

       async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids) -> {ok, ReqId} | {error, Reason}
       async_get_bulk2(UserId, TargetName, NonRep, MaxRep,  Oids,  SendOpts)  ->  {ok,  ReqId}  |
       {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 NonRep = integer()
                 MaxRep = integer()
                 Oids = [oid()]
                 SendOpts = send_opts()
                 send_opts() = [send_opt()]
                 send_opt()  = {context, string()} | {timeout, pos_integer()} | {extra, term()} |
                 {community, community()} | {sec_model, sec_model()}  |  {sec_name,  string()}  |
                 {sec_level, sec_level()} | {max_message_size, pos_integer()}
                 ReqId = integer()
                 Reason = term()

              Asynchronous get-bulk-request (See RFC1905).

              The  reply  will be delivered to the user through a call to the snmpm_user callback
              function handle_pdu.

              The send option timeout specifies for how long the request is  valid  (after  which
              the manager is free to delete it).

              The  send  option  extra specifies an opaque data structure passed on to the net-if
              process. The net-if process included in this application makes no use of this info,
              so  the  only  use  for it in such a configuration (when using the built in net-if)
              would be tracing.

              Some  of  the  send  options  (community,  sec_model,   sec_name,   sec_level   and
              max_message_size)  are  override  options. That is, for this request, they override
              any configuration done when the agent was registered.

       async_get_bulk(UserId, TargetName, NonRep, MaxRep, Oids) -> {ok, ReqId} | {error, Reason}
       async_get_bulk(UserId, TargetName, NonRep, MaxRep, ContextName, Oids)  ->  {ok,  ReqId}  |
       {error, Reason}
       async_get_bulk(UserId,  TargetName, NonRep, MaxRep, Oids, Expire) -> {ok, ReqId} | {error,
       Reason}
       async_get_bulk(UserId, TargetName, NonRep, MaxRep,  ContextName,  Oids,  Expire)  ->  {ok,
       ReqId} | {error, Reason}
       async_get_bulk(UserId,  TargetName,  NonRep, MaxRep, ContextName, Oids, Expire, ExtraInfo)
       -> {ok, ReqId} | {error, Reason}

              Types:

                 UserId = term()
                 TargetName = target_name()
                 NonRep = integer()
                 MaxRep = integer()
                 ContextName = string()
                 Oids = [oid()]
                 Expire = integer()
                 ExtraInfo = term()
                 ReqId = integer()
                 Reason = term()

              Asynchronous get-bulk-request (See RFC1905).

              The reply will be delivered to the user through a call to the  snmpm_user  callback
              function handle_pdu.

              The  Expire  time  indicates  for  how  long  the request is valid (after which the
              manager is free to delete it).

              ExtraInfo is an opaque data structure passed on to the net-if process.  The  net-if
              process  included  in  this  application  makes, with one exception, no use of this
              info, so the only use for it in such a configuration (when using the built in  net-
              if)   would   be   tracing.   The   one   usage   exception   is:  Any  tuple  with
              snmpm_extra_info_tag as its first element is reserved for internal use.

       cancel_async_request(UserId, ReqId) -> ok | {error, Reason}

              Types:

                 UserId = term()
                 ReqId = term()
                 Reason = term()

              Cancel a previous asynchronous request.

       log_to_txt(LogDir)
       log_to_txt(LogDir, Block | Mibs)
       log_to_txt(LogDir, Mibs, Block | OutFile) -> ok | {error, Reason}
       log_to_txt(LogDir, Mibs, OutFile, Block | LogName) -> ok | {error, Reason}
       log_to_txt(LogDir, Mibs, OutFile, LogName, Block | LogFile) -> ok | {error, Reason}
       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block | Start) -> ok | {error, Reason}
       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -> ok | {error, Reason}
       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok | {error, Reason}
       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop) ->  ok  |  {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()}
                 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
              "./snmpm_log.txt".   LogName   defaults   to   "snmpm_log".   LogFile  defaults  to
              "snmpm.log".

              The Block argument indicates if the log should be blocked during  conversion.  This
              could  be  usefull  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 | {error, Reason}
       log_to_io(LogDir, Block | Mibs) -> ok | {error, Reason}
       log_to_io(LogDir, Mibs) -> ok | {error, Reason}
       log_to_io(LogDir, Mibs, Block | LogName) -> ok | {error, Reason}
       log_to_io(LogDir, Mibs, LogName, Block | LogFile) -> ok | {error, Reason}
       log_to_io(LogDir, Mibs, LogName, LogFile, Block | Start) -> ok | {error, Reason}
       log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {error, Reason}
       log_to_io(LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {error, Reason}
       log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok | {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()}
                 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 "snmpm_log". LogFile defaults to "snmpm.log".

              The Block argument indicates if the log should be blocked during  conversion.  This
              could  be  usefull  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}

              Types:

                 NewType = OldType = atl_type()
                 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.

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

              Types:

                 Mib = MibName
                 MibName = string()
                 Reason = term()

              Load a Mib into the manager. 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/",
                        snmpm:load_mib(Dir ++ "MY-MIB").

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

              Types:

                 Mib = MibName
                 MibName = string()
                 Reason = term()

              Unload a Mib from the manager. 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/",
                        snmpm:unload_mib(Dir ++ "MY-MIB").

       which_mibs() -> Mibs

              Types:

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

              Get a list of all the mib's loaded into the manager.

       name_to_oid(Name) -> {ok, Oids} | {error, Reason}

              Types:

                 Name = atom()
                 Oids = [oid()]

              Transform a alias-name to its oid.

              Note  that  an  alias-name  is  only unique within the mib, so when loading several
              mib's into a manager, there might be several instances of the same aliasname.

       oid_to_name(Oid) -> {ok, Name} | {error, Reason}

              Types:

                 Oid = oid()
                 Name = atom()
                 Reason = term()

              Transform a oid to its aliasname.

       oid_to_type(Oid) -> {ok, Type} | {error, Reason}

              Types:

                 Oid = oid()
                 Type = atom()
                 Reason = term()

              Retreive the type (asn1 bertype) of an oid.

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

              Types:

                 BackupDir = string()

              Backup persistent data handled by the manager.

              BackupDir cannot be identical to DbDir.

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

              Types:

                 Key = atom()
                 Value = term()

              Returns a list (a dictionary) containing information about the manager. Information
              includes  statistics  counters,  miscellaneous info about each process (e.g. memory
              allocation), and so on.

       verbosity(Ref, Verbosity) -> void()

              Types:

                 Ref = server | config | net_if | note_store | all
                 Verbosity = 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.

       format_reason(Reason) -> string()
       format_reason(Prefix, Reason) -> string()

              Types:

                 Reason = term()
                 Prefix = integer() | string()

              This  utility  function  is used to create a formatted (pretty printable) string of
              the error reason received from either:

                * The Reason returned value if any of  the  sync/async  get/get-next/set/get-bulk
                  functions returns {error, Reason}

                * The Reason parameter in the handle_error user callback function.

              Prefix  should  either be an indention string (e.g. a list of spaces) or a positive
              integer (which will be used to create the indention string of that length).