.\" 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