'\" t
.\"
.\" Copyright (c) 2011 Ken McDonell.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMCPP 1 "" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pmcpp\f1 \- پیش‌پردازنده ساده برای Performance Co-Pilot
.SH "خلاصه دستور (SYNOPSIS)"
.B pmcpp
[\f3\-Prs?\f1]
[\f3\-D\f1 \f2name\f1[=\f2value\f1] ...]
[\f3\-I\f1 \f2dir\f1 ...]
[[\f2infile\f1] [\f2outfile\f1]]
.SH "توضیحات (DESCRIPTION)"
دستور
.B pmcpp
یک پیش‌پردازنده بسیار ساده را فراهم می‌کند که در اصل برای دستکاری فایل‌های فضای نام سنجه عملکرد (PMNS) در
Performance Co-Pilot (PCP)
طراحی شده بود، اما بعداً برای ارائه بلوک‌های شرطی، پردازش گنجاندن فایل (include)، اجرای درجا (in-line) دستورهای پوسته
و جایگزینی ماکرو برای فایل‌های دلخواه تعمیم یافت.
این ابزار اغلب به طور داخلی برای پردازش فایل(های) PMNS پس از فراخوانی
.BR pmLoadNameSpace (3)
یا
.BR pmLoadASCIINameSpace (3)
و همچنین برای پیش‌پردازش فایل‌های پیکربندی
.BR pmlogger (1)
به کار می‌رود.
.PP
خطوط ورودی از
.I infile
(یا ورودی استاندارد در صورتی که
.I infile
مشخص نشده باشد) خوانده شده، پردازش می‌شوند و در
.I outfile
(یا خروجی استاندارد در صورتی که
.I outfile
مشخص نشده باشد) نوشته می‌شوند.
.PP
تمام توضیحات به سبک C به صورت /* ... */ از جریان ورودی حذف می‌شوند.
.PP
هیچ ماکروی از پیش‌تعریف‌شده‌ای برای
.B pmcpp
وجود ندارد، اگرچه می‌توان ماکروها را در خط فرمان با استفاده از گزینه
.B \-D
تعریف کرد، که در آن
.I name
و
.I value
باید از همان قواعد شرح داده شده در زیر برای دستورالعمل
.B #define
پیروی کنند.
.PP
دستور
.B pmcpp
دستورالعمل‌های زیر را در جریان ورودی می‌پذیرد (مشابه
.BR cpp (1)):
.IP \(bu 3n
\fB#include "\fIfilename\fB"\fR
.br
یا
.br
\fB#include <\fIfilename\fB>\fR
.br
در هر دو حالت، مسیر جستجوی دایرکتوری برای
.I filename
ابتدا خودِ
.I filename
را بررسی می‌کند، سپس دایرکتوریِ فایل ورودی
.I infile
در خط فرمان (در صورت وجود)، و پس از آن هر دایرکتوری مشخص‌شده در آرگومان‌های خط فرمان
.BR \-I ،
و در نهایت دایرکتوری
.B $PCP_VAR_DIR/pmns
(مورد آخر برای سازگاری عقروعلی با نسخه‌های پیشین
.B pmcpp
و کاربرد ضمنی برگرفته از
.BR pmLoadASCIINameSpace (3)
است).
دستورالعمل‌های
.B #include
می‌توانند به صورت تودرتو، حداکثر تا عمق ۵ سطح باشند.
.IP \(bu 3n
\fB#shell "\fIcommand\fB"\fR
.br
یا
.br
\fB#shell '\fIcommand\fB'
.br
دستور پوسته
.I command
اجرا خواهد شد و خروجی استاندارد آن در جریان داده‌هایی که قرار است توسط
.B pmcpp
پردازش شوند درج می‌گردد. از نظر عملکردی، این دستورالعمل مشابه
.B #include
است، با این تفاوت که خطوط ورودی به جای یک فایل، از یک
.I command
خوانده می‌شوند.
دستورالعمل
.B #shell
بیشتر برای گنجاندن یا کنار گذاشتن دستورالعمل‌های
.B #define
یا
.B #undef
بر پایه منطق زمان اجرا در
.I command
کاربرد دارد.
.IP \(bu 3n
\fB#define \fIname value\fR
.br
یا
.br
\fB#define \fIname \fB"\fIvalue\fB"\fR
.br
یا
.br
\fB#define \fIname \fB'\fIvalue\fB'\fR
.br
مقداری را برای ماکروی
.I name
تعریف می‌کند که باید یک نام معتبر به سبک زبان C باشد، بنابراین باید با یک حرف الفبا یا زیرخط آغاز شده و به دنبال آن صفر یا چند کاراکتر الفبایی‌عددی یا زیرخط بیاید.
مقدار
.I value
اختیاری است (و پیش‌فرض آن یک رشته خالی است).
هیچ سازوکار گریز از کاراکتر (escape) وجود ندارد، اما می‌توان از کوتیشن‌های تکی یا دوتایی برای تعریف یک
.I value
شامل کاراکترهای خاص یا فاصله‌های سفید افقی تعبیه‌شده (بدون خطوط جدید) استفاده کرد.
.IP \(bu 3n
\fB#undef \fIname\fR
.br
تعریف ماکروی
.IR name
را در صورت وجود حذف می‌کند.
.IP \(bu 3n
\fB#ifdef \fIname\fR
.br
\&...
.br
\fB#endif\fR
.br
یا
.br
\fB#ifndef \fIname\fR
.br
\&...
.br
\fB#endif\fR
.br
خطوط محصور بسته به این‌که ماکروی
.I name
تعریف شده باشد یا خیر، حذف یا گنجانده خواهند شد.
.IP \(bu 3n
\fB#else\fR
.br
درون یک بلوک
.B #ifdef
یا
.BR #ifndef ،
می‌توان از
.B #else
برای مشخص کردن خطوطی که در صورت نادرست بودن شرط «if» پیشین باید گنجانده شوند، استفاده کرد.
.PP
جایگزینی ماکرو با شکستن جریان ورودی به کلماتی انجام می‌شود که توسط فاصله‌های سفید یا کاراکترهایی که در نام ماکرو معتبر نیستند (یعنی غیرالفبایی‌عددی و غیرزیرخط) از هم جدا شده‌اند.
هر کلمه بررسی می‌شود و اگر با نام یک ماکرو مطابقت داشته باشد، با مقدار آن ماکرو جایگزین می‌شود؛ در غیر این صورت کلمه دست‌نخورده باقی می‌ماند..PP
به طور کلی به ازای هر خط ورودی، یک خط خروجی وجود دارد؛ اگرچه در صورتی که متن به دلیل مدیریت کامنت‌ها یا دستورهای شرطی حذف شده باشد، این خط ممکن است خالی باشد.
هنگامی که تغییری در جریان ورودی ایجاد شود، یک خط خروجی اضافی به این شکل تولید می‌شود:
.PP
.ti +10n
# lineno "filename"
.PP
تا مشخص کند خط خروجی
.I بعدی
مربوط به شماره خط
.I lineno
از فایل ورودی
.IR filename
است.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های خط فرمان موجود عبارتند از:
.TP 5
\fB\-D\fR \fIname[=value]\fR, \fB\-\-define\fR=\fIname[=value]\fR
ماکرویی را با یک مقدار اختیاری تعریف می‌کند، همان‌طور که پیش‌تر توضیح داده شد.
.TP
\fB\-I\fR \fIdir\fR, \fB\-\-include\fR=\fIdir\fR
یک دایرکتوری اضافی برای جستجوی فایل‌های include.
.TP
\fB\-P\fR
از تولید خطوط نشانگر شماره خط (linemarker) که در بالا توضیح داده شد جلوگیری می‌کند.
.TP
\fB\-s\fR, \fB\-\-shell\fR
سبک ورودی مورد انتظار را از شبیه به C به شبیه به شل تغییر می‌دهد
(جایی که # پیشوند کامنت است).
این کار باعث اعمال تغییرات زیر در رفتار
.B pmcpp
می‌شود:
.RS 5
.PD 0
.IP \(bu 3n
نویسه پیشوند کنترلی از
.B #
به
.BR %
تغییر می‌یابد؛ بنابراین به عنوان مثال
.B %include
به جای
.BR #include
و
.B %ifdef
به جای
.BR #ifdef
به کار می‌رود.
.IP \(bu 3n
هیچ حذف کامنتی به سبک C انجام نمی‌شود.
.PD
.RE
.TP
\fB\-r\fR, \fB\-\-restrict\fR
کنترل دقیق‌تری روی گسترش ماکرو فراهم می‌کند \- این
گزینه جایگزینی ماکرو را به کلماتی محدود می‌کند که با الگوهای
.BR # name
یا
.BR #{ name }
یا در صورت مشخص شدن
.BR \-s ،
با
.BR % name
یا
.BR %{ name }
مطابقت داشته باشند.
در این حالت، نام ماکرو
.I name
به تنهایی در جریان ورودی هرگز گسترش نخواهد یافت؛ با این حال در خطوط کنترلی (مانند
.BR #ifdef )
نام ماکرو
.I name
باید به تنهایی و بدون نویسه پیشوند یا آکولادها ظاهر شود (به بخش «مثال‌ها (EXAMPLES)» در زیر مراجعه کنید).
.TP
\fB\-?\fR, \fB\-\-help\fR
نمایش پیام راهنمای استفاده و خروج.
.PP
قابلیت‌های مهم
.BR cpp (1)
که توسط
.B pmcpp
پشتیبانی
.B نمی‌شوند
عبارتند از:
.PD 0
.IP \(bu 3n
ماکروهای دارای پارامتر \- ماکروهای
.B pmcpp
تنها از جایگزینی رشته‌ای بدون پارامتر پشتیبانی می‌کنند.
.IP \(bu 3n
\fB#if \fIexpr\fR
.br
\&...
.br
\fB#endif\fR
.IP \(bu 3n
استفاده تو در تو از
.B #ifdef
یا
.BR #ifndef .
.IP \(bu 3n
حذف کامنت‌های سبک ++C، مانند // comment.
.IP \(bu 3n
بازیابی از خطا \- نخستین خطایی که توسط
.B pmcpp
شناسایی شود مهلک خواهد بود.
.IP \(bu 3n
گزینه‌های خط فرمان
.BR cpp (1)
مانند
.BR \-o ،
.BR \-W ،
.BR \-U
و
.BR \-x .
.PD.SH "مثال‌ها (EXAMPLES)"
.\" man.1.in from src dir
.TS
box;
lR s
lB | lB
lf(CR) | lf(CR).
دستور: \fBpmcpp\fP
_
ورودی	خروجی
_
	# 1 "<stdin>"
#define MYDOMAIN 27

root {	root {
    foo   MYDOMAIN:0:0	   foo   27:0:0
}	}
.TE
.PP
برای مثال‌های زیر، فایل
.I frequencies
شامل این خطوط است:
.nf
.ft CR
.in +8n
%define dk_freq 1minute
%define cpu_freq '15 sec'
.in
.ft
.fi
.PP
.\" man.2.in from src dir
.TS
box;
lR s
lB | lB
lf(CR) | lf(CR).
دستور: \fBpmcpp -rs\fP
_
ورودی	خروجی
_
# get logging frequencies	# get logging frequencies
# e.g. dk_freq macro	# e.g. dk_freq macro
%include "frequencies"

log mandatory on %dk_freq {	log mandatory on 1minute {
    disk.dev	   disk.dev
}	}

# note no %want_cpu here	# note no %want_cpu here
%ifdef want_cpu
%define cpu_pfx 'kernel.all.cpu.'
log mandatory on %cpu_freq {
    %{cpu_pfx}user
    %{cpu_pfx}sys
}
%endif
.TE
.PP
.TS
box;
lR s
lB | lB
lf(CR) | lf(CR).
دستور: \fBpmcpp -rs -D want_cpu\fP
_
ورودی	خروجی
_
# get logging frequencies	# get logging frequencies
# e.g. dk_freq macro	# e.g. dk_freq macro
%include "frequencies"

log mandatory on %dk_freq {	log mandatory on 1min {
    disk.dev	   disk.dev
}	}

# note no %want_cpu here	# note no %want_cpu here
%ifdef want_cpu
%define cpu_pfx 'kernel.all.cpu.'
log mandatory on %cpu_freq {	log mandatory on 15 sec {
    %{cpu_pfx}user	   kernel.all.cpu.user
    %{cpu_pfx}sys	   kernel.all.cpu.sys
}	}
%endif
.TE.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند \fBPCP_\fP برای مقداردهی و تعیین نام فایل‌ها و دایرکتوری‌های مورد استفاده PCP به کار می‌روند.
در هر نصب، فایل \fI/etc/pcp.conf\fP حاوی مقادیر محلی برای این متغیرها است.
متغیر \fB$PCP_CONF\fP می‌تواند برای مشخص کردن یک فایل پیکربندی جایگزین استفاده شود، همان‌طور که در \fBpcp.conf\fP(5) شرح داده شده است.
.PP
برای متغیرهای محیطی تأثیرگذار بر ابزارهای PCP، به \fBpmGetOptions\fP(3) مراجعه کنید.
.SH "همچنین ببینید (SEE ALSO)"
.BR cpp (1),
.BR pmLoadASCIINameSpace (3),
.BR pmLoadNameSpace (3),
.BR pcp.conf (5),
.BR pcp.env (5)
و
.BR PMNS (5).

.\" control lines for scripts/man-spell
.\" +ok+ MYDOMAIN cpu_freq cpu_pfx dk_freq infile linemarker
.\" +ok+ lineno pre sys want_cpu