![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdlua.1 b/doc/rrdlua.1
--- /dev/null
+++ b/doc/rrdlua.1
@@ -0,0 +1,350 @@
+.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.08)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "RRDLUA 1"
+.TH RRDLUA 1 "2009-06-09" "1.3.999" "rrdtool"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+RRDLua \- Lua binding for RRDTool
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 10
+\& require \*(Aqrrd\*(Aq
+\& 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(...)
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+.SS "Calling Sequence"
+.IX Subsection "Calling Sequence"
+This module accesses RRDtool functionality directly from within Lua.
+The arguments to the functions listed in the \s-1SYNOPSIS\s0 are explained in
+the regular RRDtool documentation. The command-line call
+.PP
+.Vb 1
+\& rrdtool update mydemo.rrd \-\-template in:out N:12:13
+.Ve
+.PP
+gets turned into
+.PP
+.Vb 1
+\& rrd.update ("mydemo.rrd", "\-\-template", "in:out", "N:12:13")
+.Ve
+.PP
+Note that \-\-template=in:out is also valid.
+.SS "Using with Lua 5.1"
+.IX Subsection "Using with Lua 5.1"
+Start your programs with:
+.PP
+.Vb 5
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& package.cpath = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.1/?.so;\*(Aq ..
+\& package.cpath
+\& require \*(Aqrrd\*(Aq
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+.Ve
+.PP
+\&\s-1OBS:\s0 If you configured with \-\-enable\-lua\-site\-install, you don't need
+to set package.cpath like above.
+.SS "Using with Lua 5.0"
+.IX Subsection "Using with Lua 5.0"
+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:
+.PP
+.Vb 1
+\& require \*(Aqcompat\-5.1\*(Aq
+.Ve
+.PP
+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 \s-1LUA_PATH:\s0
+.PP
+.Vb 8
+\& \-\- 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 = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.0/?.lua\*(Aq
+\& require \*(Aqcompat\-5.1\*(Aq
+\& 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 = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.0/?.so;\*(Aq ..
+\& package.cpath
+\& require \*(Aqrrd\*(Aq
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+.Ve
+.SS "Error Handling"
+.IX Subsection "Error Handling"
+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'.
+.PP
+.Vb 1
+\& 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 = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.0/?.lua\*(Aq
+\&
+\& \-\- here we use a protected call to require compat\-5.1
+\& local r = pcall(require, \*(Aqcompat\-5.1\*(Aq)
+\& if not r then
+\& print(\*(Aq** could not load compat\-5.1.lua\*(Aq)
+\& 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 \*(Aqrequire\*(Aq can find the module:
+\&
+\& package.cpath = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.0/?.so;\*(Aq ..
+\& package.cpath
+\&
+\& local rrd = require \*(Aqrrd\*(Aq
+\& rrd.update ("mydemo.rrd","N:12:13")
+.Ve
+.PP
+If we execute the program above we'll get:
+.PP
+.Vb 1
+\& $ lua t.lua
+\&
+\& lua: t.lua:27: opening \*(Aqmydemo.rrd\*(Aq: No such file or directory
+\& stack traceback:
+\& [C]: in function \`update\*(Aq
+\& t.lua:27: in main chunk
+\& [C]: ?
+.Ve
+.SS "Return Values"
+.IX Subsection "Return Values"
+The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch
+return their findings.
+.PP
+\&\fBrrd.first\fR returns a single \s-1INTEGER\s0 representing the timestamp of the
+first data sample in an \s-1RRA\s0 within an \s-1RRD\s0 file. Example returning the
+first timestamp of the third \s-1RRA\s0 (index 2):
+.PP
+.Vb 1
+\& local firstdate = rrd.first(\*(Aqexample.rrd\*(Aq, \*(Aq\-\-rraindex\*(Aq, 2)
+.Ve
+.PP
+\&\fBrrd.last\fR returns a single \s-1INTEGER\s0 representing the last update time.
+.PP
+.Vb 1
+\& local lastupdate = rrd.last(\*(Aqexample.rrd\*(Aq)
+.Ve
+.PP
+\&\fBrrd.graph\fR returns the x\-size and y\-size of the created image and a table
+with the results of the \s-1PRINT\s0 arguments.
+.PP
+.Vb 3
+\& local xsize, ysize, averages = rrd.graph ...
+\& print(string.format("Image size: %dx%d", xsize, ysize)
+\& print("Averages: ", table.concat(averages, \*(Aq, \*(Aq))
+.Ve
+.PP
+\&\fBrrd.info\fR returns a table where the keys and the values represent property
+names and property values of the \s-1RRD\s0.
+.PP
+.Vb 4
+\& local info = rrd.info("test.rrd")
+\& for key, value in pairs(info) do
+\& print(key, \*(Aq = \*(Aq, value)
+\& end
+.Ve
+.PP
+\&\fBrrd.graphv\fR 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').
+.PP
+\&\fBrrd.updatev\fR also returns a table. The keys of the table are strings
+formed by the concatenation of timestamp, \s-1RRA\s0 index and data source name
+for each consolidated data point (\s-1CDP\s0) written to disk as a result of the
+current update call. The key values are \s-1CDP\s0 values.
+.PP
+\&\fBrrd.fetch\fR 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.
+.PP
+.Vb 1
+\& \-\-require compat\-5.1 if necessary
+\&
+\& package.cpath = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.0/?.so;\*(Aq ..
+\& 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)\en",
+\& os.date("%c", start),start))
+\& io.write("Step size: ", step, " seconds\en")
+\& io.write("DS names: ", table.concat(names, \*(Aq, \*(Aq), "\en")
+\& io.write("Data points: ", #data[1], "\en")
+\& io.write("Data:\en")
+\& 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("\en")
+\& end
+.Ve
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Fidelis Assis <fidelis@pobox.com>