Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
snmp_index(3)		   Erlang Module Definition		 snmp_index(3)

NAME
       snmp_index - Abstract Data Type for SNMP	Indexing

DESCRIPTION
       The  module  snmp_index	implements  an Abstract	Data Type (ADT)	for an
       SNMP index structure for	SNMP tables. It	is implemented as an ets table
       of the ordered_set data-type, which means that all operations are O(log
       n). In the table, the key is an ASN.1 OBJECT IDENTIFIER.

       This index is used to separate the implementation of the	SNMP  ordering
       from the	actual implementation of the table. The	SNMP ordering, that is
       implementation of GET NEXT, is implemented in this module.

       For example, suppose there is an	SNMP table, which is best  implemented
       in  Erlang  as one process per SNMP table row. Suppose further that the
       INDEX in	the SNMP table is an OCTET STRING. The index  structure	 would
       be created as follows:

       snmp_index:new(string)

       For  each  new  process	we  create, we insert an item in an snmp_index
       structure:

       new_process(Name, SnmpIndex) ->
	 Pid = start_process(),
	 NewSnmpIndex =
	   snmp_index:insert(SnmpIndex,	Name, Pid),
	 <...>

       With this structure, we can now map an OBJECT IDENTIFIER	in e.g.	a  GET
       NEXT request, to	the correct process:

       get_next_pid(Oid, SnmpIndex) ->
	 {ok, {_, Pid}}	= snmp_index:get_next(SnmpIndex, Oid),
	 Pid.

COMMON DATA TYPES
       The following data types	are used in the	functions below:

	 * index()

	 * oid() = [byte()]

	 * key_types = type_spec() | {type_spec(), type_spec(),	...}

	 * type_spec() = fix_string | string | integer

	 * key() = key_spec() |	{key_spec(), key_spec(), ...}

	 * key_spec() =	string() | integer()

       The index() type	denotes	an snmp	index structure.

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

       The key_types() type is used when creating the index structure, and the
       key() type is used when inserting and deleting items  from  the	struc-
       ture.

       The  key_types()	 type  defines the types of the	SNMP INDEX columns for
       the table. If the table has one single INDEX column, this  type	should
       be  a  single  atom,  but  if  the table	has multiple INDEX columns, it
       should be a tuple with atoms.

       If the INDEX column is of type INTEGER, or derived  from	 INTEGER,  the
       corresponding  type  should be integer. If it is	a variable length type
       (e.g. OBJECT IDENTIFIER,	OCTET STRING), the corresponding  type	should
       be string. Finally, if the type is of variable length, but with a fixed
       size restriction	(e.g. IpAddress), the  corresponding  type  should  be
       fix_string.

       For  example, if	the SNMP table has two INDEX columns, the first	one an
       OCTET STRING with size 2, and the second	one an OBJECT  IDENTIFER,  the
       corresponding key_types parameter would be {fix_string, string}.

       The  key()  type	correlates to the key_types() type. If the key_types()
       is a single atom, the corresponding key() is a single type as well, but
       if the key_types() is a tuple, key must be a tuple of the same size.

       In  the	example	 above,	 valid	keys could be {"hi", "mom"} and	{"no",
       "thanks"}, whereas "hi",	{"hi", 42} and {"hello", "there"} would	be in-
       valid.

   Warning:

       All API functions that update the index return a	NewIndex term. This is
       for backward compatibility with a previous implementation that  used  a
       B+  tree	 written  purely  in Erlang for	the index. The NewIndex	return
       value can now be	ignored. The return value is now the  unchanged	 table
       identifier for the ets table.

       The implementation using	ets tables introduces a	semantic incompatibil-
       ity with	older implementations. In those	older  implementations,	 using
       pure  Erlang  terms, the	index was garbage collected like any other Er-
       lang term and did not have to be	deleted	when discarded.	An  ets	 table
       is  deleted  only when the process creating it explicitly deletes it or
       when the	creating process terminates.

       A new interface delete/1	is now added to	handle the case	when a process
       wants  to  discard an index table (i.e. to build	a completely new). Any
       application using transient snmp	indexes	has to be modified  to	handle
       this.

       As  an  snmp adaption usually keeps the index for the whole of the sys-
       tems lifetime, this is rarely a problem.

EXPORTS
       delete(Index) ->	true

	      Types:

		 Index = NewIndex = index()
		 Key = key()

	      Deletes a	complete index structure (i.e. the ets	table  holding
	      the  index).  The	 index	can no longer be referenced after this
	      call. See	the warning note above.

       delete(Index, Key) -> NewIndex

	      Types:

		 Index = NewIndex = index()
		 Key = key()

	      Deletes a	key and	its value from the index structure. Returns  a
	      new structure.

       get(Index, KeyOid) -> {ok, {KeyOid, Value}} | undefined

	      Types:

		 Index = index()
		 KeyOid	= oid()
		 Value = term()

	      Gets the item with key KeyOid. Could be used from	within an SNMP
	      instrumentation function.

       get_last(Index) -> {ok, {KeyOid,	Value}}	| undefined

	      Types:

		 Index = index()
		 KeyOid	= oid()
		 Value = term()

	      Gets the last item in the	index structure.

       get_next(Index, KeyOid) -> {ok, {NextKeyOid, Value}} | undefined

	      Types:

		 Index = index()
		 KeyOid	= NextKeyOid = oid()
		 Value = term()

	      Gets the next item in the	 SNMP  lexicographic  ordering,	 after
	      KeyOid  in the index structure. KeyOid does not have to refer to
	      an existing item in the index.

       insert(Index, Key, Value) -> NewIndex

	      Types:

		 Index = NewIndex = index()
		 Key = key()
		 Value = term()

	      Inserts a	new key	value tuple into the index  structure.	If  an
	      item  with the same key already exists, the new Value overwrites
	      the old value.

       key_to_oid(Index, Key) -> KeyOid

	      Types:

		 Index = index()
		 Key = key()
		 KeyOid	= NextKeyOid = oid()

	      Converts Key to an OBJECT	IDENTIFIER.

       new(KeyTypes) ->	Index

	      Types:

		 KeyTypes = key_types()
		 Index = index()

	      Creates a	new snmp index structure. The key_types() type is  de-
	      scribed above.

Ericsson AB			  snmp 5.2.12			 snmp_index(3)

NAME | DESCRIPTION | COMMON DATA TYPES | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=snmp_index&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help