oid(3snmp)

oid: free_oid, make_oid, make_obj_id_from_hex, make_dot_from_obj_id, make_obj_id_from_dot -- operations on object Identifiers

Synopsis

#include <snmp/snmp.h>

void free_oid(OID oid_ptr);

OID make_oid(unsigned long sid_array[], long length);

OID make_obj_id_from_hex(char hex_string);

#include <snmp/snmp.h>
#include <snmp/snmpuser.h>

short make_dot_from_obj_id(OID oid_ptr, char return_buffer[]);

OID make_obj_id_from_dot(char text_string);

Description

free_oid frees all memory associated with the object identifier (type OID), including the memory allocated to the members of ``oid_elements'' that are part of the identifier.

make_oid produces a library object identifier construct from a passed sub-identifier array and length. The sub-identifier array sid_array is an array of unsigned long integers, with each element corresponding to the value of each integer at each position in the dot-notation display of an object identifier. For example, the object identifier ``1.3.6.1.2.1.1'' would have a value 1 in sid_array[0], 3 in sid_array[1], and so on. length is the number of sub-identifier elements present in the array. The construct returned can be freed by passing the pointer to free_oid. Usually, this is unnecessary as the construct is most often passed to another library routine for inclusion in a large ASN.1 construct, and that library routine's freeing counterpart will perform memory recovery.

From a hex text string, make_obj_id_from_hex is used to create a library-format object identifier data structure which is used by calls to make_varbind(3snmp) and make_authentication(3snmp). The format of these strings is a hex value (1 or more hex digits, upper or lower case) followed by a space, with more hex values and spaces to complete the string. For example, to create an object identifier consisting of three sub-identifiers (say, ``1.21.51'') the text string could be ``1 15 3d'' or ``0x1 0x15 0x3D''. The object identifier construct returned by this call can be freed by a call to free_oid. Usually this is unnecessary as the construct is most often passed to another library routine for inclusion in a larger ASN.1 construct, and that library's free counterpart will perform the memory recovery.

make_dot_from_obj_id is called to convert an object identifier library construct into a dot notation character string, usually for use in a human interface. The dot notation output is the usual form (``1.2.3.4.1.2.1.1'') with a MIB name substituted for the most possible sub-identifiers starting from the left (``1.3.6.1.2.1.1.1.0'' becomes sysDescr.0). The MIB names included in the library are found in the mib_oid_table in <snmp-mib.h>. This include file is used in the compilation of oid_lib.c, part of the libsnmp.a library, and need not be included in applications.

make_obj_id_from_dot is used to create a library form object identifier from a character string. The string input is usually in the format ``integer.integer.integer'' (for example, ``1.3.6.1.2.1.1.1.0''), but can be shortened by using the names as they appear in RFC 1066 (for example, ``sysDescr.0''). It returns a pointer to a malloc'ed data structure containing the internal library representation for an object identifier. This identifier can then be used in calls to make_varbind and make_pdu(3snmp) (in the case of traps). This malloc'ed structure will be freed by calling free_pdu(3snmp) after the pointer has been used.

References

octetstring(3snmp), snmp_authentication(3snmp), snmp_pdu(3snmp), varbind(3snmp)