'\"! tbl | mmdoc
'\"macro stdmacro
.\"
.\" Copyright (c) 2014,2019 Red Hat.
.\"
.\" 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 PMGETOPT 1 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pmgetopt\f1 \- تجزیه‌کننده گزینه‌های اسکریپت شل در Performance Co-Pilot
.SH "خلاصه دستور (SYNOPSIS)"
\f3$PCP_BINADM_DIR/pmgetopt\f1
[\f3\-u?\f1]
[\f3\-c \f2file\f1]
[\f3\-D\f1 \f2debug\f1]
[\f3\-p \f2name\f1]
[\f3\-\-\f1]
[\f2parameters\f1]
.SH "توضیحات (DESCRIPTION)"
.de EX
.in +0.5i
.ie t .ft CB
.el .ft B
.ie t .sp .5v
.el .sp
.ta \\w' 'u*8
.nf
..
.de EE
.fi
.ie t .sp .5v
.el .sp
.ft R
.in
..
دستور
.B pmgetopt
برای تجزیه گزینه‌های خط فرمان در اسکریپت‌های شلِ مورد استفاده در Performance Co-Pilot (مجموعه ابزار PCP) به کار می‌رود.
این ابزار همچنین برای تولید پیام‌های نحوه استفاده (راهنما) برای آن اسکریپت‌ها استفاده می‌شود.
.PP
پارامترهای ارائه‌شده به
.B pmgetopt
به دو شکل هستند: در ابتدا، گزینه‌های مختص خودِ
.B pmgetopt
ارسال شده و با استفاده از سازوکار \-\- خاتمه می‌یابند.
پس از آن، تمامی پارامترهای منتقل‌شده به اسکریپت شل باید ارسال شوند (که معمولاً این کار به‌سادگی با متغیر "$@" صورت می‌گیرد).
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های خط فرمانِ موجود عبارتند از:
.TP 5
\f3\-c\f1=\f2file\f1, \f3\-\-config\f1=\f2file\f1
یک
.I file
پیکربندی با قالبی که در ادامه شرح داده شده است، با استفاده از این گزینه به
.B pmconfig
ارسال می‌شود.
در صورت حذف این گزینه،
.B pmconfig
پیکربندی خود را از جریان ورودی استاندارد می‌خواند.
.TP
\f3\-p\f1=\f2name\f1, \f3\-\-progname\f1=\f2name\f1
هنگام تجزیه پارامترهای اسکریپت شلِ فراخواننده، پیام‌های خطا و راهنما به جای ارجاع به خودِ
.B pmgetopt
به‌عنوان منبع خطا، شامل
.I name
برنامه داده‌شده خواهند بود.
.TP
\f3\-u\f1, \f3\-\-usage\f1
با استفاده از این گزینه می‌توان پیام راهنمای مناسبی برای اسکریپت شل فراخواننده تولید کرد تا آن را به‌عنوان راهنمای خود ارائه دهد.
.TP
\fB\-?\fR, \fB\-\-help\fR
نمایش پیام نحوه استفاده برای خودِ
.B pmgetopt
و خروج.
.PP
.B pmgetopt
پارامترهای داده‌شده را تجزیه کرده و خروجی را در قالبی مناسب برای بارگذاری (source کردن) در اسکریپت شل فراخواننده تولید می‌کند.
هنگامی که طبق مشخصات هر دو فرم کوتاه و بلند یک آرگومان مجاز باشند،
.B pmgetopt
برای پردازش ساده‌تر در شل همواره فرم کوتاه را مشخص می‌کند.
اگر آرگومان‌هایی ارائه شوند که با پیکربندی مطابقت نداشته باشند، درخواستی برای پیام نحوه استفاده (\-?) تولید می‌شود تا اسکریپت فراخواننده به آن پاسخ دهد.
هرگونه پارامتر غیراز گزینه، با قرار گرفتن نویسه جداکننده خط فاصله دوبل (\-\-) در ابتدای آن، به اسکریپت فراخواننده بازگردانده می‌شود.
بنابراین یک اسکریپت باید به محض شناسایی این جداکننده، پردازش گزینه‌ها را متوقف کرده و پردازش آرگومان‌های غیرگزینه‌ای را آغاز نماید.
.PP
برخلاف دستور داخلی شل
.IR getopt ،
متغیرهایی مانند $OPTARG مقداردهی نمی‌شوند و اسکریپت فراخواننده معمولاً از دستورهای داخلی شل نظیر
.IR eval ،
.I set
و دستور جابه‌جایی موضعی
.I shift
استفاده می‌کند تا از پردازش صحیح گزینه‌ها اطمینان حاصل شود.
.SH "پیکربندی (CONFIGURATION)"
قالب پیکربندی مورد استفاده توسط
.B pmgetopt
به‌گونه‌ای طراحی شده است که شباهت نزدیکی به پیام راهنمایی داشته باشد که در صورت وجود آرگومان‌های نامعتبر (یا گزینه
\f3\-?\f1، \f3\-\-help\f1)
تولید می‌شود.
.PP
اساساً دو نوع خط پیکربندی وجود دارد \- دستورها و گزینه‌ها.
دستورها امکان ارسال فراداده به فرایند پردازش گزینه‌ها را فراهم می‌کنند، و گزینه‌ها همان گزینه‌های مجاز خط فرمان هستند که اسکریپت شل خواهد پذیرفت.
ابتدای خطوط دستور نویسه هش (#) قرار می‌گیرد، در حالی که خطوط گزینه‌ها همواره با یک خط تیره (تک یا دوبل) آغاز می‌شوند.
هر خط دیگر در پیکربندی، که ممکن است شامل سرآیندهای راهنما یا متون توضیحی باشد، هیچ اثری بر تجزیه گزینه‌ها ندارد و بدون تغییر در پیام راهنما کپی خواهد شد.
.PP
مجموعه دستورها عبارتند از:
.I getopt
(مشخصات گزینه‌های دارای آرگومان کوتاه را به‌صورت دستی ارائه می‌دهد؛ در صورت عدم وجود، از روی گزینه‌های ارائه‌شده تولید خواهد شد)،
.I usage
(خلاصه‌ای کوتاه و تک‌خطی ارائه می‌دهد که در ابتدای پیام راهنما استفاده می‌شود و پیش از گزارش، مقدار
.I progname
در ابتدای آن قرار می‌گیرد)، و
.I end
که به
.B pmgetopt
اعلام می‌کند پردازش دستورها و گزینه‌های بعدی را متوقف کند \- هر متن دیگری پس از آن مشاهده شود، به‌سادگی به انتهای پیام راهنما پیوست خواهد شد.
.PP
برای هر یک از گزینه‌های استاندارد PCP، همان‌طور که در
.BR PCPIntro (1)
شرح داده شده، یک نماد اختصاری وجود دارد.
اگر هر یک از این گزینه‌ها (برای مثال \f3\-\-host\f1) به‌صورت یک کلمه منفرد در هر خطی ظاهر شود، به گزینه مناسب برای اسکریپت شل تبدیل خواهد شد، شامل تمام فراداده‌های مربوط به آن گزینه (اینکه آیا آرگومانی می‌پذیرد، فرم‌های کوتاه و بلند گزینه و غیره).
.PP
استفاده از نماد مساوی («=») نشان‌دهنده وجود یک آرگومان الزامی برای هر گزینه، هم در فرم کوتاه و هم فرم بلند است.
هر گزینه غیراستاندارد باید با توضیحی غیرخالی درباره آن آرگومان همراه باشد.
.SH "مثال‌ها (EXAMPLES)"
به‌عنوان مثال، موارد زیر یک پیکربندی معتبر است:
.EX
# Usage: [options] node...

Options:
    \-\-archive
    \-d, \-\-delay            pause between updates for archive replay
    \-\-host
    \-\-interval
    \-i=INST, \-\-insts=INST  comma-separated metrics instance list
    \-r                     output raw counters (no rate conversion)
    \-\-width=N              set the width of each column of output
    \-\-timezone
    \-\-help
.EE
.PP
این پیکربندی در صورت اجرا به شکل نشان داده شده، پیام راهنمای زیر را تولید خواهد کرد.
.EX
$ pmgetopt \-\-usage \-\-progname=clusterstat \-\- "$@"
Usage: clusterstat [options] node...

Options:
  \-a FILE, \-\-archive=FILE
                        metrics source is a PCP archive
  \-d, \-\-delay           pause between updates for archive replay
  \-h HOST, \-\-host=HOST  metrics source is PMCD on host
  \-t DELTA, \-\-interval=DELTA
                        sampling interval
  \-i INST, \-\-insts=INST comma-separated metrics instance list
  \-r                    output raw counters (no rate conversion)
  \-\-width=N             set the width of each column of output
  \-Z TZ, \-\-timezone=TZ  set reporting timezone
  \-?, \-\-help            show this usage message and exit
.EE
.PP
چندین نمونه از کاربرد
.B pmgetopt
بخشی از مجموعه ابزار PCP را تشکیل می‌دهند؛ به‌ویژه اسکریپت‌های
.BR pcp (1)
و
.BR pmlogmv (1)
نمونه‌های مرجع بسیار خوبی هستند.
.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند \fBPCP_\fP برای پارامتریک‌سازی نام فایل‌ها و دایرکتوری‌های مورد استفاده PCP به کار می‌روند.
در هر نصب، فایل \fI/etc/pcp.conf\fP حاوی مقادیر محلی برای این متغیرها است.
می‌توان از متغیر \fB$PCP_CONF\fP برای مشخص کردن یک فایل پیکربندی جایگزین استفاده کرد، همان‌طور که در \fBpcp.conf\fP(5) شرح داده شده است.
.SH "گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)"
گزینه
.B \-D
یا
.B \-\-debug
خروجی پیام‌های عیب‌یابی تکمیلی را در
.I stderr
فعال می‌کند تا به اولویت‌بندی و بررسی مشکلات کمک نماید، هرچند این اطلاعات گاهی پیچیده بوده و در وهله اول برای راهنمایی توسعه‌دهندگان در نظر گرفته شده است تا کاربران نهایی.
آرگومان
.I debug
فهرستی از گزینه‌های اشکال‌زدایی است که با کاما از هم جدا شده‌اند؛ از
.BR pmdbg (1)
همراه با گزینه
.B \-l
استفاده کنید تا فهرستی از گزینه‌های اشکال‌زدایی موجود و مفهوم آن‌ها را به دست آورید.
.SH "همچنین ببینید (SEE ALSO)"
.BR pcp (1)،
.BR pmlogmv (1)،
.BR pmgetopt_r (3)،
.BR pcp.conf (5)
و
.BR pcp.env (5).

.\" control lines for scripts/man-spell
.\" +ok+ INST clusterstat sp {from .sp in troff macro}