.\" -*- 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 "CPP 1"
.TH CPP 1 2026-08-07 gcc-16.2.0 GNU
.\" 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)"
arm-none-eabi-cpp \- پیش‌پردازنده C برای معماری ARM
.SH "خلاصه دستور (SYNOPSIS)"
.IX Header "SYNOPSIS"
cpp [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR]
    [\fB\-I\fR\fIdir\fR...] [\fB\-iquote\fR\fIdir\fR...]
    [\fB\-M\fR|\fB\-MM\fR] [\fB\-MG\fR] [\fB\-MF\fR \fIfilename\fR]
    [\fB\-MP\fR] [\fB\-MQ\fR \fItarget\fR...]
    [\fB\-MT\fR \fItarget\fR...]
    \fIinfile\fR [[\fB\-o\fR] \fIoutfile\fR]
.PP
تنها کاربردی‌ترین گزینه‌ها در بالا آورده شده‌اند؛ برای فهرست کامل‌تری از گزینه‌های ویژه پیش‌پردازنده به ادامه مراجعه کنید.
علاوه بر این،
.B cpp
بیشتر گزینه‌های درایور
.B gcc
را که در اینجا فهرست نشده‌اند می‌پذیرد. برای جزئیات به مستندات GCC مراجعه فرمایید.
.SH "توضیحات (DESCRIPTION)"
.IX Header "DESCRIPTION"
پیش‌پردازنده سی (C)، که اغلب با عنوان
.I cpp
شناخته می‌شود، یک
.I "پردازنده ماکرو"
است که پیش از کامپایل، به طور خودکار توسط کامپایلر C برای تبدیل برنامه شما استفاده می‌شود. از این رو پردازنده ماکرو نامیده می‌شود که به شما امکان می‌دهد
.I ماکروها
را تعریف کنید؛ ماکروها اختصارات کوتاهی برای ساختارهای طولانی‌تر هستند.
.PP
پیش‌پردازنده C تنها برای استفاده با کدهای منبع C، C++ و Objective\-C در نظر گرفته شده است. در گذشته، به عنوان یک پردازنده متنی عمومی سوءاستفاده شده است. این ابزار در مواجهه با ورودی‌هایی که از قواعد واژگانی C پیروی نمی‌کنند متوقف شده و با خطا روبرو می‌شود. به عنوان مثال، آپوستروف‌ها به عنوان ابتدای ثابت‌های نویسه‌ای در نظر گرفته شده و موجب خطا می‌شوند. همچنین نمی‌توانید به آن برای حفظ ویژگی‌هایی از ورودی که برای زبان‌های خانواده C اهمیتی ندارند تکیه کنید. اگر یک Makefile پیش‌پردازش شود، تمام فاصله‌های تب سخت (hard tabs) حذف شده و Makefile کار نخواهد کرد.
.PP
با این حال، شما اغلب می‌توانید از cpp برای مواردی غیر از C نیز با موفقیت استفاده کنید. سایر زبان‌های برنامه‌نویسی شبه‌الگول (مانند Ada و غیره) اغلب بدون مشکل هستند. اسمبلی نیز با رعایت احتیاط همین‌گونه است. حالت
.B \-traditional\-cpp
فاصله‌های خالی بیشتری را حفظ می‌کند و در سایر زمینه‌ها نیز آسان‌گیرتر است. با نوشتن کامنت‌ها به سبک C یا C++ به جای کامنت‌های زبان اصلی، و همچنین با ساده نگه داشتن ماکروها، می‌توان از بسیاری از مشکلات دوری کرد.
.PP
تا حد امکان، باید از پیش‌پردازنده‌ای متناسب با زبانی که با آن کد می‌نویسید استفاده کنید. نسخه‌های مدرن اسمبلر گنو دارای امکانات ماکرو هستند. بیشتر زبان‌های برنامه‌نویسی سطح بالا سازوکارهای کامپایل شرطی و گنجاندن فایل مختص به خود را دارند. اگر هیچ‌کدام کارساز نبود، یک پردازنده متن عمومی واقعی مانند GNU M4 را امتحان کنید.
.PP
پیش‌پردازنده‌های C در برخی جزئیات تفاوت دارند. این راهنما به بررسی پیش‌پردازنده GNU C می‌پردازد که فرامجموعه کوچکی از ویژگی‌های استاندارد ISO C را فراهم می‌کند. در حالت پیش‌فرض، پیش‌پردازنده GNU C چند مورد موردنیاز استاندارد را انجام نمی‌دهد. این‌ها ویژگی‌هایی هستند که به ندرت، یا شاید هرگز، استفاده می‌شوند و ممکن است تغییرات شگفت‌آوری در معنای برنامه‌ای که انتظار آنها را ندارد ایجاد کنند. برای دستیابی به استاندارد دقیق ISO C، بسته به اینکه کدام نسخه از استاندارد را می‌خواهید، باید از گزینه‌های
.BR \-std=c90 ،
.BR \-std=c99 ،
.B \-std=c11
یا
.B \-std=c17
استفاده کنید. همچنین برای دریافت تمام پیام‌های تشخیصی الزامی، باید از
.B \-pedantic
نیز استفاده کنید.
.PP
این راهنما رفتار پیش‌پردازنده ISO را شرح می‌دهد. برای به حداقل رساندن تفاوت‌های غیرضروری، در مواردی که رفتار پیش‌پردازنده ISO با معناشناسی سنتی تعارضی ندارد، پیش‌پردازنده سنتی نیز باید به همان صورت عمل کند. تفاوت‌های گوناگونی که وجود دارند، به طور مفصل در بخش
.B "حالت سنتی (Traditional Mode)"
بیان شده‌اند.
.PP
جهت شفافیت، مگر در مواردی که خلاف آن قید شده باشد، منظور از
.B CPP
در این راهنما، GNU CPP است.
.SH "گزینه‌ها (OPTIONS)"
.IX Header "OPTIONS"
دستور
.B cpp
دو نام فایل را به عنوان آرگومان دریافت می‌کند:
.I infile
و
.IR outfile .
پیش‌پردازنده فایل
.I infile
را به همراه سایر فایل‌هایی که با
.B #include
مشخص شده‌اند می‌خواند. تمام خروجی تولیدشده توسط ترکیب فایل‌های ورودی در
.I outfile
نوشته می‌شود.
.PP
هر یک از
.I infile
یا
.I outfile
می‌تواند
.B \-
باشد، که برای
.I infile
به معنای خواندن از ورودی استاندارد و برای
.I outfile
به معنای نوشتن در خروجی استاندارد است. اگر هر یک از فایل‌ها حذف شود، دقیقاً به این معنی است که برای آن فایل
.B \-
تعیین شده است. همچنین می‌توانید از گزینه
.B \-o
.I outfile
برای تعیین فایل خروجی استفاده کنید.
.PP
مگر در مواردی که خلاف آن قید شده باشد، یا گزینه به
.B =
ختم شود، تمام گزینه‌هایی که آرگومان دریافت می‌کنند، آرگومان آنها می‌تواند بلافاصله پس از گزینه، یا با یک فاصله بین گزینه و آرگومان ظاهر شود:
.B \-Ifoo
و
.B \-I foo
اثر یکسانی دارند.
.PP
بسیاری از گزینه‌ها نام‌های چندحرفی دارند؛ بنابراین چندین گزینه تک‌حرفی را
.I نمی‌توان
با هم ادغام کرد:
.B \-dM
بسیار متفاوت از
.B \-d \-M
است.
.IP "\fB\-D\fR \fIname\fR" 4
.IX Item "-D name"
.PD 0
.IP \fB\-\-define\-macro=\fR\fIname\fR 4
.IX Item "--define-macro=name"
.IP "\fB\-\-define\-macro\fR \fIname\fR" 4
.IX Item "--define-macro name"
.PD
از پیش
.I name
را به عنوان یک ماکرو با تعریف
\f(CW1\fR
تعریف می‌کند.
.IP "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4
.IX Item "-D name=definition"
.PD 0
.IP \fB\-\-define\-macro=\fR\fIname\fR\fB=\fR\fIdefinition\fR 4
.IX Item "--define-macro=name=definition"
.IP "\fB\-\-define\-macro\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4
.IX Item "--define-macro name=definition"
.PD
محتویات
.I definition
نشانه‌گذاری شده و به گونه‌ای پردازش می‌شود که گویی در مرحله سوم ترجمه درون یک دستور
.B #define
ظاهر شده است. به طور خاص، تعریف توسط نویسه‌های خط جدیدِ درونی کوتاه می‌شود.
.Sp
اگر پیش‌پردازنده را از یک شل یا برنامه‌ای شبه‌شل فراخوانی می‌کنید، ممکن است نیاز باشد از قواعد نقل‌قول (کوتیشن) شل برای محافظت از نویسه‌هایی مانند فاصله که در نحو شل معنا دارند، استفاده کنید.
.Sp
اگر می‌خواهید یک ماکروی تابع‌گونه (function\-like) در خط فرمان تعریف کنید، فهرست آرگومان‌های آن را درون پرانتزها قبل از علامت مساوی (در صورت وجود) بنویسید. پرانتزها در اکثر شل‌ها معنا دارند، بنابراین باید گزینه را کوت کنید. در
.B sh
و
.BR csh ،
قالب
\&\fB\-D\*(Aq\fR\fIname\fR\fB(\fR\fIargs...\fR\fB)=\fR\fIdefinition\fR\fB\*(Aq\fR
کار می‌کند.
.Sp
گزینه‌های
.B \-D
و
.B \-U
به ترتیبی که در خط فرمان داده شده‌اند پردازش می‌شوند. تمام گزینه‌های
.B \-imacros
.I file
و
.B \-include
.I file
پس از تمامی گزینه‌های
.B \-D
و
.B \-U
پردازش می‌گردند.
.IP "\fB\-U\fR \fIname\fR" 4
.IX Item "-U name"
.PD 0
.IP \fB\-\-undefine\-macro=\fR\fIname\fR 4
.IX Item "--undefine-macro=name"
.IP "\fB\-\-undefine\-macro\fR \fIname\fR" 4
.IX Item "--undefine-macro name"
.PD
هرگونه تعریف قبلی از
.I name
را، خواه توکار باشد یا با گزینه
.B \-D
تعیین شده باشد، لغو می‌کند.
.IP "\fB\-include\fR \fIfile\fR" 4
.IX Item "-include file"
.PD 0
.IP \fB\-\-include=\fR\fIfile\fR 4
.IX Item "--include=file"
.IP "\fB\-\-include\fR \fIfile\fR" 4
.IX Item "--include file"
.PD
پرونده
.I file
را پردازش می‌کند به گونه‌ای که گویی
\f(CW\*(C`#include "file"\*(C'\fR
به عنوان نخستین خط پرونده منبع اصلی درج شده است. با این حال، نخستین دایرکتوری مورد جستجو برای
.IR file ،
دایرکتوری کاری پیش‌پردازنده است
.I به جای
دایرکتوری دربردارنده پرونده منبع اصلی. در صورتی که در آنجا یافت نشود، مانند حالت عادی در باقیمانده زنجیره جستجوی
\f(CW\*(C`#include "..."\*(C'\fR
جستجو می‌شود.
.Sp
اگر چند گزینه
.B \-include
داده شود، پرونده‌ها به ترتیبی که در خط فرمان آمده‌اند گنجانده می‌شوند.
.IP "\fB\-imacros\fR \fIfile\fR" 4
.IX Item "-imacros file"
.PD 0
.IP \fB\-\-imacros=\fR\fIfile\fR 4
.IX Item "--imacros=file"
.IP "\fB\-\-imacros\fR \fIfile\fR" 4
.IX Item "--imacros file"
.PD
دقیقاً مانند
.B \-include
است، جز اینکه هرگونه خروجی حاصل از پیمایش
.I file
دور انداخته می‌شود. ماکروهایی که این پرونده تعریف می‌کند تعریف‌شده باقی می‌مانند. این امر به شما امکان می‌دهد تمام ماکروها را از یک هدر استخراج کنید بدون اینکه اعلانات آن را نیز پردازش کنید.
.Sp
تمام پرونده‌های مشخص‌شده با
.B \-imacros
پیش از تمام پرونده‌های مشخص‌شده با
.B \-include
پردازش می‌شوند.
.IP \fB\-undef\fR 4
.IX Item "-undef"
هیچ ماکروی مختص سیستم یا مختص GCC را از پیش تعریف نمی‌کند. ماکروهای استاندارد از پیش تعریف‌شده همچنان تعریف‌شده باقی می‌مانند.
.IP \fB\-pthread\fR 4
.IX Item "-pthread"
ماکروهای اضافی مورد نیاز برای استفاده از کتابخانه نخ‌های پازیکس (POSIX threads) را تعریف می‌کند. شما باید از این گزینه به طور هماهنگ هم برای کامپایل و هم برای پیوند (لینک) استفاده کنید. این گزینه در اهداف GNU/Linux، اکثر مشتقات یونیکس، و همچنین روی اهداف Cygwin و MinGW معماری x86 پشتیبانی می‌شود.
.IP \fB\-M\fR 4
.IX Item "-M"
.PD 0
.IP \fB\-\-dependencies\fR 4
.IX Item "--dependencies"
.PD
به جای خروجی دادن نتیجه پیش‌پردازش، قاعده‌ای مناسب برای \fBmake\fR که وابستگی‌های پرونده منبع اصلی را توصیف می‌کند، خروجی می‌دهد. پیش‌پردازنده یک قاعده \fBmake\fR شامل نام پرونده شیء برای آن پرونده منبع، یک دو‌نقطه، و نام تمام پرونده‌های گنجانده‌شده، از جمله مواردی که از گزینه‌های خط فرمان \fB\-include\fR یا \&\fB\-imacros\fR می‌آیند را خروجی می‌دهد.
.Sp
مگر اینکه به صراحت مشخص شده باشد (با \fB\-MT\fR یا \fB\-MQ\fR)، نام پرونده شیء از نام پرونده منبع با جایگزینی هر پسوند با پسوند پرونده شیء و حذف هر بخش پوشه پیشین تشکیل می‌شود. اگر پرونده‌های گنجانده‌شده زیادی وجود داشته باشد، قاعده با استفاده از خط جدید\-\fB\e\fR به چندین خط تقسیم می‌شود. این قاعده دستوری ندارد.
.Sp
این گزینه خروجی اشکال‌زدایی پیش‌پردازنده مانند \&\fB\-dM\fR را متوقف نمی‌کند. برای جلوگیری از ترکیب چنین خروجی اشکال‌زدایی با قواعد وابستگی، باید پرونده خروجی وابستگی را به صراحت با \&\fB\-MF\fR مشخص کنید، یا از یک متغیر محیطی مانند \&\fBDEPENDENCIES_OUTPUT\fR استفاده نمایید. خروجی اشکال‌زدایی همچنان طبق معمول به جریان خروجی استاندارد فرستاده می‌شود.
.Sp
ارسال \fB\-M\fR به راه‌انداز مستلزم \fB\-E\fR است و هشدارها را با یک \fB\-w\fR ضمنی غیرفعال می‌کند.
.IP \fB\-MM\fR 4
.IX Item "-MM"
.PD 0
.IP \fB\-\-user\-dependencies\fR 4
.IX Item "--user-dependencies"
.PD
مشابه \fB\-M\fR است، اما به پرونده‌های هدر موجود در پوشه‌های هدر سیستم و همچنین پرونده‌های هدری که به‌طور مستقیم یا غیرمستقیم از چنین هدری گنجانده شده‌اند، اشاره نمی‌کند.
.Sp
این بدان معنی است که انتخاب قلاب‌ها یا گیومه‌ها در یک دستورالعمل \&\fB#include\fR به خودی خود تعیین نمی‌کند که آیا آن هدر در خروجی وابستگی \fB\-MM\fR ظاهر می‌شود یا خیر.
.IP "\fB\-MF\fR \fIfile\fR" 4
.IX Item "-MF file"
هنگام استفاده به همراه \fB\-M\fR یا \fB\-MM\fR، پرونده‌ای را برای نوشتن وابستگی‌ها در آن مشخص می‌کند. اگر هیچ سوییچ \fB\-MF\fR داده نشود، پیش‌پردازنده قواعد را به همان جایی می‌فرستد که خروجی پیش‌پردازش‌شده را ارسال می‌کرد.
.Sp
هنگام استفاده با گزینه‌های راه‌انداز \fB\-MD\fR یا \fB\-MMD\fR، گزینه \&\fB\-MF\fR پرونده خروجی پیش‌فرض وابستگی را بازنویسی می‌کند.
.Sp
اگر \fIfile\fR برابر \fI\-\fR باشد، وابستگی‌ها در \fIstdout\fR نوشته می‌شوند.
.IP \fB\-MG\fR 4
.IX Item "-MG"
.PD 0
.IP \fB\-\-print\-missing\-file\-dependencies\fR 4
.IX Item "--print-missing-file-dependencies"
.PD
در ارتباط با گزینه‌ای مانند \fB\-M\fR که درخواست تولید وابستگی دارد، \fB\-MG\fR فرض می‌کند که پرونده‌های هدر ناموجود پرونده‌های تولیدشده هستند و آن‌ها را بدون ایجاد خطا به فهرست وابستگی‌ها اضافه می‌کند. نام پرونده وابستگی مستقیماً از دستورالعمل \&\f(CW\*(C`#include\*(C'\fR بدون افزودن هیچ مسیری در ابتدا گرفته می‌شود. \fB\-MG\fR همچنین خروجی پیش‌پردازش‌شده را متوقف می‌کند، زیرا پرونده هدر ناموجود این خروجی را بی‌استفاده می‌سازد.
.Sp
این قابلیت در به‌روزرسانی خودکار makefileها استفاده می‌شود.
.IP \fB\-Mno\-modules\fR 4
.IX Item "-Mno-modules"
تولید وابستگی را برای رابط‌های ماژول کامپایل‌شده غیرفعال می‌کند.
.IP \fB\-MP\fR 4
.IX Item "-MP"
این گزینه به CPP دستور می‌دهد که برای هر وابستگی غیر از پرونده اصلی، یک هدف ساختگی اضافه کند، به طوری که هر کدام به چیزی وابسته نباشند. این قواعد ساختگی خطاهایی را دور می‌زنند که در صورت حذف پرونده‌های هدر بدون به‌روزرسانی متناظر \fIMakefile\fR، توسط \fBmake\fR ایجاد می‌شوند.
.Sp
این یک خروجی نمونه است:
.Sp
.Vb 1
\&        test.o: test.c test.h
\&        
\&        test.h:
.Ve
.IP "\fB\-MT\fR \fItarget\fR" 4
.IX Item "-MT target"
هدف قاعده‌ای که توسط تولید وابستگی صادر می‌شود را تغییر می‌دهد. به‌طور پیش‌فرض CPP نام پرونده ورودی اصلی را می‌گیرد، هر بخش پوشه و هر پسوند پرونده مانند \fB.c\fR را حذف می‌کند، و پسوند شیء معمول پلتفرم را به آن الحاق می‌نماید. نتیجه همان هدف است.
.Sp
یک گزینه \fB\-MT\fR هدف را دقیقاً برابر با رشته‌ای که مشخص می‌کنید قرار می‌دهد. اگر چندین هدف می‌خواهید، می‌توانید آن‌ها را به عنوان یک آرگومان واحد به \fB\-MT\fR مشخص کنید، یا از چندین گزینه \fB\-MT\fR استفاده نمایید.
.Sp
برای مثال، \fB\-MT\ \*(Aq$(objpfx)foo.o\*(Aq\fR ممکن است خروجی زیر را بدهد:
.Sp
.Vb 1
\&        $(objpfx)foo.o: foo.c
.Ve
.IP "\fB\-MQ\fR \fItarget\fR" 4
.IX Item "-MQ target"
مشابه \fB\-MT\fR است، اما کاراکترهایی را که برای Make خاص هستند نقل‌قول می‌کند. مقدار \fB\-MQ\ \*(Aq$(objpfx)foo.o\*(Aq\fR این خروجی را می‌دهد:
.Sp
.Vb 1
\&        $$(objpfx)foo.o: foo.c
.Ve
.Sp
هدف پیش‌فرض به‌طور خودکار نقل‌قول می‌شود، گویی با \&\fB\-MQ\fR مشخص شده است.
.IP \fB\-MD\fR 4
.IX Item "-MD"
.PD 0
.IP \fB\-\-write\-dependencies\fR 4
.IX Item "--write-dependencies"
.PD
گزینه \&\fB\-MD\fR معادل \fB\-M \-MF\fR \fIfile\fR است، با این تفاوت که \&\fB\-E\fR در آن ضمنی نیست. راه‌انداز مقدار \fIfile\fR را بر اساس داده شدن یا نشدن گزینه \fB\-o\fR تعیین می‌کند. اگر داده شده باشد، راه‌انداز از آرگومان آن اما با پسوند \fI.d\fR استفاده می‌کند، در غیر این صورت نام پرونده ورودی را گرفته، بخش‌های پوشه و پسوند را حذف کرده و پسوند \fI.d\fR را اعمال می‌کند.
.Sp
اگر \fB\-MD\fR همراه با \fB\-E\fR استفاده شود، هر سوییچ \&\fB\-o\fR به عنوان مشخص‌کننده پرونده خروجی وابستگی در نظر گرفته می‌شود، اما اگر بدون \fB\-E\fR استفاده شود، هر \fB\-o\fR مشخص‌کننده یک پرونده شیء هدف خواهد بود.
.Sp
از آنجا که \fB\-E\fR ضمنی نیست، \fB\-MD\fR می‌تواند برای تولید پرونده خروجی وابستگی به عنوان یک اثر جانبی از فرآیند کامپایل استفاده شود.
.IP \fB\-MMD\fR 4
.IX Item "-MMD"
.PD 0
.IP \fB\-\-write\-user\-dependencies\fR 4
.IX Item "--write-user-dependencies"
.PD
مشابه \fB\-MD\fR است با این تفاوت که فقط به پرونده‌های هدر کاربر اشاره می‌کند، نه پرونده‌های هدر سیستم.
.IP \fB\-fpreprocessed\fR 4
.IX Item "-fpreprocessed"
به پیش‌پردازنده نشان می‌دهد که پرونده ورودی قبلاً پیش‌پردازش شده است. این امر مواردی مانند بسط ماکرو، تبدیل سه‌نگاره‌ها، الحاق خطوط جدید اسکیپ‌شده و پردازش بیشتر دستورالعمل‌ها را متوقف می‌کند. پیش‌پردازنده همچنان توضیحات را شناسایی و حذف می‌کند، بنابراین می‌توانید پرونده‌ای را که با \fB\-C\fR پیش‌پردازش شده است بدون مشکل به کامپایلر ارسال کنید. در این حالت، پیش‌پردازنده یکپارچه چیزی بیش از یک توکن‌ساز برای بخش‌های جلویی نیست.
.Sp
اگر پرونده ورودی دارای یکی از پسوندهای \fB.i\fR، \fB.ii\fR یا \fB.mi\fR باشد، گزینه \&\fB\-fpreprocessed\fR به صورت ضمنی فعال می‌شود. این‌ها پسوندهایی هستند که GCC برای پرونده‌های پیش‌پردازش‌شده ایجادشده توسط \&\fB\-save\-temps\fR استفاده می‌کند.
.IP \fB\-fdirectives\-only\fR 4
.IX Item "-fdirectives-only"
هنگام پیش‌پردازش، دستورالعمل‌ها را پردازش می‌کند، اما ماکروها را بسط نمی‌دهد.
.Sp
رفتار این گزینه به گزینه‌های \fB\-E\fR و \fB\-fpreprocessed\fR بستگی دارد.
.Sp
همراه با \fB\-E\fR، پیش‌پردازش به پردازش دستورالعمل‌هایی مانند \f(CW\*(C`#define\*(C'\fR، \f(CW\*(C`#ifdef\*(C'\fR و \f(CW\*(C`#error\*(C'\fR محدود می‌شود. سایر عملیات پیش‌پردازنده مانند بسط ماکرو و تبدیل سه‌نگاره انجام نمی‌شوند. علاوه بر این، گزینه \fB\-dD\fR به‌طور ضمنی فعال می‌گردد.
.Sp
همراه با \fB\-fpreprocessed\fR، پیش‌تعریف ماکروهای خط فرمان و اکثر ماکروهای توکار غیرفعال می‌شود. ماکروهایی مانند \f(CW\*(C`_\|_LINE_\|_\*(C'\fR که به زمینه وابسته هستند، طبق معمول پردازش می‌شوند. این امر امکان کامپایل پرونده‌هایی را فراهم می‌کند که قبلاً با \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR پیش‌پردازش شده‌اند.
.Sp
در صورت وجود هر دو گزینه \fB\-E\fR و \fB\-fpreprocessed\fR، قواعد مربوط به \&\fB\-fpreprocessed\fR اولویت دارند. این کار امکان پیش‌پردازش کامل پرونده‌هایی را که قبلاً با \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR پیش‌پردازش شده‌اند، فراهم می‌کند.
.IP \fB\-fdollars\-in\-identifiers\fR 4
.IX Item "-fdollars-in-identifiers"
پذیرش \fB$\fR در شناسه‌ها.
.IP \fB\-fextended\-identifiers\fR 4
.IX Item "-fextended-identifiers"
پذیرش نام‌های کاراکتر عمومی و کاراکترهای گسترش‌یافته در شناسه‌ها. این گزینه به‌طور پیش‌فرض برای C99 (و نسخه‌های بعدی استاندارد C) و C++ فعال است.
.IP \fB\-fno\-canonical\-system\-headers\fR 4
.IX Item "-fno-canonical-system-headers"
هنگام پیش‌پردازش، مسیرهای هدر سیستم را با یکسان‌سازی کوتاه نمی‌کند.
.IP \fB\-fmax\-include\-depth=\fR\fIdepth\fR 4
.IX Item "-fmax-include-depth=depth"
تنظیم حداکثر عمق تودرتویی دستورالعمل #include. مقدار پیش‌فرض 200 است.
.IP \fB\-fsearch\-include\-path\fR[\fB=\fR\fIkind\fR] 4
.IX Item "-fsearch-include-path[=kind]"
جستجوی پرونده‌های ورودی در مسیر #include، نه فقط در پوشه جاری. این گزینه به ویژه در ماژول‌های C++20 مفید است که در آن‌ها هر دو واحد هدر و واحدهای رابط ماژول باید مستقیماً کامپایل شوند:
.Sp
.Vb 1
\&        g++ \-c \-std=c++20 \-fmodules \-fsearch\-include\-path bits/stdc++.h bits/std.cc
.Ve
.Sp
مقدار \&\fIkind\fR به طور پیش‌فرض \fBuser\fR است که در مسیر جستجوی \f(CW#include "..."\fR جستجو می‌کند؛ همچنین می‌توانید برای مسیر جستجوی \f(CW\*(C`#include <...>\*(C'\fR به صراحت \fBsystem\fR را مشخص نمایید.
.IP \fB\-ftabstop=\fR\fIwidth\fR 4
.IX Item "-ftabstop=width"
فاصله بین ایستگاه‌های تب را تنظیم می‌کند. این کار به پیش‌پردازنده کمک می‌کند تا شماره ستون‌های صحیح را در هشدارها یا خطاها گزارش دهد، حتی اگر تب‌ها در خط وجود داشته باشند. اگر مقدار کمتر از 1 یا بیشتر از 100 باشد، گزینه نادیده گرفته می‌شود. مقدار پیش‌فرض 8 است.
.IP \fB\-ftrack\-macro\-expansion\fR[\fB=\fR\fIlevel\fR] 4
.IX Item "-ftrack-macro-expansion[=level]"
موقعیت توکن‌ها را در طول بسط ماکروها ردیابی می‌کند. این کار به کامپایلر اجازه می‌دهد هنگامی که خطای کامپایل در یک بسط ماکرو رخ می‌دهد، پیام‌های تشخیصی را درباره پشته بسط ماکروی فعلی صادر کند. استفاده از این گزینه باعث می‌شود پیش‌پردازنده و کامپایلر حافظه بیشتری مصرف کنند. پارامتر \fIlevel\fR می‌تواند برای انتخاب سطح دقت ردیابی موقعیت توکن و در نتیجه کاهش مصرف حافظه در صورت لزوم استفاده شود. مقدار \fB0\fR برای \fIlevel\fR این گزینه را غیرفعال می‌کند. مقدار \fB1\fR موقعیت‌های توکن را در حالتی تقلیل‌یافته به منظور حداقل بار اضافی حافظه ردیابی می‌نماید. در این حالت تمام توکن‌های ناشی از بسط یک آرگومان از یک ماکروی شبیه تابع، موقعیت یکسانی دارند. مقدار \fB2\fR موقعیت توکن‌ها را به‌طور کامل ردیابی می‌کند. این مقدار بیشترین مصرف حافظه را دارد. هنگامی که این گزینه بدون آرگومان داده شود، مقدار پیش‌فرض پارامتر \&\fB2\fR خواهد بود.
.Sp
توجه داشته باشید که \f(CW\*(C`\-ftrack\-macro\-expansion=2\*(C'\fR به‌طور پیش‌فرض فعال است.
.IP \fB\-fmacro\-prefix\-map=\fR\fIold\fR\fB=\fR\fInew\fR 4
.IX Item "-fmacro-prefix-map=old=new"
هنگام پیش‌پردازش پرونده‌های مقیم در پوشه \fIold\fR، ماکروهای \f(CW\*(C`_\|_FILE_\|_\*(C'\fR و \f(CW\*(C`_\|_BASE_FILE_\|_\*(C'\fR را طوری بسط می‌دهد که گویی پرونده‌ها در پوشه \fInew\fR قرار دارند. این گزینه می‌تواند برای تغییر یک مسیر مطلق به یک مسیر نسبی با استفاده از \fI.\fR برای \&\fInew\fR استفاده شود که می‌تواند منجر به ساخت‌های تکرارپذیرتر و مستقل از مکان گردد. این گزینه همچنین بر \&\f(CW\*(C`_\|_builtin_FILE()\*(C'\fR در حین کامپایل تأثیر می‌گذارد. همچنین نگاه کنید به \&\fB\-ffile\-prefix\-map\fR و \fB\-fcanon\-prefix\-map\fR.
.IP \fB\-fexec\-charset=\fR\fIcharset\fR 4
.IX Item "-fexec-charset=charset"
مجموعه کاراکترهای اجرایی را که برای ثابت‌های رشته‌ای و کاراکتری استفاده می‌شود، تنظیم می‌کند. مقدار پیش‌فرض UTF\-8 است. \fIcharset\fR می‌تواند هر کدگذاری پشتیبانی‌شده توسط روال کتابخانه \f(CW\*(C`iconv\*(C'\fR سیستم باشد.
.IP \fB\-fwide\-exec\-charset=\fR\fIcharset\fR 4
.IX Item "-fwide-exec-charset=charset"
مجموعه کاراکترهای اجرایی عریض را که برای ثابت‌های رشته‌ای و کاراکتری عریض استفاده می‌شود، تنظیم می‌کند. مقدار پیش‌فرض یکی از UTF\-32BE، UTF\-32LE، UTF\-16BE یا UTF\-16LE است، بسته به اینکه کدام یک با عرض \f(CW\*(C`wchar_t\*(C'\fR و ترتیب بایت‌های بزرگ‌بایتی یا کوچک‌بایتی مورد استفاده برای تولید کد مطابقت داشته باشد. همانند \fB\-fexec\-charset\fR، مقدار \fIcharset\fR می‌تواند هر کدگذاری پشتیبانی‌شده توسط روال کتابخانه \f(CW\*(C`iconv\*(C'\fR سیستم باشد؛ با این حال، با کدگذاری‌هایی که دقیقاً در \f(CW\*(C`wchar_t\*(C'\fR جا نمی‌شوند دچار مشکل خواهید شد.
.IP \fB\-finput\-charset=\fR\fIcharset\fR 4
.IX Item "-finput-charset=charset"
مجموعه کاراکتر ورودی را تنظیم می‌کند که برای تبدیل از مجموعه کاراکتر پرونده ورودی به مجموعه کاراکتر منبع مورد استفاده توسط GCC به کار می‌رود. مقدار پیش‌فرض UTF\-8 است. \fIcharset\fR می‌تواند هر کدگذاری پشتیبانی‌شده توسط روال کتابخانه \f(CW\*(C`iconv\*(C'\fR سیستم باشد.
.Sp
اگر مجموعه کاراکتر ورودی UTF\-8 باشد و گزینه \fB\-Winvalid\-utf8\fR فعال باشد، هشدارهایی درباره دنباله‌های واحد کد ناقص صادر می‌شود. در غیر این صورت، در صورتی که مجموعه کاراکتر ورودی با مجموعه کاراکتر اجرایی مطابقت داشته باشد، هیچ پیام تشخیصی صادر نمی‌شود. اگر آن‌ها متفاوت باشند، دنباله‌های واحد کد ناقص در حین تبدیل کدگذاری به مجموعه کاراکتر اجرایی، منجر به خطا می‌شوند.
.IP \fB\-fworking\-directory\fR 4
.IX Item "-fworking-directory"
تولید نشانگرهای خط را در خروجی پیش‌پردازنده فعال می‌کند که به کامپایلر اجازه می‌دهد از پوشه کاری جاری در زمان پیش‌پردازش مطلع شود. هنگامی که این گزینه فعال است، پیش‌پردازنده پس از نشانگر خط اولیه، یک نشانگر خط دوم با پوشه کاری جاری که به دنبال آن دو اسلش قرار دارد صادر می‌کند. هنگامی که این پوشه در ورودی پیش‌پردازش‌شده وجود دارد، GCC از آن به عنوان پوشه‌ای استفاده می‌کند که در برخی قالب‌های اطلاعات اشکال‌زدایی به عنوان پوشه کاری جاری صادر می‌شود. اگر اطلاعات اشکال‌زدایی فعال باشد، این گزینه به‌طور ضمنی فعال است، اما می‌توان با شکل نفی‌شده \fB\-fno\-working\-directory\fR از آن جلوگیری کرد. اگر فلگ \fB\-P\fR در خط فرمان وجود داشته باشد، این گزینه هیچ اثری ندارد، زیرا هیچ دستورالعمل \&\f(CW\*(C`#line\*(C'\fR به هیچ وجه صادر نمی‌شود.
.IP "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4
.IX Item "-A predicate=answer"
.PD 0
.IP "\fB\-\-assert\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4
.IX Item "--assert predicate=answer"
.IP \fB\-\-assert=\fR\fIpredicate\fR\fB=\fR\fIanswer\fR 4
.IX Item "--assert=predicate=answer"
.PD
یک تصدیق با گزاره \fIpredicate\fR و پاسخ \&\fIanswer\fR ایجاد می‌کند. این شکل بر شکل قدیمی‌تر \fB\-A\fR \&\fIpredicate\fR\fB(\fR\fIanswer\fR\fB)\fR که همچنان پشتیبانی می‌شود ترجیح داده می‌شود، زیرا از کاراکترهای ویژه شل استفاده نمی‌کند.
.Sp
تصدیق‌ها یک ویژگی منسوخ‌شده در پیش‌پردازنده هستند که تنها برای سازگاری با هدرهای قدیمی سیستم در برخی اهداف پشتیبانی می‌شوند.
.IP "\fB\-A \-\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4
.IX Item "-A -predicate=answer"
.PD 0
.IP "\fB\-\-assert \-\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4
.IX Item "--assert -predicate=answer"
.IP \fB\-\-assert=\-\fR\fIpredicate\fR\fB=\fR\fIanswer\fR 4
.IX Item "--assert=-predicate=answer"
.PD
یک تصدیق را با گزاره \fIpredicate\fR و پاسخ \&\fIanswer\fR لغو می‌کند.
.IP \fB\-C\fR 4
.IX Item "-C"
.PD 0
.IP \fB\-\-comments\fR 4
.IX Item "--comments"
.PD
کامنت‌ها را دور نریزید. تمام کامنت‌ها به پرونده خروجی منتقل می‌شوند،
به‌جز کامنت‌های موجود در دایرکتیوهای پردازش‌شده که همراه با خود
دایرکتیو حذف می‌شوند.
.Sp
هنگام استفاده از \fB\-C\fR باید برای اثرات جانبی آماده باشید؛ این گزینه
باعث می‌شود پیش‌پردازنده با کامنت‌ها به عنوان نشانه‌ها (توکن‌ها)ی مستقل رفتار کند.
به عنوان مثال، کامنت‌هایی که در ابتدای خطی قرار می‌گیرند که می‌توانست یک خط
دایرکتیو باشد، موجب تبدیل آن خط به یک خط کد منبع معمولی می‌شوند،
زیرا اولین توکن روی خط دیگر \fB#\fR نیست.
.IP \fB\-CC\fR 4
.IX Item "-CC"
.PD 0
.IP \fB\-\-comments\-in\-macros\fR 4
.IX Item "--comments-in-macros"
.PD
کامنت‌ها را دور نریزید، از جمله در زمان بسط ماکرو. این گزینه مانند
\fB\-C\fR است، با این تفاوت که کامنت‌های درون ماکروها نیز در جایی که ماکرو
بسط داده می‌شود به پرونده خروجی منتقل می‌شوند.
.Sp
علاوه بر اثرات جانبی گزینه \fB\-C\fR، گزینه
\&\fB\-CC\fR باعث می‌شود تمام کامنت‌های سبک C++ درون یک ماکرو به کامنت‌های
سبک C تبدیل شوند. این کار برای جلوگیری از این است که استفاده‌های بعدی از آن ماکرو
به‌طور ناخواسته باقی‌مانده خط منبع را کامنت کند.
.Sp
گزینه \fB\-CC\fR معمولاً برای پشتیبانی از کامنت‌های lint استفاده می‌شود.
.IP \fB\-P\fR 4
.IX Item "-P"
.PD 0
.IP \fB\-\-no\-line\-commands\fR 4
.IX Item "--no-line-commands"
.PD
از ایجاد نشانگرهای خط (linemarkers) در خروجی پیش‌پردازنده جلوگیری می‌کند.
این قابلیت ممکن است هنگام اجرای پیش‌پردازنده روی متنی که کد C نیست و به برنامه‌ای
ارسال خواهد شد که ممکن است با نشانگرهای خط دچار سردرگمی شود، مفید باشد.
.IP \fB\-traditional\fR 4
.IX Item "-traditional"
.PD 0
.IP \fB\-\-traditional\fR 4
.IX Item "--traditional"
.IP \fB\-traditional\-cpp\fR 4
.IX Item "-traditional-cpp"
.IP \fB\-\-traditional\-cpp\fR 4
.IX Item "--traditional-cpp"
.PD
تلاش برای تقلید از رفتار پیش‌پردازنده‌های C پیش از استاندارد، در مقابل
پیش‌پردازنده‌های استاندارد ISO C.
.Sp
توجه داشته باشید که GCC در موارد دیگر تلاشی برای شبیه‌سازی کامپایلر C پیش از استاندارد
نمی‌کند، و این گزینه‌ها تنها با سوییچ \fB\-E\fR یا هنگام فراخوانی صریح CPP پشتیبانی می‌شوند.
.IP \fB\-trigraphs\fR 4
.IX Item "-trigraphs"
.PD 0
.IP \fB\-\-trigraphs\fR 4
.IX Item "--trigraphs"
.PD
پشتیبانی از سه‌نگاره‌های (trigraphs) استاندارد ISO C.
این‌ها توالی‌های سه‌کاراکتری هستند که همگی با \fB??\fR آغاز می‌شوند و توسط ISO C
برای نمایش کاراکترهای تکی تعریف شده‌اند. به عنوان مثال،
\&\fB??/\fR بیانگر \fB\e\fR است، بنابراین \fB\*(Aq??/n\*(Aq\fR یک ثابت
کاراکتری برای خط جدید (newline) است.
.Sp
به‌طور پیش‌فرض، GCC سه‌نگاره‌ها را نادیده می‌گیرد، اما در حالت‌های منطبق با استاندارد
آن‌ها را تبدیل می‌کند. گزینه‌های \fB\-std\fR و
\&\fB\-ansi\fR را ببینید.
.IP \fB\-remap\fR 4
.IX Item "-remap"
کد ویژه‌ای را برای دور زدن محدودیت‌های سیستم‌های پرونده‌ای که فقط نام‌های بسیار
کوتاه برای پرونده‌ها را مجاز می‌دانند (مانند MS\-DOS)، فعال می‌کند.
.IP \fB\-H\fR 4
.IX Item "-H"
.PD 0
.IP \fB\-\-trace\-includes\fR 4
.IX Item "--trace-includes"
.PD
نام هر پرونده هدر استفاده‌شده را علاوه بر سایر فعالیت‌های عادی چاپ می‌کند. هر نام
با تورفتگی نمایش داده می‌شود تا نشان دهد در چه عمقی از پشته
\&\fB#include\fR قرار دارد. پرونده‌های هدر پیش‌کامپایل‌شده نیز چاپ می‌شوند،
حتی اگر نامعتبر تشخیص داده شوند؛ یک پرونده هدر پیش‌کامپایل‌شده نامعتبر با \fB...x\fR و
یک پرونده معتبر با \fB...!\fR چاپ می‌شود.
.IP \fB\-d\fR\fIletters\fR 4
.IX Item "-dletters"
.PD 0
.IP \fB\-\-dump=\fR\fIletters\fR 4
.IX Item "--dump=letters"
.IP "\fB\-\-dump\fR \fIletters\fR" 4
.IX Item "--dump letters"
.PD
دستور می‌دهد تا در طول کامپایل، دامپ‌های اشکال‌زدایی طبق آنچه در
\&\fIletters\fR مشخص شده ایجاد شوند. فلگ‌های مستندشده در اینجا مواردی هستند که به
پیش‌پردازنده مربوط می‌شوند. سایر \fIletters\fR توسط خود کامپایلر تفسیر می‌شوند یا برای
نسخه‌های آینده GCC رزرو شده‌اند، و بنابراین بدون اخطار نادیده گرفته می‌شوند. اگر
\&\fIletters\fR را به گونه‌ای مشخص کنید که رفتار آن‌ها در تضاد باشد، نتیجه تعریف‌نشده خواهد بود.
.RS 4
.IP \fB\-dM\fR 4
.IX Item "-dM"
.PD 0
.IP \fB\-\-dump=M\fR 4
.IX Item "--dump=M"
.PD
به‌جای خروجی عادی، فهرستی از دایرکتیوهای \fB#define\fR را برای تمامی ماکروهای
تعریف‌شده در حین اجرای پیش‌پردازنده، از جمله ماکروهای پیش‌تعریف‌شده تولید می‌کند. این به
شما راهی برای پی بردن به این که چه چیزهایی در نسخه پیش‌پردازنده شما از پیش تعریف شده‌اند می‌دهد.
با فرض اینکه پرونده‌ای به نام \fIfoo.h\fR ندارید، دستور
.Sp
.Vb 1
\&        touch foo.h; cpp \-dM foo.h
.Ve
.Sp
تمامی ماکروهای از پیش تعریف‌شده را نمایش می‌دهد.
.IP \fB\-dD\fR 4
.IX Item "-dD"
.PD 0
.IP \fB\-\-dump=D\fR 4
.IX Item "--dump=D"
.PD
مانند \fB\-dM\fR است، با این تفاوت که \fIهر دو\fR دایرکتیوهای \fB#define\fR و
نتیجه پیش‌پردازش را خروجی می‌دهد. هر دو نوع خروجی به پرونده خروجی استاندارد
ارسال می‌شوند.
.IP \fB\-dN\fR 4
.IX Item "-dN"
.PD 0
.IP \fB\-\-dump=N\fR 4
.IX Item "--dump=N"
.PD
مانند \fB\-dD\fR است، اما تنها نام ماکروها را صادر می‌کند، نه بسط آن‌ها را.
.IP \fB\-dI\fR 4
.IX Item "-dI"
.PD 0
.IP \fB\-\-dump=I\fR 4
.IX Item "--dump=I"
.PD
علاوه بر نتیجه پیش‌پردازش، دایرکتیوهای \fB#include\fR را نیز در خروجی قرار می‌دهد.
.IP \fB\-dU\fR 4
.IX Item "-dU"
.PD 0
.IP \fB\-\-dump=U\fR 4
.IX Item "--dump=U"
.PD
مانند \fB\-dD\fR است با این تفاوت که تنها ماکروهایی که بسط داده می‌شوند، یا تعریف‌شدن
آن‌ها در دایرکتیوهای پیش‌پردازنده بررسی می‌شود، در خروجی قرار می‌گیرند؛ خروجی تا زمان
استفاده یا آزمودن ماکرو به تاخیر می‌افتد؛ و دایرکتیوهای \fB#undef\fR نیز برای ماکروهایی که
بررسی شده‌اند اما در آن زمان تعریف‌نشده بودند، خروجی داده می‌شوند.
.RE
.RS 4
.RE
.IP \fB\-fdebug\-cpp\fR 4
.IX Item "-fdebug-cpp"
این گزینه تنها برای اشکال‌زدایی GCC مفید است. هنگامی که از CPP یا همراه با
\&\fB\-E\fR استفاده شود، اطلاعات اشکال‌زدایی مربوط به نقشه‌های موقعیت (location maps) را
دامپ می‌کند. هر توکن در خروجی با دامپ نقشه‌ای که مکانش به آن تعلق دارد، مقدم می‌شود.
.Sp
هنگامی که از GCC بدون \fB\-E\fR استفاده شود، این گزینه هیچ اثری ندارد.
.IP "\fB\-I\fR \fIdir\fR" 4
.IX Item "-I dir"
.PD 0
.IP "\fB\-iquote\fR \fIdir\fR" 4
.IX Item "-iquote dir"
.IP "\fB\-isystem\fR \fIdir\fR" 4
.IX Item "-isystem dir"
.IP "\fB\-idirafter\fR \fIdir\fR" 4
.IX Item "-idirafter dir"
.IP \fB\-\-include\-directory\-after=\fR\fIdir\fR 4
.IX Item "--include-directory-after=dir"
.IP "\fB\-\-include\-directory\-after\fR \fIdir\fR" 4
.IX Item "--include-directory-after dir"
.IP \fB\-\-include\-directory=\fR\fIdir\fR 4
.IX Item "--include-directory=dir"
.IP "\fB\-\-include\-directory\fR \fIdir\fR" 4
.IX Item "--include-directory dir"
.PD
دایرکتوری \fIdir\fR را به فهرست پوشه‌های مورد جستجو برای پرونده‌های هدر در حین پیش‌پردازش اضافه می‌کند.
\&\fB\-\-include\-directory\fR یک نام مستعار برای \fB\-I\fR است، در حالی که
\&\fB\-\-include\-directory\-after\fR نام مستعاری برای \fB\-idirafter\fR است.
.Sp
اگر \fIdir\fR با \fB=\fR یا \f(CW$SYSROOT\fR آغاز شود، آن‌گاه \fB=\fR
یا \f(CW$SYSROOT\fR با پیشوند sysroot جایگزین می‌شود؛ گزینه‌های
\&\fB\-\-sysroot\fR و \fB\-isysroot\fR را ببینید.
.Sp
پوشه‌های مشخص‌شده با \fB\-iquote\fR تنها برای شکل نقل‌قولی (گیومه)
دایرکتیو اعمال می‌شوند: \f(CW\*(C`#include\ "\fR\f(CIfile\fR\f(CW"\*(C'\fR.
پوشه‌های مشخص‌شده با \fB\-I\fR، \fB\-isystem\fR
یا \fB\-idirafter\fR برای جستجوی هر دو دایرکتیو
\&\f(CW\*(C`#include\ "\fR\f(CIfile\fR\f(CW"\*(C'\fR و
\&\f(CW\*(C`#include\ <\fR\f(CIfile\fR\f(CW>\*(C'\fR اعمال می‌شوند.
.Sp
می‌توانید هر تعداد یا ترکیبی از این گزینه‌ها را در خط فرمان برای جستجوی پرونده‌های هدر
در چندین دایرکتوری مشخص کنید. ترتیب جستجو به شرح زیر است:
.RS 4
.IP 1. 4
.IX Item "1."
برای شکل نقل‌قولی دایرکتیو include، ابتدا دایرکتوری پرونده فعلی جستجو می‌شود.
.IP 2. 4
.IX Item "2."
برای شکل نقل‌قولی دایرکتیو include، پوشه‌های مشخص‌شده با گزینه‌های \fB\-iquote\fR به
ترتیب از چپ به راست، همان‌گونه که در خط فرمان آمده‌اند، جستجو می‌شوند.
.IP 3. 4
.IX Item "3."
پوشه‌های مشخص‌شده با گزینه‌های \fB\-I\fR به ترتیب از چپ به راست بررسی می‌شوند.
.IP 4. 4
.IX Item "4."
پوشه‌های مشخص‌شده با گزینه‌های \fB\-isystem\fR به ترتیب از چپ به راست بررسی می‌شوند.
.IP 5. 4
.IX Item "5."
دایرکتوری‌های استاندارد سیستم بررسی می‌شوند.
.IP 6. 4
.IX Item "6."
پوشه‌های مشخص‌شده با گزینه‌های \fB\-idirafter\fR به ترتیب از چپ به راست بررسی می‌شوند.
.RE
.RS 4
.Sp
شما می‌توانید از \fB\-I\fR برای بازنویسی و جایگزینی یک پرونده هدر سیستم با نسخه خودتان
استفاده کنید، چرا که این دایرکتوری‌ها پیش از پوشه‌های پرونده‌های هدر استاندارد سیستم
جستجو می‌شوند. با این حال، نباید از این گزینه برای افزودن پوشه‌های حاوی پرونده‌های هدر سیستمی
ارائه‌شده توسط سازنده (vendor) استفاده کنید؛ برای این منظور از \fB\-isystem\fR استفاده نمایید.
.Sp
گزینه‌های \fB\-isystem\fR و \fB\-idirafter\fR همچنین پوشه را به عنوان دایرکتوری سیستم علامت‌گذاری
می‌کنند، به طوری که همان رفتار ویژه‌ای که برای پوشه‌های استاندارد سیستم اعمال می‌شود برای آن نیز لحاظ گردد.
.Sp
اگر یک دایرکتوری استاندارد include سیستم یا پوشه‌ای که با \fB\-isystem\fR مشخص شده، با
\&\fB\-I\fR نیز مشخص گردد، گزینه \fB\-I\fR نادیده گرفته می‌شود. دایرکتوری همچنان جستجو خواهد شد،
اما به عنوان یک پوشه سیستم در جایگاه عادی خود در زنجیره include سیستم.
این کار برای اطمینان از این است که سازوکار GCC برای اصلاح هدرهای معیوب سیستم و
ترتیب دایرکتیو \f(CW\*(C`#include_next\*(C'\fR به‌طور ناخواسته تغییر نکند.
اگر واقعاً نیاز به تغییر ترتیب جستجوی پوشه‌های سیستم دارید، از گزینه‌های \fB\-nostdinc\fR یا
\&\fB\-isystem\fR استفاده کنید.
.RE
.IP \fB\-I\-\fR 4
.IX Item "-I-"
.PD 0
.IP \fB\-\-include\-barrier\fR 4
.IX Item "--include-barrier"
.PD
مسیر include را تقسیم می‌کند.
این گزینه منسوخ شده است. لطفاً به‌جای آن برای پوشه‌های \fB\-I\fR قبل از
\&\fB\-I\-\fR از \fB\-iquote\fR استفاده کرده و گزینه \fB\-I\-\fR را حذف کنید.
.Sp
هر پوشه‌ای که با گزینه‌های \fB\-I\fR پیش از \fB\-I\-\fR مشخص شده باشد، تنها برای
هدرهای درخواست‌شده با \f(CW\*(C`#include\ "\fR\f(CIfile\fR\f(CW"\*(C'\fR جستجو می‌شود؛
آن‌ها برای \f(CW\*(C`#include\ <\fR\f(CIfile\fR\f(CW>\*(C'\fR جستجو نمی‌شوند. اگر پوشه‌های اضافی
با گزینه‌های \fB\-I\fR پس از \fB\-I\-\fR مشخص شوند، آن پوشه‌ها برای تمامی دایرکتیوهای
\&\fB#include\fR جستجو می‌شوند.
.Sp
علاوه بر این، \fB\-I\-\fR از استفاده از دایرکتوری پرونده فعلی به عنوان نخستین پوشه جستجو برای
\&\f(CW\*(C`#include\ "\fR\f(CIfile\fR\f(CW"\*(C'\fR جلوگیری می‌کند. هیچ راهی برای بی‌اثر کردن این ویژگی
\&\fB\-I\-\fR وجود ندارد.
.IP "\fB\-iprefix\fR \fIprefix\fR" 4
.IX Item "-iprefix prefix"
.PD 0
.IP \fB\-\-include\-prefix=\fR\fIprefix\fR 4
.IX Item "--include-prefix=prefix"
.IP "\fB\-\-include\-prefix\fR \fIprefix\fR" 4
.IX Item "--include-prefix prefix"
.PD
مقدار \fIprefix\fR را به‌عنوان پیشوند برای گزینه‌های بعدی \fB\-iwithprefix\fR
مشخص می‌کند. اگر پیشوند نشان‌دهنده یک پوشه باشد، باید
\fB/\fR پایانی را نیز قرار دهید.
.IP "\fB\-iwithprefix\fR \fIdir\fR" 4
.IX Item "-iwithprefix dir"
.PD 0
.IP "\fB\-iwithprefixbefore\fR \fIdir\fR" 4
.IX Item "-iwithprefixbefore dir"
.IP \fB\-\-include\-with\-prefix=\fR\fIprefix\fR 4
.IX Item "--include-with-prefix=prefix"
.IP "\fB\-\-include\-with\-prefix\fR \fIprefix\fR" 4
.IX Item "--include-with-prefix prefix"
.IP \fB\-\-include\-with\-prefix\-after=\fR\fIprefix\fR 4
.IX Item "--include-with-prefix-after=prefix"
.IP "\fB\-\-include\-with\-prefix\-after\fR \fIprefix\fR" 4
.IX Item "--include-with-prefix-after prefix"
.IP \fB\-\-include\-with\-prefix\-before=\fR\fIprefix\fR 4
.IX Item "--include-with-prefix-before=prefix"
.IP "\fB\-\-include\-with\-prefix\-before\fR \fIprefix\fR" 4
.IX Item "--include-with-prefix-before prefix"
.PD
مقدار \fIdir\fR را به پیشوندی که پیش‌تر با
\&\fB\-iprefix\fR مشخص شده اضافه می‌کند و پوشه حاصل را به مسیر جستجوی include
می‌افزاید. \fB\-iwithprefixbefore\fR آن را در همان جایی قرار می‌دهد که \fB\-I\fR
قرار می‌داد؛ \fB\-iwithprefix\fR آن را در جایی قرار می‌دهد که \fB\-idirafter\fR قرار می‌داد.
.Sp
\&\fB\-\-include\-with\-prefix\fR و \fB\-\-include\-with\-prefix\-after\fR هر دو
نام‌های مستعاری برای \fB\-iwithprefix\fR هستند، در حالی که
\&\fB\-\-include\-with\-prefix\-before\fR نام مستعاری برای
\&\fB\-iwithprefixbefore\fR است.
.IP "\fB\-isysroot\fR \fIdir\fR" 4
.IX Item "-isysroot dir"
این گزینه مانند گزینه \fB\-\-sysroot\fR است، اما تنها برای
فایل‌های هدر اعمال می‌شود (به جز برای مقصدهای Darwin که در آن‌ها هم برای فایل‌های
هدر و هم کتابخانه‌ها اعمال می‌گردد). برای اطلاعات بیشتر گزینه \fB\-\-sysroot\fR را
ببینید.
.IP "\fB\-imultilib\fR \fIdir\fR" 4
.IX Item "-imultilib dir"
از \fIdir\fR به‌عنوان یک زیرپوشه از دایرکتوری حاوی
هدرهای C++ مختص مقصد استفاده می‌کند.
.IP "\fB\-imultiarch\fR \fIdir\fR" 4
.IX Item "-imultiarch dir"
از \fIdir\fR به‌عنوان یک زیرپوشه از دایرکتوری حاوی
هدرهای C++ مختص معماری استفاده می‌کند.
.IP \fB\-nostdinc\fR 4
.IX Item "-nostdinc"
.PD 0
.IP \fB\-\-no\-standard\-includes\fR 4
.IX Item "--no-standard-includes"
.PD
دایرکتوری‌های استاندارد سیستم را برای یافتن فایل‌های هدر جستجو نمی‌کند.
تنها دایرکتوری‌هایی که صراحتاً با گزینه‌های \fB\-I\fR،
\&\fB\-iquote\fR، \fB\-isystem\fR و/یا \fB\-idirafter\fR
مشخص شده‌اند (و دایرکتوری فایل فعلی، در صورت مناسب بودن)
جستجو می‌شوند.
.IP \fB\-nostdinc++\fR 4
.IX Item "-nostdinc++"
فایل‌های هدر را در دایرکتوری‌های استاندارد اختصاصی C++ جستجو نمی‌کند،
اما سایر دایرکتوری‌های استاندارد را همچنان جستجو می‌کند. (این گزینه
هنگام ساخت کتابخانه C++ استفاده می‌شود.)
.IP \fB\-\-embed\-dir=\fR\fIdir\fR 4
.IX Item "--embed-dir=dir"
.PD 0
.IP \fB\-\-embed\-directory=\fR\fIdir\fR 4
.IX Item "--embed-directory=dir"
.IP "\fB\-\-embed\-directory\fR \fIdir\fR" 4
.IX Item "--embed-directory dir"
.PD
پوشه \fIdir\fR را به فهرست پوشه‌های مورد جستجو برای
دستور پیش‌پردازنده \f(CW\*(C`#embed\*(C'\fR یا ماکروی \f(CW\*(C`_\|_has_embed\*(C'\fR اضافه می‌کند.
هیچ پوشه پیش‌فرضی برای \f(CW\*(C`#embed\*(C'\fR وجود ندارد.
.Sp
اگر \fIdir\fR با \fB=\fR یا \f(CW$SYSROOT\fR آغاز شود، آنگاه \fB=\fR
یا \f(CW$SYSROOT\fR با پیشوند sysroot جایگزین می‌شود؛ گزینه‌های
\&\fB\-\-sysroot\fR و \fB\-isysroot\fR را ببینید.
.IP \fB\-Wcomment\fR 4
.IX Item "-Wcomment"
.PD 0
.IP \fB\-Wcomments\fR 4
.IX Item "-Wcomments"
.PD
هر زمان که یک توالی شروع توضیح \fB/*\fR در یک توضیح \fB/*\fR
ظاهر شود، یا هر زمان که یک بک‌اسلش-خط‌جدید در یک توضیح \fB//\fR ظاهر شود، هشدار می‌دهد.
این هشدار با \fB\-Wall\fR فعال می‌شود.
.IP \fB\-Wtrigraphs\fR 4
.IX Item "-Wtrigraphs"
در صورت برخورد با هرگونه سه‌نویسه‌ای (trigraph) که ممکن است معنای
برنامه را تغییر دهد هشدار می‌دهد. در مورد سه‌نویسه‌های درون توضیحات هشداری داده نمی‌شود،
مگر مواردی که یک خط جدید اسکیپ‌شده تشکیل دهند.
.Sp
این گزینه به‌طور ضمنی توسط \fB\-Wall\fR فعال می‌شود. اگر \fB\-Wall\fR
داده نشده باشد، این گزینه همچنان فعال است مگر اینکه سه‌نویسه‌ها فعال شده باشند. برای
به‌دست آوردن تبدیل سه‌نویسه‌ها بدون هشدار، اما دریافت سایر
هشدارهای \fB\-Wall\fR، از \fB\-trigraphs \-Wall \-Wno\-trigraphs\fR استفاده کنید.
.IP \fB\-Wundef\fR 4
.IX Item "-Wundef"
اگر یک شناسه تعریف‌نشده در یک دستور \f(CW\*(C`#if\*(C'\fR ارزیابی شود هشدار می‌دهد.
چنین شناسه‌هایی با صفر جایگزین می‌شوند.
.IP \fB\-Wexpansion\-to\-defined\fR 4
.IX Item "-Wexpansion-to-defined"
هر زمان که \fBdefined\fR در بسط یا بازشدن یک ماکرو دیده شود
(از جمله حالتی که ماکرو توسط یک دستور \fB#if\fR باز می‌شود) هشدار می‌دهد.
چنین کاربردی قابل حمل نیست.
این هشدار همچنین با \fB\-Wpedantic\fR و \fB\-Wextra\fR فعال می‌شود.
.IP \fB\-Wunused\-macros\fR 4
.IX Item "-Wunused-macros"
درباره ماکروهای تعریف‌شده در فایل اصلی که استفاده نشده‌اند هشدار می‌دهد. یک ماکرو
در صورتی \fIاستفاده‌شده\fR است که حداقل یک بار باز شود یا وجود آن بررسی شده باشد.
پیش‌پردازنده همچنین اگر ماکرو در زمان بازتعریف یا حذف تعریف (undefine)
استفاده نشده باشد، هشدار می‌دهد.
.Sp
در مورد ماکروهای توکار، ماکروهای تعریف‌شده در خط فرمان و ماکروهای
تعریف‌شده در فایل‌های include هشداری داده نمی‌شود.
.Sp
\&\fIنکته:\fR اگر ماکرویی در عمل استفاده شود، اما تنها در بلوک‌های شرطی
نادیده‌گرفته‌شده به کار رفته باشد، پیش‌پردازنده آن را به‌عنوان استفاده‌نشده گزارش می‌کند. برای جلوگیری از
هشدار در چنین شرایطی، می‌توانید دامنه تعریف ماکرو را بهبود ببخشید،
برای مثال با انتقال آن به اولین بلوک نادیده‌گرفته‌شده.
همچنین، می‌توانید با چیزی شبیه به عبارت زیر یک استفاده صوری برای آن فراهم کنید:
.Sp
.Vb 2
\&        #if defined the_macro_causing_the_warning
\&        #endif
.Ve
.IP \fB\-Wno\-endif\-labels\fR 4
.IX Item "-Wno-endif-labels"
هر زمان که به دنبال یک \f(CW\*(C`#else\*(C'\fR یا \f(CW\*(C`#endif\*(C'\fR متنی بیاید هشدار نمی‌دهد.
این حالت گاهی در برنامه‌های قدیمی‌تر با کدهایی به شکل زیر رخ می‌دهد:
.Sp
.Vb 5
\&        #if FOO
\&        ...
\&        #else FOO
\&        ...
\&        #endif FOO
.Ve
.Sp
دومین و سومین \f(CW\*(C`FOO\*(C'\fR باید درون توضیحات (کامنت‌ها) قرار گیرند.
این هشدار به‌طور پیش‌فرض روشن است.
.SH "محیط (ENVIRONMENT)"
.IX Header "ENVIRONMENT"
این بخش متغیرهای محیطی را شرح می‌دهد که بر نحوه عملکرد CPP
تأثیر می‌گذارند. می‌توانید از آن‌ها برای تعیین دایرکتوری‌ها یا پیشوندهایی که
هنگام جستجوی فایل‌های include به کار می‌روند، یا برای کنترل خروجی وابستگی‌ها استفاده کنید.
.PP
توجه داشته باشید که می‌توانید مکان‌های جستجو را با گزینه‌هایی مانند
\&\fB\-I\fR نیز تعیین کنید و خروجی وابستگی‌ها را با گزینه‌هایی مانند
\&\fB\-M\fR کنترل نمایید. این گزینه‌ها بر
متغیرهای محیطی اولویت دارند و متغیرهای محیطی نیز به نوبه خود بر
پیکربندی GCC تقدم دارند.
.IP \fBCPATH\fR 4
.IX Item "CPATH"
.PD 0
.IP \fBC_INCLUDE_PATH\fR 4
.IX Item "C_INCLUDE_PATH"
.IP \fBCPLUS_INCLUDE_PATH\fR 4
.IX Item "CPLUS_INCLUDE_PATH"
.IP \fBOBJC_INCLUDE_PATH\fR 4
.IX Item "OBJC_INCLUDE_PATH"
.PD
مقدار هر متغیر فهرستی از دایرکتوری‌ها است که با یک کاراکتر ویژه،
بسیار شبیه به \fBPATH\fR، از هم جدا شده‌اند و در آن‌ها به دنبال فایل‌های هدر گشته می‌شود.
کاراکتر ویژه، یعنی \f(CW\*(C`PATH_SEPARATOR\*(C'\fR، به معماری مقصد وابسته بوده و
در زمان ساخت GCC تعیین می‌شود. برای مقصدهای مبتنی بر Microsoft Windows این کاراکتر
نقطه-ویرگول (semicolon) و برای تقریباً تمامی دیگر مقصدها دونقطه (colon) است.
.Sp
متغیر محیطی \&\fBCPATH\fR فهرستی از دایرکتوری‌ها را مشخص می‌کند تا جستجو شوند طوری که گویی
با \fB\-I\fR مشخص شده‌اند، اما پس از هر مسیری که با گزینه‌های \fB\-I\fR
در خط فرمان داده شده باشد. این متغیر محیطی بدون توجه به زبانی که
پیش‌پردازش می‌شود مورد استفاده قرار می‌گیرد.
.Sp
باقی متغیرهای محیطی تنها هنگام پیش‌پردازش زبان خاص مشخص‌شده
اعمال می‌شوند. هر یک فهرستی از دایرکتوری‌ها را مشخص می‌کند تا طوری جستجو شوند
که گویی با \fB\-isystem\fR تعیین شده‌اند، اما پس از هر مسیری که
با گزینه‌های \fB\-isystem\fR در خط فرمان ارائه شده است.
.Sp
در تمامی این متغیرها، یک عنصر خالی به کامپایلر دستور می‌دهد که
دایرکتوری کاری فعلی خود را جستجو کند. عناصر خالی می‌توانند در
آغاز یا پایان یک مسیر ظاهر شوند. برای نمونه، اگر مقدار
\&\fBCPATH\fR برابر با \f(CW\*(C`:/special/include\*(C'\fR باشد، اثری یکسان با
\&\fB\-I.\ \-I/special/include\fR خواهد داشت.
.IP \fBDEPENDENCIES_OUTPUT\fR 4
.IX Item "DEPENDENCIES_OUTPUT"
اگر این متغیر تنظیم شده باشد، مقدار آن نحوه خروجی دادن
وابستگی‌ها برای Make را بر اساس فایل‌های هدر غیرسیستمی پردازش‌شده
توسط کامپایلر مشخص می‌کند. فایل‌های هدر سیستمی در خروجی وابستگی‌ها
نادیده گرفته می‌شوند.
.Sp
مقدار \fBDEPENDENCIES_OUTPUT\fR می‌تواند صرفاً نام یک فایل باشد، که
در این صورت قواعد Make در آن فایل نوشته می‌شوند و نام هدف از
روی نام فایل مبدأ حدس زده می‌شود. یا این مقدار می‌تواند به شکل
\&\fIfile\fR\fB \fR\fItarget\fR باشد، که در این حالت قواعد در فایل
\&\fIfile\fR با استفاده از \fItarget\fR به‌عنوان نام هدف نوشته می‌شوند.
.Sp
به عبارت دیگر، این متغیر محیطی معادل ترکیب
گزینه‌های \fB\-MM\fR و \fB\-MF\fR است،
همراه با یک سوییچ اختیاری \fB\-MT\fR.
.IP \fBSUNPRO_DEPENDENCIES\fR 4
.IX Item "SUNPRO_DEPENDENCIES"
این متغیر مشابه \fBDEPENDENCIES_OUTPUT\fR است (بالا را ببینید)،
با این تفاوت که فایل‌های هدر سیستمی نادیده گرفته نمی‌شوند، بنابراین
به جای \fB\-MM\fR بر \fB\-M\fR دلالت دارد. با این حال، وابستگی به
فایل ورودی اصلی نادیده گرفته می‌شود.
.IP \fBSOURCE_DATE_EPOCH\fR 4
.IX Item "SOURCE_DATE_EPOCH"
اگر این متغیر تنظیم شده باشد، مقدار آن یک برچسب زمانی یونیکس (UNIX timestamp) را مشخص می‌کند تا
به جای تاریخ و زمان فعلی در ماکروهای \f(CW\*(C`_\|_DATE_\|_\*(C'\fR
و \f(CW\*(C`_\|_TIME_\|_\*(C'\fR استفاده شود، تا بدین ترتیب برچسب‌های زمانی تعبیه‌شده
تکرارپذیر (reproducible) شوند.
.Sp
مقدار \fBSOURCE_DATE_EPOCH\fR باید یک برچسب زمانی یونیکس باشد،
که به‌صورت تعداد ثانیه‌ها (به استثنای ثانیه‌های کبیسه) از
01 Jan 1970 00:00:00 نمایش‌یافته در قالب ASCII تعریف می‌شود؛ یکسان با خروجی
\&\f(CW\*(C`date +%s\*(C'\fR در گنو/لینوکس و سایر سیستم‌هایی که از
پسوند \f(CW%s\fR در دستور \f(CW\*(C`date\*(C'\fR پشتیبانی می‌کنند.
.Sp
این مقدار باید یک برچسب زمانی شناخته‌شده باشد مانند آخرین زمان تغییر
مبدأ یا بسته، و باید توسط فرآیند ساخت تنظیم شود.
.SH "همچنین ببینید (SEE ALSO)"
.IX Header "SEE ALSO"
\&\fBgpl\fR\|(7)، \fBgfdl\fR\|(7)، \fBfsf\-funding\fR\|(7)،
\&\fBgcc\fR\|(1)، و مدخل‌های Info برای \fIcpp\fR و \fIgcc\fR.
.SH "کپی‌رایت (COPYRIGHT)"
.IX Header "COPYRIGHT"
حق نشر (c) ۱۹۸۷\-۲۰۲۶ بنیاد نرم‌افزارهای آزاد (Free Software Foundation, Inc.)
.PP
اجازه کپی، توزیع و/یا تغییر این سند تحت شرایط مجوز
مستندات آزاد گنو (GNU Free Documentation License)، نسخه ۱.۳ یا
هر نسخه جدیدتر منتشر شده توسط بنیاد نرم‌افزارهای آزاد داده می‌شود. نسخه‌ای از
مجوز در صفحه راهنمای \fBgfdl\fR\|(7) گنجانده شده است.
این راهنما فاقد بخش‌های ناوردا (Invariant Sections) است. متون روی جلد
(a) (پایین را ببینید) و متون پشت جلد (b) (پایین را ببینید) هستند.
.PP
(a) متن روی جلد FSF عبارت است از:
.PP
.Vb 1
\&     A GNU Manual
.Ve
.PP
(b) متن پشت جلد FSF عبارت است از:
.PP
.Vb 3
\&     You have freedom to copy and modify this GNU Manual, like GNU
\&     software.  Copies published by the Free Software Foundation raise
\&     funds for GNU development.
.Ve