![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdlua.html b/doc/rrdlua.html
--- /dev/null
+++ b/doc/rrdlua.html
@@ -0,0 +1,241 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>rrdlua</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body style="background-color: white">
+
+
+<!-- INDEX BEGIN -->
+<div name="index">
+<p><a name="__index__"></a></p>
+<!--
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <ul>
+
+ <li><a href="#calling_sequence">Calling Sequence</a></li>
+ <li><a href="#using_with_lua_5_1">Using with Lua 5.1</a></li>
+ <li><a href="#using_with_lua_5_0">Using with Lua 5.0</a></li>
+ <li><a href="#error_handling">Error Handling</a></li>
+ <li><a href="#return_values">Return Values</a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+
+-->
+
+
+</div>
+<!-- INDEX END -->
+
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>RRDLua - Lua binding for RRDTool</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ require 'rrd'
+ rrd.create(...)
+ rrd.dump(...)
+ rrd.fetch(...)
+ rrd.first(...)
+ rrd.graph(...)
+ rrd.graphv(...)
+ rrd.info(...)
+ rrd.last(...)
+ rrd.resize(...)
+ rrd.restore(...)
+ rrd.tune(...)
+ rrd.update(...)
+ rrd.updatev(...)</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>
+</p>
+<h2><a name="calling_sequence">Calling Sequence</a></h2>
+<p>This module accesses RRDtool functionality directly from within Lua.
+The arguments to the functions listed in the SYNOPSIS are explained in
+the regular RRDtool documentation. The command-line call</p>
+<pre>
+ rrdtool update mydemo.rrd --template in:out N:12:13</pre>
+<p>gets turned into</p>
+<pre>
+ rrd.update ("mydemo.rrd", "--template", "in:out", "N:12:13")</pre>
+<p>Note that --template=in:out is also valid.</p>
+<p>
+</p>
+<h2><a name="using_with_lua_5_1">Using with Lua 5.1</a></h2>
+<p>Start your programs with:</p>
+<pre>
+ ---------------------------------------------------------------
+ package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.1/?.so;' ..
+ package.cpath
+ require 'rrd'
+ ---------------------------------------------------------------
+
+OBS: If you configured with --enable-lua-site-install, you don't need
+to set package.cpath like above.</pre>
+<p>
+</p>
+<h2><a name="using_with_lua_5_0">Using with Lua 5.0</a></h2>
+<p>The Lua binding for RRDtool needs the Lua module compat-5.1 to work with
+Lua 5.0. Some Linux distros, like Ubuntu gutsy and hardy, have it already
+integrated in Lua 5.0 -dev packages, so you just have to require it:</p>
+<pre>
+ require 'compat-5.1'</pre>
+<p>For other platforms, the compat-5.1 module that comes with this binding
+will be installed for you in the same dir where RRDtool was installed,
+under the subdir .../lib/lua/5.0. In this case, you must tell your Lua
+programs where to find it by changing the Lua var LUA_PATH:</p>
+<pre>
+ -- compat-5.1.lua is only necessary for Lua 5.0 ----------------
+ -- try only compat-5.1 installed with RRDtool package
+ local original_LUA_PATH = LUA_PATH
+ LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'
+ require 'compat-5.1'
+ LUA_PATH = original_LUA_PATH
+ original_LUA_PATH = nil
+ --- end of code to require compat-5.1 ---------------------------
+
+ Now we can require the rrd module in the same way we did for 5.1 above:
+
+ ---------------------------------------------------------------
+ package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
+ package.cpath
+ require 'rrd'
+ ---------------------------------------------------------------</pre>
+<p>
+</p>
+<h2><a name="error_handling">Error Handling</a></h2>
+<p>The Lua RRDTool module functions will abort your program with a stack
+traceback when they can not make sense out of the arguments you fed them.
+However, you can capture and handle the errors yourself, instead of just
+letting the program abort, by calling the module functions through Lua
+protected calls - 'pcall' or 'xpcall'.</p>
+<pre>
+ Ex: program t.lua
+
+ --- compat-5.1.lua is only necessary for Lua 5.0 ----------------
+ -- uncomment below if your distro has not compat-5.1
+ -- original_LUA_PATH = LUA_PATH
+ -- try only compat-5.1.lua installed with RRDtool package
+ -- LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'
+
+ -- here we use a protected call to require compat-5.1
+ local r = pcall(require, 'compat-5.1')
+ if not r then
+ print('** could not load compat-5.1.lua')
+ os.exit(1)
+ end
+
+ -- uncomment below if your distro has not compat-5.1
+ -- LUA_PATH = original_LUA_PATH
+ -- original_LUA_PATH = nil
+ --- end of code to require compat-5.1 ---------------------------
+
+ -- If the Lua RRDTool module was installed together with RRDTool,
+ -- in /usr/local/rrdtool-1.3.2/lib/lua/5.0, package.cpath must be
+ -- set accordingly so that 'require' can find the module:
+
+ package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
+ package.cpath
+
+ local rrd = require 'rrd'
+ rrd.update ("mydemo.rrd","N:12:13")
+
+If we execute the program above we'll get:</pre>
+<pre>
+ $ lua t.lua
+
+ lua: t.lua:27: opening 'mydemo.rrd': No such file or directory
+ stack traceback:
+ [C]: in function `update'
+ t.lua:27: in main chunk
+ [C]: ?</pre>
+<p>
+</p>
+<h2><a name="return_values">Return Values</a></h2>
+<p>The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch
+return their findings.</p>
+<p><strong>rrd.first</strong> returns a single INTEGER representing the timestamp of the
+first data sample in an RRA within an RRD file. Example returning the
+first timestamp of the third RRA (index 2):</p>
+<pre>
+ local firstdate = rrd.first('example.rrd', '--rraindex', 2)</pre>
+<p><strong>rrd.last</strong> returns a single INTEGER representing the last update time.</p>
+<pre>
+ local lastupdate = rrd.last('example.rrd')</pre>
+<p><strong>rrd.graph</strong> returns the x-size and y-size of the created image and a table
+with the results of the PRINT arguments.</p>
+<pre>
+ local xsize, ysize, averages = rrd.graph ...
+ print(string.format("Image size: %dx%d", xsize, ysize)
+ print("Averages: ", table.concat(averages, ', '))</pre>
+<p><strong>rrd.info</strong> returns a table where the keys and the values represent property
+names and property values of the RRD.</p>
+<pre>
+ local info = rrd.info("test.rrd")
+ for key, value in pairs(info) do
+ print(key, ' = ', value)
+ end</pre>
+<p><strong>rrd.graphv</strong> takes the same parameters as rrd.graph but it returns a table
+only. The table returned contains meta information about the graph, like
+its size as well as the position of the graph area on the image. When
+called with and empty filename, the contents of the graph will be returned
+in the table as well (key 'image').</p>
+<p><strong>rrd.updatev</strong> also returns a table. The keys of the table are strings
+formed by the concatenation of timestamp, RRA index and data source name
+for each consolidated data point (CDP) written to disk as a result of the
+current update call. The key values are CDP values.</p>
+<p><strong>rrd.fetch</strong> is the most complex of the pack regarding return values. It
+returns 5 values: the initial timestamp, the step, two parallel arrays
+containing the data source names and their data points respectively, and
+the final timestamp.</p>
+<pre>
+ --require compat-5.1 if necessary
+
+ package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
+ package.cpath
+
+ local rrd = require "rrd"
+ local first, last = rrd.first("test.rrd"), rrd.last("test.rrd")
+ local start, step, names, data =
+ rrd.fetch("test.rrd", "--start", first, "--end", last, "AVERAGE")
+ io.write(string.format("Start: %s (%d)\n",
+ os.date("%c", start),start))
+ io.write("Step size: ", step, " seconds\n")
+ io.write("DS names: ", table.concat(names, ', '), "\n")
+ io.write("Data points: ", #data[1], "\n")
+ io.write("Data:\n")
+ for i,dp in ipairs(data) do
+ io.write(os.date("%t", start), " (", start, "): ")
+ start = start + step
+ for j,v in ipairs(dp) do
+ io.write(v, " ")
+ end
+ io.write("\n")
+ end</pre>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Fidelis Assis <<a href="mailto:fidelis@pobox.com">fidelis@pobox.com</a>></p>
+
+</body>
+
+</html>