'\"macro stdmacro
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  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 PMGENMAP 1 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
pmgenmap \- تولید کد C برای ساده‌سازی مدیریت معیارهای کارایی
.SH "خلاصه دستور (SYNOPSIS)"
\f3pmgenmap\f1
[\f2infile\f1]
.SH "توضیحات (DESCRIPTION)"
.de CR
.ie t \f(CR\\$1\f1\\$2
.el \fI\\$1\f1\\$2
..
با دریافت یک یا چند فهرست از نام‌های معیار در
.I infile
یا در ورودی استاندارد،
.B pmgenmap
اعلان‌های C و ماکروهای
.BR cpp (1)
مناسب برای استفاده در «رابط برنامه‌نویسی معیارهای کارایی» (PMAPI) را در خروجی استاندارد تولید می‌کند.
.PP
اعلان‌های تولیدشده توسط
.B pmgenmap
کدنویسی برنامه‌های کارخواهی را که از PMAPI استفاده می‌کنند ساده می‌سازد.
.PP
ورودی باید شامل یک یا چند فهرست از نام‌های معیار به شکل زیر باشد:
.PP
.ft CR
.nf
.in +0.5i
listname {
    metricname1 symbolname1
    metricname2 symbolname2
    ...
}
.in
.fi
.ft 1
.PP
که اعلان‌های C و
.BR cpp (1)
را به شکل زیر تولید خواهد کرد:
.PP
.ft CR
.nf
.in +0.5i
char *listname[] = {
#define symbolname1 0
    "metricname1",
#define symbolname2 1
    "metricname2",
    ...
};
.in
.fi
.ft 1
.PP
اعلان‌های آرایه‌ایِ تولیدشده به‌عنوان آرگومان برای
.BR pmLookupName (3)
مناسب هستند، و از ثابت‌های تعریف‌شده با
.BR #define
می‌توان برای نمایه‌گذاری
.CR vset
ها در ساختار
.CR pmResult
که توسط فراخوانی
.BR pmFetch (3)
بازگردانده می‌شود، استفاده کرد.
.PP
بدیهی است که
.CR listname
باید با قواعد نام‌گذاری شناسه‌ها در C مطابقت داشته باشد، هر
.CR symbolname
باید از قواعد نام‌گذاری ماکروهای
.BR cpp (1)
پیروی کند، و انتظار می‌رود هر
.CR metricname
یک نام معتبر برای معیارهای کارایی باشد (برای جزئیات بیشتر به
.BR PMNS (5)
مراجعه کنید).
.PP
ورودی ممکن است شامل خطوط توضیح به سبک
.BR sh
باشد، یعنی خطوطی که در آن‌ها نخستین نویسهٔ غیرفاصله یک «\f3#\f1» است؛ این خطوط در خروجی به توضیحات تک‌خطی یا چندخطی C به سبک K&R تبدیل می‌شوند.
برای نمونه، ورودی:
.sp
.PP
.ft CR
.nf
.in +0.5i
# leading block of multi-line comments
# initialization group
foo {
        a.b.c   ONE
        d.e.f.g TWO
        # embedded block of multi-lines
        # comments and boring pad text
        xx.yy.zz        THREE
}

# trailing single line comment
.in
.fi
.ft 1
.sp
.PP
خروجی زیر را تولید می‌کند:
.PP
.ft CR
.nf
.in +0.5i
/*
 * leading block of multi-line comments
 * initialization group
 */
char *foo[] = {
#define ONE 0
        "a.b.c",
#define TWO 1
        "d.e.f.g",
/*
 * embedded block of multi-lines
 * comments and boring pad text
 */
#define THREE 2
        "xx.yy.zz",

};


/* trailing single line comment */
.in
.fi
.ft 1
.SH "مثال‌ها (EXAMPLES)"
برای رعایت اختصار، کد مدیریت خطا حذف شده است و فرض شده معیارهای انتخاب‌شده دارای چندین مقدار نیستند.
.PP
فایل ورودی
.PP
.ft CR
.nf
.in +0.5i
mystats {
    kernel.percpu.cpu.idle     IDLE
    kernel.percpu.cpu.sys      SYS
    kernel.percpu.cpu.user     USER
    hinv.ncpu                       NCPU
}
.in
.fi
.ft 1
.PP
کد C زیر را تولید می‌کند که برای
.BR #include
کردن مناسب است:
.PP
.ft CR
.nf
.in +0.5i
/*
 * Performance Metrics Name Space Map
 * Built by pmgenmap from the file
 * mystats.metrics
 * on Wed Dec 28 19:44:17 EST 1994
 *
 * Do not edit this file!
 */

char *mystats[] = {
#define IDLE    0
        "kernel.percpu.cpu.idle",
#define SYS     1
        "kernel.percpu.cpu.sys",
#define USER    2
        "kernel.percpu.cpu.user",
#define NCPU    3
        "hinv.ncpu",

};
.in
.fi
.ft 1
.PP
با استفاده از کد تولیدشده توسط
.BR pmgenmap ،
اکنون می‌توانیم به شکل زیر به‌سادگی معیارهایی را از «زیرسیستم جمع‌آوری معیارهای کارایی» (PMCS) به دست آوریم:

.PP
.ft CR
.nf
.in +0.5i
#define MAX_PMID 4

    int         trip = 0;
    int         numpmid = sizeof(mystats)/sizeof(mystats[0]);
    double      duration;
    pmResult    *resp;
    pmResult    *prev;
    pmID        pmidlist[MAX_PMID];

    pmNewContext(PM_CONTEXT_HOST, "localhost");
    pmLookupName(numpmid, mystats, pmidlist);
    pmFetch(numpmid, pmidlist, &resp);

    printf("%d CPUs: %d usr   %d sys   %d   idle\n",
           resp->vset[NCPU]->vlist[0].value.lval,
           resp->vset[USER]->vlist[0].value.lval,
           resp->vset[SYS]->vlist[0].value.lval,
           resp->vset[IDLE]->vlist[0].value.lval);
.in
.fi
.ft 1
.PP
برخی از فراخوانی‌ها برای اطمینان از قابلیت حمل، جهت وضوح بیشتر از کد بالا حذف شده‌اند \- مثال بالا نباید به‌عنوان الگویی برای برنامه‌نویسی استفاده شود.
به‌ویژه، مقادیر خام معیارها در حالی استفاده شده‌اند که برای تعیین معناشناسی هر معیار باید
.BR pmLookupDesc (3)
فراخوانی می‌شد.
.PP
مثال‌های کامل‌تری که نحوهٔ استفاده از
.B pmgenmap
را نشان می‌دهند و می‌توانند به‌عنوان پایه‌ای برای توسعهٔ برنامه‌ها به کار روند، در برنامه‌های نمایشی PCP گنجانده شده‌اند؛ مانند
.IR $PCP_DEMOS_DIR/pmclient .
.SH "فایل‌ها (FILES)"
.TP 5
.I $PCP_VAR_DIR/pmns/*
فایل‌های مشخصات پیش‌فرض PMNS
.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند \fBPCP_\fP برای پارامتریک‌سازی نام فایل‌ها و دایرکتوری‌های مورداستفادهٔ PCP به کار می‌روند.
در هر نصب، فایل
\fI/etc/pcp.conf\fP
حاوی مقادیر محلی برای این متغیرها است.
همان‌طور که در
\fBpcp.conf\fP(5)
شرح داده شده است، متغیر
\fB$PCP_CONF\fP
می‌تواند برای مشخص کردن یک فایل پیکربندی جایگزین استفاده شود.
.SH "همچنین ببینید (SEE ALSO)"
.BR cpp (1)،
.BR PMAPI (3)،
.BR pmFetch (3)،
.BR pmLookupName (3)،
.BR pmNewContext (3)،
.BR pcp.conf (5)،
.BR pcp.env (5)
و
.BR PMNS (5).

.\" control lines for scripts/man-spell
.\" +ok+ EST MAX_PMID NCPU SYS hinv ing {from #include -ing}
.\" +ok+ ncpu {from hinv.ncpu}
.\" +ok+ yy zz {from xx.yy.zz}
.\" +ok+ {all below are variables from C code example}
.\" +ok+ listname metricname mystats
.\" +ok+ pmidlist prev
.\" +ok+ resp sizeof symbolname sys