usage

监控软件rrdtools

$Id: USAGE,v 1.1.1.1 2002/02/26 10:21:20 oetiker Exp $

--------------------------------------------------
Usage:

	Loading the rrdtool module is a little bit different with
PHP4/Zend.  If you build the rrdtool module into PHP4 at compile
time (per INSTALL file), then there is nothing you need to do
in your scripts to use the rrd_* functions. 


	However, if you build the rrdtool module as a 'self-contained'
module, you will need to load it for each php script you intend to use.
To do this, you will need a line such as this in your script:

	<? dl("rrdtool.so"); ?>

Note that in PHP4/Zend, you cannot specify the directory where
the module lives.  It restricts the search to a specifc directory
which is defined at compile time.  'make install' will place
this file in the appropriate location.



API:

--------------------------------------------------------------------
string rrd_error()

	rrd_error takes no arguments.

	Use this function to retrieve the error message from
the last rrd_* function that was called and failed.

	If an error was set, a string will be returned.  

	If no error was set, a blank string will be returned.




--------------------------------------------------------------------
int rrd_last(string filename)

	rrd_last takes only one argument, a filename of an RRD
file.  

	If rrd_last is successful in obtaining the last modifiation
time of the file, a date will be returned in the form of the
number of seconds from the unix epoch (Jan 1, 1970, 00:00:00).
You can then use any of php's excellent time functions on this
value.

	If rrd_last is not sucessful, a value of 0 will be returned,
and the internal rrd error will be set.  You can access this error
message via the rrd_error() function (if one was set).
 

--------------------------------------------------------------------
int rrd_update(string filename, string options)

	rrd_update takes 2 arguments, a filename of an RRD file
and a string with options to fill the RRD file with.

	It has been designed to work similary to the rrd_update
call in the RRDs perl library.

Example:  $result = rrd_update("/some.rrd", "N:123:9873:235");
 
	If rrd_update is successful, 1 is returned. 

	If rrd_update is not successful, 0 is returned, and an
error message should be obtainable by called 'rrd_error()'.


--------------------------------------------------------------------
int rrd_create(string filename, array options, int num_of_elements)

	rrd_create takes 3 arguments, a filename of an RRD file to
create, an array of options (exactly like you would pass in the RRDs 
perl library, or on the command line to 'rrdtool'), and the last 
argument is the number of elements in the array of options.  This 
can be obtained by simply calling " count($opt_array) ".  See the 
example scripts for a more clear example.

	If rrd_update is successful, 1 is returned. 

	If rrd_update is not successful, 0 is returned, and an
error message should be obtainable by called 'rrd_error()'.



--------------------------------------------------------------------
mixed rrd_graph(string filename, array options, int num_of_elements) 

	rrd_graph takes 3 arguments, a filename of an RRD file,
an array of options (exactly like you would pass in the RRDs perl
library, or on the command line to 'rrdtool'), and the last argument
is the number of elements in the array of options.  This can be 
obtained by simply calling " count($opt_array) ".  See the example
scripts for a more clear example.


	If rrd_graph is successful, an array is returned.  The
array is an associate array with 3 values:

$array[xsize]  -  The size of the image along the X axis.
$array[ysize]  -  The size of the image along the Y axis.
$array[calcpr] -  This is actually another array, that will contain
                  the results of any PRINT statements.


	If rrd_graph is not successful, a 0 is returned.

IMPORTANT NOTE:  In order for php not to complain about mis-using
the return value, it is important that you check the type of the
return value.  use the " is_array() " function to check if the 
returned value is an array (in which case rrd_graph was successful),
or not an array (meaning rrd_graph was NOT successful).  See the
examples for an illustration of this.


--------------------------------------------------------------------
mixed rrd_fetch(string filename, array options, int num_of_elements) 

	rrd_fetch takes 3 arguments, a filename of an RRD file,
an array of options (exactly like you would pass in the RRDs perl
library, or on the command line to 'rrdtool'), and the last argument
is the number of elements in the array of options.  This can be 
obtained by simply calling " count($opt_array) ".  See the example
scripts for a more clear example.


	If rrd_fetch is successful, an array is returned.  The
array is an associate array with 5 values:

$array[start]   -  This is the start time of the data returned 
                   (unix epoch timestamp format)
$array[end]     -  This is the end time of the data returned
                   (unix epoch timestamp format)
$array[step]    -  This is the step interval of the data returned,
                   in number of seconds.
$array[ds_cnt]  -  This is the number of DS's returned from the
                   RRD file.
$array[ds_namv] -  This is an array with the names of the DS's
                   returned from the RRD file.
$array[data]    -  This is an array with all the values fetch'd
                   from the rrd file by rrd_fetch.

(This is very similar to the way rrd_fetch() in the RRDs
perl library works, as well as the C function rrd_fetch()).

	If rrd_fetch is not successful, a 0 is returned.

IMPORTANT NOTE:  In order for php not to complain about mis-using
the return value, it is important that you check the type of the
return value.  use the " is_array() " function to check if the 
returned value is an array (in which case rrd_fetch was successful),
or not an array (meaning rrd_fetch was NOT successful).  See the
examples for an illustration of this.


--------------------------------------------------------------------