.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "RRDLUA 1"
.TH RRDLUA 1 2026-08-08 1.11.0 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 برای 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"
این پودمان امکان دسترسی مستقیم به قابلیت‌های RRDtool را از درون Lua فراهم می‌کند.
آرگومان‌های توابع فهرست‌شده در بخش خلاصه دستور (SYNOPSIS) در مستندات اصلی
RRDtool توضیح داده شده‌اند. فراخوانی خط فرمانی
.PP
.Vb 1
\&    rrdtool update mydemo.rrd \-\-template in:out N:12:13
.Ve
.PP
به شکل زیر تبدیل می‌شود:
.PP
.Vb 1
\&    rrd.update ("mydemo.rrd", "\-\-template", "in:out", "N:12:13")
.Ve
.PP
توجه داشته باشید که استفاده از \-\-template=in:out نیز معتبر است.
.SS "استفاده با Lua 5.1 (Using with Lua 5.1)"
.IX Subsection "Using with Lua 5.1"
برنامه‌های خود را به این صورت آغاز کنید:
.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
نکته: اگر با گزینهٔ \-\-enable\-lua\-site\-install پیکربندی کرده‌اید، نیازی به
تنظیم package.cpath مانند بالا نخواهید داشت.
.SS "استفاده با Lua 5.0 (Using with Lua 5.0)"
.IX Subsection "Using with Lua 5.0"
رابط Lua برای RRDtool جهت کار با Lua 5.0 به پودمان compat\-5.1 در Lua نیاز دارد.
برخی از توزیع‌های لینوکس مانند Ubuntu gutsy و hardy، از پیش آن را در بسته‌های
\-dev مربوط به Lua 5.0 ادغام کرده‌اند، بنابراین تنها کافی است آن را با require فراخوانی کنید:
.PP
.Vb 1
\&    require \*(Aqcompat\-5.1\*(Aq
.Ve
.PP
برای سایر پلتفرم‌ها، پودمان compat\-5.1 که به همراه این رابط ارائه می‌شود در همان دایرکتوری
محل نصب RRDtool و در زیرشاخهٔ .../lib/lua/5.0 نصب خواهد شد. در این حالت، باید با
تغییر دادن متغیر LUA_PATH در Lua به برنامه‌های خود مشخص کنید آن را در کجا پیدا کنند:
.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"
توابع پودمان Lua برای RRDtool در صورتی که نتوانند آرگومان‌های ارائه‌شده را تحلیل
کنند، برنامهٔ شما را با نمایش ردگیری پشته (stack traceback) متوقف خواهند کرد.
با این حال، به جای این که بگذارید برنامه متوقف شود، می‌توانید با فراخوانی توابع پودمان
از طریق فراخوانی‌های حفاظت‌شدهٔ Lua یعنی \*(Aqpcall\*(Aq یا \*(Aqxpcall\*(Aq،
خطاها را خودتان دریافت کرده و مدیریت نمایید.
.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
اگر برنامهٔ بالا را اجرا کنیم، خروجی زیر را خواهیم گرفت:
.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"
توابع rrd.first، rrd.last، rrd.graph، rrd.info و rrd.fetch مقادیر حاصل از پردازش خود را بازمی‌گردانند.
.PP
\&\fBrrd.first\fR یک مقدار INTEGER منفرد را برمی‌گرداند که نشان‌دهندهٔ برچسب زمانی (timestamp)
نخستین نمونهٔ داده در یک RRA درون یک فایل RRD است. نمونه‌ای برای بازگرداندن برچسب زمانی
نخستین داده در سومین RRA (اندیس ۲):
.PP
.Vb 1
\&     local firstdate = rrd.first(\*(Aqexample.rrd\*(Aq, \*(Aq\-\-rraindex\*(Aq, 2)
.Ve
.PP
\&\fBrrd.last\fR یک مقدار INTEGER منفرد را برمی‌گرداند که نشان‌دهندهٔ زمان آخرین به‌روزرسانی است.
.PP
.Vb 1
\&     local lastupdate = rrd.last(\*(Aqexample.rrd\*(Aq)
.Ve
.PP
\&\fBrrd.graph\fR مقادیر x\-size و y\-size تصویر ایجادشده و یک جدول شامل نتایج آرگومان‌های
PRINT را برمی‌گرداند.
.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 یک جدول بازمی‌گرداند که در آن کلیدها و مقادیر نشان‌دهندهٔ نام‌ها و مقادیر ویژگی‌های
RRD هستند.
.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 همان پارامترهای rrd.graph را می‌گیرد، اما تنها یک جدول برمی‌گرداند.
جدول بازگردانده‌شده حاوی اطلاعات فراداده‌ای دربارهٔ نمودار، مانند ابعاد آن و موقعیت ناحیهٔ نمودار
روی تصویر است. هنگامی که با یک نام فایل خالی فراخوانی شود، محتوای تصویر نمودار نیز درون جدول
قرار می‌گیرد (کلید \*(Aqimage\*(Aq).
.PP
\&\fBrrd.updatev\fR نیز یک جدول برمی‌گرداند. کلیدهای این جدول رشته‌هایی هستند که از پیوند دادن
برچسب زمانی، اندیس RRA و نام منبع داده (DS) به ازای هر نقطه دادهٔ تجمیع‌شده (CDP) که در نتیجهٔ
فراخوانی به‌روزرسانی جاری روی دیسک ذخیره شده، ساخته شده‌اند. مقادیر این کلیدها همان مقادیر CDP هستند.
.PP
\&\fBrrd.fetch\fR در میان این توابع از نظر مقادیر بازگشتی پیچیده‌ترین است. این تابع ۵ مقدار برمی‌گرداند:
برچسب زمانی اولیه، گام (step)، دو آرایهٔ موازی به ترتیب شامل نام‌های منبع داده و نقاط دادهٔ آنها،
و برچسب زمانی نهایی.
.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 "نویسندگان (AUTHORS)"
.IX Header "AUTHORS"
Fidelis Assis <fidelis@pobox.com>