From 2454c1fb0e8bef7d7f413e67fbeb25d824f710f0 Mon Sep 17 00:00:00 2001 From: Christian Hammers Date: Sun, 20 Feb 2011 12:46:37 +0000 Subject: [PATCH] Added documentation for the snmp2_* functions. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@308499 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/snmp/functions/snmp2-get.xml | 55 ++++++--- reference/snmp/functions/snmp2-getnext.xml | 58 ++++++--- reference/snmp/functions/snmp2-real-walk.xml | 71 ++++++++--- reference/snmp/functions/snmp2-set.xml | 120 ++++++++++++++++--- reference/snmp/functions/snmp2-walk.xml | 69 ++++++++--- 5 files changed, 297 insertions(+), 76 deletions(-) diff --git a/reference/snmp/functions/snmp2-get.xml b/reference/snmp/functions/snmp2-get.xml index 8d908444b3..6b9988947e 100644 --- a/reference/snmp/functions/snmp2-get.xml +++ b/reference/snmp/functions/snmp2-get.xml @@ -4,9 +4,9 @@ snmp2_get - Description + Fetch an SNMP object - + &reftitle.description; @@ -18,13 +18,12 @@ stringretries5 - + The snmp2_get function is used to read the + value of an SNMP object specified by the + object_id. - - &warn.undocumented.func; - - + &reftitle.parameters; @@ -32,7 +31,7 @@ host - + The SNMP agent. @@ -40,7 +39,7 @@ community - + The read community. @@ -48,7 +47,7 @@ object_id - + The SNMP object. @@ -56,7 +55,7 @@ timeout - + The number of microseconds until the first timeout. @@ -64,20 +63,45 @@ retries - + The number of retries in case timeouts occur. - + &reftitle.returnvalues; - + Returns SNMP object value on success or &false; on error. - + + + &reftitle.examples; + + + Using <function>snmp2_get</function> + + +]]> + + + + + + + &reftitle.seealso; + + + snmp2_set + + + + + diff --git a/reference/snmp/functions/snmp2-getnext.xml b/reference/snmp/functions/snmp2-getnext.xml index beb82a14fb..ab17af593a 100644 --- a/reference/snmp/functions/snmp2-getnext.xml +++ b/reference/snmp/functions/snmp2-getnext.xml @@ -4,9 +4,9 @@ snmp2_getnext - Description + Fetch the SNMP object which follows the given object id - + &reftitle.description; @@ -18,13 +18,12 @@ stringretries5 - + The snmp2_get_next function is used to read the + value of the SNMP object that follows the specified + object_id. - - &warn.undocumented.func; - - + &reftitle.parameters; @@ -32,7 +31,7 @@ host - + The hostname of the SNMP agent (server). @@ -40,7 +39,7 @@ community - + The read community. @@ -48,7 +47,7 @@ object_id - + The SNMP object id which precedes the wanted one. @@ -56,7 +55,7 @@ timeout - + The number of microseconds until the first timeout. @@ -64,20 +63,48 @@ retries - + The number of retries in case timeouts occur. - + + &reftitle.returnvalues; - + Returns SNMP object value on success or &false; on error. + In case of an error, an E_WARNING message is shown. - + + + &reftitle.examples; + + + Using <function>snmp2_get_next</function> + + +]]> + + + + + + + &reftitle.seealso; + + + snmp2_get + snmp2_walk + + + + + diff --git a/reference/snmp/functions/snmp2-real-walk.xml b/reference/snmp/functions/snmp2-real-walk.xml index 22b959046c..f170532dd3 100644 --- a/reference/snmp/functions/snmp2-real-walk.xml +++ b/reference/snmp/functions/snmp2-real-walk.xml @@ -4,9 +4,9 @@ snmp2_real_walk - Description + Return all objects including their respective object ID within the specified one - + &reftitle.description; @@ -18,13 +18,12 @@ stringretries5 - + The snmp2_real_walk function is used to traverse over a number + of SNMP objects starting from object_id + and return not only their values but also their object ids. - - &warn.undocumented.func; - - + &reftitle.parameters; @@ -32,7 +31,7 @@ host - + The hostname of the SNMP agent (server). @@ -40,7 +39,7 @@ community - + The read community. @@ -48,7 +47,7 @@ object_id - + The SNMP object id which precedes the wanted one. @@ -56,7 +55,7 @@ timeout - + The number of microseconds until the first timeout. @@ -64,20 +63,61 @@ retries - + The number of retries in case timeouts occur. - + + &reftitle.returnvalues; - + Returns an associative array of the SNMP object ids and their values on success or &false; on error. + In case of an error, an E_WARNING message is shown. - + + + &reftitle.examples; + + + Using <function>snmp2_real_walk</function> + + +]]> + + + + The above will output something like: + STRING: lo + [IF-MIB::ifName.2] => STRING: eth0 + [IF-MIB::ifName.3] => STRING: eth2 + [IF-MIB::ifName.4] => STRING: sit0 + [IF-MIB::ifName.5] => STRING: sixxs + ) +]]> + + + + + + + &reftitle.seealso; + + + snmp2_walk + + + + + diff --git a/reference/snmp/functions/snmp2-set.xml b/reference/snmp/functions/snmp2-set.xml index 4c1fd39020..8d4554108c 100644 --- a/reference/snmp/functions/snmp2-set.xml +++ b/reference/snmp/functions/snmp2-set.xml @@ -4,9 +4,9 @@ snmp2_set - Description + Set the value of an SNMP object - + &reftitle.description; @@ -20,13 +20,12 @@ stringretries5 - + snmp2_set is used to set the value of an SNMP object + specified by the object_id. - - &warn.undocumented.func; - + - + &reftitle.parameters; @@ -34,7 +33,7 @@ host - + The hostname of the SNMP agent (server). @@ -42,7 +41,7 @@ community - + The write community. @@ -50,7 +49,7 @@ object_id - + The SNMP object id. @@ -58,15 +57,70 @@ type - + The MIB defines the type of each object id. It has to be specified as a single character from the below list. + + types + + + =The type is taken from the MIB + iINTEGER + uINTEGER + sSTRING + xHEX STRING + dDECIMAL STRING + nNULLOBJ + oOBJID + tTIMETICKS + aIPADDRESS + bBITS + + +
+ + If OPAQUE_SPECIAL_TYPES was defined while compiling the SNMP library, the following are also valid: + + + types + + + Uunsigned int64 + Isigned int64 + Ffloat + Ddouble + + +
+ + Most of these will use the obvious corresponding ASN.1 type. 's', 'x', 'd' and 'b' are all different ways of specifying an OCTET STRING value, and + the 'u' unsigned type is also used for handling Gauge32 values. + + + If the MIB-Files are loaded by into the MIB Tree with "snmp_read_mib" or by specifying it in the libsnmp config, '=' may be used as the type parameter + for all object ids as the type can then be automatically read from the MIB. + + + Note that there are two ways to set a variable of the type BITS like e.g. "SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}" + + + + + Using type "b" and a list of bit numbers like: snmpset('FOO-MIB::bar.42', 'b', '0 1 2 3 4'); with the disadvantage that the success is not easily verifyable as an snmpget() for the same OID would return e.g. 0xF8. + + + + + Using type "x" and a hex number but without(!) the usual "0x" prefix: snmpset('FOO-MIB::bar.42', 'x', 'F0'); + + + value - + The new value. @@ -74,7 +128,7 @@ timeout - + The number of microseconds until the first timeout. @@ -82,20 +136,51 @@ retries - + The number of retries in case of timeouts. - + &reftitle.returnvalues; - + &return.success; + + + If the SNMP host rejects the data type, an E_WARNING message like "Warning: Error in packet. Reason: (badValue) The value given has the wrong type or length." is shown. + If an unknown or invalid OID is specified the warning probably reads "Could not add variable". - + + + + + &reftitle.examples; + + + Using <function>snmp2_set</function> + + + ]]> + + + + + + + &reftitle.seealso; + + + snmp2_get + + + + + diff --git a/reference/snmp/functions/snmp2-walk.xml b/reference/snmp/functions/snmp2-walk.xml index c034fc9f5b..49d60e0ccb 100644 --- a/reference/snmp/functions/snmp2-walk.xml +++ b/reference/snmp/functions/snmp2-walk.xml @@ -4,9 +4,9 @@ snmp2_walk - Description + Fetch all the SNMP objects from an agent - + &reftitle.description; @@ -18,13 +18,11 @@ stringretries5 - + snmp2_walk function is used to read all the values from + an SNMP agent specified by the hostname. - - &warn.undocumented.func; - - + &reftitle.parameters; @@ -32,7 +30,7 @@ host - + The SNMP agent (server). @@ -40,7 +38,7 @@ community - + The read community. @@ -48,7 +46,13 @@ object_id - + If &null;, object_id is taken as the root of + the SNMP objects tree and all objects under that tree are returned as + an array. + + + If object_id is specified, all the SNMP objects + below that object_id are returned. @@ -56,7 +60,7 @@ timeout - + The number of microseconds until the first timeout. @@ -64,20 +68,56 @@ retries - + The number of retries in case timeouts occur. - + &reftitle.returnvalues; - + Returns an array of SNMP object values starting from the + object_id as root or &false; on error. + + + &reftitle.examples; + + + <function>snm2_pwalk</function> Example + + +]]> + + + + + Above function call would return all the SNMP objects from the + SNMP agent running on localhost. One can step through the values + with a loop + + + + + &reftitle.seealso; + + + snmp2_real_walk + + + + +