.\" -*- 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 "RRDCGI 1"
.TH RRDCGI 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)"
rrdcgi \- ساخت صفحات وب حاوی نمودارهای RRD بر اساس قالب‌ها
.SH "خلاصه دستور (SYNOPSIS)"
.IX Header "SYNOPSIS"
\&\f(CW\*(C`#!/path/to/\*(C'\fR\fBrrdcgi\fR [\fB\-\-filter\fR|\fB\-f\fR]
.SH "توضیحات (DESCRIPTION)"
.IX Header "DESCRIPTION"
برنامه \fBrrdcgi\fR به نوعی یک مفسر اسکریپت بسیار محدود است. هدف آن اجرا به عنوان یک برنامه cgi و تجزیه قالب یک صفحه وب شامل برچسب‌های ویژه <RRD:: است. \fBrrdcgi\fR این برچسب‌ها را تفسیر کرده و بر اساس آن‌ها عمل می‌کند. در پایان، یک صفحه وب شامل سرآیندهای CGI لازم را چاپ می‌کند.
.PP
برنامه \fBrrdcgi\fR محتوای قالب را در ۳ مرحله تجزیه می‌کند. در هر مرحله تنها به دنبال زیرمجموعه‌ای از برچسب‌ها می‌گردد. این کار امکان تو در تو قرار دادن برچسب‌ها را فراهم می‌سازد.
.PP
تجزیه‌کننده آرگومان از همان معناشناسی آشنا در C\-shell شما استفاده می‌کند.
.IP \fB\-\-filter\fR|\fB\-f\fR 8
.IX Item "--filter|-f"
فرض می‌کند که rrdcgi به عنوان یک فیلتر اجرا می‌شود، نه به عنوان یک cgi.
.SS "کلیدواژه‌ها (Keywords)"
.IX Subsection "Keywords"
.IP "RRD::CV \fIname\fR" 8
.IX Item "RRD::CV name"
متغیر CGI با نام مشخص‌شده را درج می‌کند.
.IP "RRD::CV::QUOTE \fIname\fR" 8
.IX Item "RRD::CV::QUOTE name"
متغیر CGI با نام مشخص‌شده را درج می‌کند، اما آن را نقل‌قول‌گذاری (quote) می‌کند تا برای استفاده به عنوان آرگومان در برچسب دیگر RRD:: آماده باشد. به این ترتیب حتی اگر در مقدار متغیر CGI فاصله وجود داشته باشد، همچنان به عنوان یک آرگومان در نظر گرفته می‌شود.
.IP "RRD::CV::PATH \fIname\fR" 8
.IX Item "RRD::CV::PATH name"
متغیر CGI با نام مشخص‌شده را درج کرده، آن را کوت می‌کند و اطمینان حاصل می‌کند که نه با \*(Aq/\*(Aq شروع شود و نه شامل \*(Aq..\*(Aq باشد. این کار برای اطمینان از این است که هیچ نام مسیر مشکل‌سازی نتواند از طریق رابط CGI وارد شود.
.IP "RRD::GETENV \fIvariable\fR" 8
.IX Item "RRD::GETENV variable"
مقدار یک متغیر محیطی را دریافت می‌کند.
.Sp
.Vb 1
\& <RRD::GETENV REMOTE_USER>
.Ve
.Sp
در صورتی که از نوعی کنترل دسترسی روی دایرکتوری استفاده کنید، ممکن است نام کاربر دوردست (remote user) را به شما بازگرداند.
.IP "RRD::GOODFOR \fIseconds\fR" 8
.IX Item "RRD::GOODFOR seconds"
تعداد ثانیه‌هایی که این صفحه باید معتبر بماند را مشخص می‌کند. این کار باعث می‌شود rrdcgi سرآیندهای Last\-Modified و Expire و در صورتی که تعداد ثانیه‌ها \fIمنفی\fR باشد، یک سرآیند Refresh در خروجی تولید کند.
.IP "RRD::INCLUDE \fIfilename\fR" 8
.IX Item "RRD::INCLUDE filename"
محتوای فایل مشخص‌شده را درون صفحه بازگردانده‌شده از cgi می‌گنجاند.
.IP "RRD::SETENV \fIvariable\fR \fIvalue\fR" 8
.IX Item "RRD::SETENV variable value"
اگر می‌خواهید نمودارهای خود را در منطقه‌ی زمانی متفاوتی از منطقه‌ی خود نمایش دهید، می‌توانید از
.Sp
.Vb 1
\& <RRD::SETENV TZ UTC>
.Ve
.Sp
استفاده کنید تا اطمینان حاصل شود که همه‌چیز در زمان جهانی (Universal Time) نمایش داده می‌شود. توجه داشته باشید که مقادیر مجاز برای TZ به سیستم‌عامل شما بستگی دارد.
.IP "RRD::SETVAR \fIvariable\fR \fIvalue\fR" 8
.IX Item "RRD::SETVAR variable value"
مشابه SETENV، اما برای متغیرهای محلی.
.IP "RRD::GETVAR \fIvariable\fR" 8
.IX Item "RRD::GETVAR variable"
مشابه GETENV، اما برای متغیرهای محلی.
.IP "RRD::TIME::LAST \fIrrd\-file\fR \fIstrftime\-format\fR" 8
.IX Item "RRD::TIME::LAST rrd-file strftime-format"
این برچسب با زمان آخرین تغییر RRD انتخاب‌شده جایگزین می‌شود. زمان با رشته مشخص‌شده در آرگومان دوم و با قالب \fIstrftime\fR قالب‌بندی می‌شود.
.IP "RRD::TIME::NOW \fIstrftime\-format\fR" 8
.IX Item "RRD::TIME::NOW strftime-format"
این برچسب با زمان کنونی روز جایگزین می‌شود. زمان با رشته مشخص‌شده در آرگومان و با قالب \fIstrftime\fR قالب‌بندی می‌شود.
.Sp
توجه داشته باشید که اگر از قالب strftime خود دو نقطه (:) بازمی‌گردانید، چنانچه قرار است زمان به عنوان آرگومانی برای یک دستور GRAPH استفاده شود، ممکن است لازم باشد با استفاده از \e از آن‌ها گریز (escape) بگیرید.
.IP "RRD::TIME::STRFTIME \fISTART|END\fR \fIstart\-spec\fR \fIend\-spec\fR \fIstrftime\-format\fR" 8
.IX Item "RRD::TIME::STRFTIME START|END start-spec end-spec strftime-format"
این برچسب با زمان قالب‌بندی‌شده توسط strftime با استفاده از قالب \fIstrftime\-format\fR روی \fIstart\-spec\fR یا \fIend\-spec\fR (بسته به این که \fISTART\fR یا \fIEND\fR مشخص شده باشد) جایگزین می‌شود. هر دو مقدار \fIstart\-spec\fR و \fIend\-spec\fR باید ارائه شوند زیرا هر کدام می‌توانند نسبت به دیگری تعریف شده باشند. هدف از این کار، فراهم آوردن عناوین زیبا روی نمودارها با زمان‌هایی است که درک آن‌ها برای افراد ناآشنا با RRDtool بسیار ساده‌تر از «\-2weeks» باشد.
.Sp
مجدداً توجه داشته باشید که اگر از قالب strftime خود دو نقطه (:) بازمی‌گردانید، چنانچه قرار است زمان به عنوان آرگومانی برای یک دستور GRAPH استفاده شود، ممکن است لازم باشد با استفاده از \e از آن گریز بگیرید.
.IP "RRD::GRAPH \fIrrdgraph arguments\fR" 8
.IX Item "RRD::GRAPH rrdgraph arguments"
این برچسب نمودار RRD تعریف‌شده با آرگومان‌هایش را ایجاد کرده و سپس با یک برچسب مناسب <IMG ... > که به نمودار ارجاع می‌دهد جایگزین می‌شود. گزینه \fB\-\-lazy\fR در rrdgraph می‌تواند برای اطمینان از این که نمودارها تنها در صورت منقضی شدن دوباره تولید شوند، استفاده شود. آرگومان‌های برچسب \fBRRD::GRAPH\fR مطابق با توضیحات موجود در صفحه راهنمای \fBrrdgraph\fR کار می‌کنند.
.Sp
برای کاهش بار روی سرور خود، از گزینه \fB\-\-lazy\fR در برچسب‌های RRD::GRAPH استفاده کنید. این گزینه تضمین می‌کند که نمودارها فقط هنگامی که نسخه‌های قدیمی منقضی شده باشند، دوباره تولید شوند.
.Sp
اگر قالب \fB\-\-imginfo\fR اختصاصی خود را مشخص نکنید، مورد زیر استفاده خواهد شد:
.Sp
.Vb 1
\& <IMG SRC="%s" WIDTH="%lu" HEIGHT="%lu">
.Ve
.Sp
توجه داشته باشید که \f(CW%s\fR بیانگر بخش نام فایل نمودار ایجاد شده است؛ تمامی دایرکتوری‌های مشخص‌شده در آرگومان فایل PNG نادیده گرفته خواهند شد.
.IP "RRD::PRINT \fInumber\fR" 8
.IX Item "RRD::PRINT number"
اگر برچسب \fBRRD::GRAPH\fR قبلی شامل هرگونه آرگومان \fBPRINT\fR بوده باشد، می‌توانید با این برچسب به خروجی آن‌ها دسترسی پیدا کنید. آرگومان \fInumber\fR به شماره آرگومان \fBPRINT\fR اشاره دارد. نخستین \fBPRINT\fR دارای شماره 0 است.
.IP "RRD::INTERNAL <var>" 8
.IX Item "RRD::INTERNAL <var>"
این برچسب با یک متغیر داخلی جایگزین می‌شود. در حال حاضر این متغیرها شناخته شده‌اند:
VERSION و COMPILETIME.
این متغیرها مقادیر کامپایل‌شده در برنامه را نشان می‌دهند.
.SH "مثال ۱ (EXAMPLE 1)"
.IX Header "EXAMPLE 1"
مثال زیر یک صفحه وب با یک نمودار RRD منفرد ایجاد می‌کند.
.PP
.Vb 9
\& #!/usr/local/bin/rrdcgi
\& <HTML>
\& <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
\& <BODY>
\& <H1>RRDCGI Example Page</H1>
\& <P>
\& <RRD::GRAPH demo.png \-\-lazy \-\-title="Temperatures"
\&          DEF:cel=demo.rrd:exhaust:AVERAGE
\&          LINE2:cel#00a000:"D. Celsius">
\&
\& </P>
\& </BODY>
\& </HTML>
.Ve
.SH "مثال ۲ (EXAMPLE 2)"
.IX Header "EXAMPLE 2"
این اسکریپت کمی پیشرفته‌تر است؛ به شما اجازه می‌دهد تا آن را از طریق فرمی که متغیر RRD_NAME را تنظیم می‌کند اجرا کنید. سپس از RRD_NAME برای انتخاب RRD مورد نظر به عنوان منبع نمودار استفاده می‌شود.
.PP
.Vb 10
\& #!/usr/local/bin/rrdcgi
\& <HTML>
\& <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
\& <BODY>
\& <H1>RRDCGI Example Page for <RRD::CV RRD_NAME></H1>
\& <H2>Selection</H2>
\& <FORM><INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomA> Room A,
\&       <INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomB> Room B.
\&       <INPUT TYPE=SUBMIT></FORM>
\& <H2>Graph</H2>
\& <P>
\& <RRD::GRAPH <RRD::CV::PATH RRD_NAME>.png \-\-lazy
\&          \-\-title "Temperatures for "<RRD::CV::QUOTE RRD_NAME>
\&          DEF:cel=<RRD::CV::PATH RRD_NAME>.rrd:exhaust:AVERAGE
\&          LINE2:cel#00a000:"D. Celsius">
\&
\& </P>
\& </BODY>
\& </HTML>
.Ve
.SH "مثال ۳ (EXAMPLE 3)"
.IX Header "EXAMPLE 3"
این مثال نحوه مدیریت وضعیتی را نشان می‌دهد که در آن فایل‌های RRD، نمودارها و cgi\-binها در دایرکتوری‌های جداگانه‌ای قرار دارند.
.PP
.Vb 10
\& #!/.../bin/rrdcgi
\& <HTML>
\& <HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
\& <BODY>
\& <H1>RRDCGI test Page</H1>
\& <RRD::GRAPH
\&  /.../web/pngs/testhvt.png
\&  \-\-imginfo \*(Aq<IMG SRC=/.../pngs/%s WIDTH=%lu HEIGHT=%lu >\*(Aq
\&  \-\-lazy \-\-start \-1d \-\-end now
\&  DEF:http_src=/.../rrds/test.rrd:http_src:AVERAGE
\&  AREA:http_src#00ff00:http_src
\& >
\& </BODY>
\& </HTML>
.Ve
.PP
نکته ۱: بخش /.../ را با دایرکتوری‌های مربوطه جایگزین کنید.
.PP
نکته ۲: مقدار SRC=/.../pngs باید از دیدگاه وب‌سرور/مرورگر یک مسیر معتبر باشد.
.SH "نویسنده (AUTHOR)"
.IX Header "AUTHOR"
Tobias Oetiker <tobi@oetiker.ch>