CPP(1) GNU CPP(1)

cpp - پیش‌پردازنده C

cpp [-Dmacro[=defn]...] [-Umacro]
[-Idir...] [-iquotedir...]
[-M|-MM] [-MG] [-MF filename]
[-MP] [-MQ target...]
[-MT target...]
infile [[-o] outfile]

تنها کاربردی‌ترین گزینه‌ها در بالا آورده شده‌اند؛ برای فهرست کامل‌تری از گزینه‌های ویژهٔ پیش‌پردازنده، بخش‌های پایین‌تر را ببینید. علاوه بر این، cpp اکثر گزینه‌های گردانندهٔ gcc را نیز می‌پذیرد که در اینجا فهرست نشده‌اند. برای جزئیات به مستندات GCC مراجعه کنید.

پیش‌پردازندهٔ C که اغلب با نام cpp شناخته می‌شود، یک پردازندهٔ ماکرو است که به صورت خودکار توسط کامپایلر C برای تبدیل و آماده‌سازی برنامهٔ شما پیش از کامپایل به کار می‌رود. این ابزار پردازندهٔ ماکرو نامیده می‌شود چرا که به شما امکان تعریف ماکروها را می‌دهد؛ ماکروهایی که اختصاراتی کوتاه برای ساختارهای طولانی‌تر هستند.

پیش‌پردازندهٔ C تنها برای استفاده با کدهای منبع C، C++‎ و Objective-C در نظر گرفته شده است. در گذشته، از آن به عنوان یک پردازندهٔ متن عمومی سوءاستفاده می‌شد. این ابزار در مواجهه با ورودی‌هایی که از قواعد واژگانی C پیروی نمی‌کنند متوقف شده و به خطا برمی‌خورد. برای نمونه، آپوستروف‌ها به عنوان آغاز ثابت‌های نویسه‌ای تفسیر شده و موجب بروز خطا می‌شوند. همچنین، نمی‌توانید برای حفظ ویژگی‌هایی از ورودی که برای زبان‌های خانوادهٔ C اهمیتی ندارند به آن اتکا کنید. اگر یک Makefile پیش‌پردازش شود، تمام فاصله‌های تب سخت (hard tabs) حذف خواهند شد و در نتیجه Makefile کار نخواهد کرد.

با این وجود، در بسیاری از موارد می‌توانید از cpp برای مواردی غیر از C نیز نتیجه بگیرید. سایر زبان‌های برنامه‌نویسی شبه‌الگول (مانند Ada و غیره) معمولاً ایمن هستند. زبان اسمبلی نیز با رعایت احتیاط قابل استفاده است. حالت -traditional-cpp فاصله‌های خالی بیشتری را حفظ کرده و در کل آسان‌گیرتر است. با نوشتن توضیحات (کامنت‌های) سبک C یا C++ به‌جای توضیحات بومی آن زبان، و همچنین ساده نگه داشتن ماکروها، می‌توان از بروز بسیاری از مشکلات جلوگیری کرد.

تا حد امکان، باید از پیش‌پردازنده‌ای استفاده کنید که متناسب با همان زبان برنامه‌نویسی شما طراحی شده باشد. نسخه‌های جدیدتر اسمبلی گنو (GNU assembler) از امکانات ماکرو برخوردارند. اکثر زبان‌های برنامه‌نویسی سطح بالا سازوکار اختصاصی خود را برای کامپایل شرطی و گنجاندن فایل‌ها دارند. اگر هیچ‌یک از این روش‌ها پاسخگو نبود، از یک پردازندهٔ متن واقعاً عمومی مانند GNU M4 استفاده کنید.

پیش‌پردازنده‌های C در برخی جزئیات با یکدیگر تفاوت دارند. این راهنما به پیش‌پردازندهٔ GNU C می‌پردازد که یک ابرمجموعهٔ کوچک از ویژگی‌های استاندارد ISO C را ارائه می‌دهد. در حالت پیش‌فرض، پیش‌پردازندهٔ GNU C چند موردی را که توسط استاندارد الزامی شده است انجام نمی‌دهد. این‌ها ویژگی‌هایی هستند که به ندرت، یا شاید هرگز، استفاده نمی‌شوند و ممکن است تغییرات غیرمنتظره‌ای در معنای برنامه‌ای که انتظار آن‌ها را ندارد ایجاد کنند. برای انطباق دقیق با استاندارد ISO C، باید بسته به نسخهٔ استانداردی که مد نظر دارید، از گزینه‌های -std=c90، -std=c99، -std=c11 یا -std=c17 استفاده کنید. برای دریافت تمام پیام‌های تشخیصی و هشدارهای الزامی، باید گزینهٔ -pedantic را نیز به کار ببرید.

این راهنما رفتار پیش‌پردازندهٔ ISO را تشریح می‌کند. برای به حداقل رساندن تفاوت‌های بی‌مورد، در جاهایی که رفتار پیش‌پردازندهٔ ISO با معناشناسی سنتی تعارضی ندارد، پیش‌پردازندهٔ سنتی نیز به همان شیوه رفتار می‌کند. تفاوت‌های گوناگون موجود در بخش Traditional Mode با جزئیات بیان شده‌اند.

جهت شفافیت، مگر در مواردی که خلاف آن ذکر شده باشد، هر جا در این راهنما به CPP اشاره شده منظور GNU CPP است..SH "گزینه‌ها (OPTIONS)" دستور cpp دو نام فایل را به عنوان آرگومان می‌پذیرد: infile و outfile. پیش‌پردازنده infile را همراه با هر فایل دیگری که با #include مشخص شده باشد می‌خواند. تمام خروجی تولیدشده توسط فایل‌های ورودی ترکیب‌شده در outfile نوشته می‌شود.

هر یک از infile یا outfile می‌تواند - باشد، که به عنوان infile به معنای خواندن از ورودی استاندارد و به عنوان outfile به معنای نوشتن در خروجی استاندارد است. اگر هر یک از فایل‌ها حذف شود، معادل آن است که برای آن فایل - مشخص شده باشد. همچنین می‌توانید از گزینه -o outfile برای تعیین فایل خروجی استفاده کنید.

مگر در مواردی که خلاف آن ذکر شده باشد، یا گزینه به = ختم شود، تمام گزینه‌هایی که آرگومان می‌پذیرند می‌توانند آن آرگومان را دقیقاً پس از گزینه یا با یک فاصله بین گزینه و آرگومان داشته باشند: -Ifoo و -I foo تأثیر یکسانی دارند.

بسیاری از گزینه‌ها نام‌های چندحرفی دارند؛ بنابراین گزینه‌های تک‌حرفی چندگانه ممکن است نتوانند با هم گروه‌بندی شوند: -dM بسیار متفاوت از -d -M است.

پیش‌تعریف name به عنوان یک ماکرو، با تعریف 1.
محتویات definition نشانه‌گذاری (tokenize) شده و طوری پردازش می‌شوند که گویی در مرحلهٔ سوم ترجمه درون یک دستورالعمل #define ظاهر شده‌اند. به‌ویژه، تعریف با نویسه‌های خط جدیدِ تعبیه‌شده کوتاه (truncated) می‌شود.

اگر پیش‌پردازنده را از یک شل یا برنامه‌ای شبیه به شل اجرا می‌کنید، ممکن است لازم باشد از نحو نقل‌قول شل برای محافظت از نویسه‌هایی مانند فاصله‌ها که در نحو شل معنای خاصی دارند، استفاده کنید.

اگر مایلید یک ماکروی شبیه به تابع (function-like) را در خط فرمان تعریف کنید، فهرست آرگومان‌های آن را همراه با پرانتزهای احاطه‌کننده قبل از علامت مساوی (در صورت وجود) بنویسید. پرانتزها برای بیشتر شل‌ها معنادار هستند، بنابراین باید گزینه را درون نقل‌قول قرار دهید. با sh و csh، ساختار -D'name(args...)=definition' کار می‌کند.

گزینه‌های -D و -U به همان ترتیبی که در خط فرمان داده شده‌اند پردازش می‌شوند. تمام گزینه‌های -imacros file و -include file پس از همهٔ گزینه‌های -D و -U پردازش می‌شوند.

لغو هرگونه تعریف قبلی از name، چه توکار باشد و چه با یک گزینه -D مشخص شده باشد.
پردازش file طوری که گویی "#include "file"" به عنوان نخستین سطر از فایل منبع اصلی ظاهر شده است. با این حال، نخستین دایرکتوری جستجوشده برای file دایرکتوری کاری پیش‌پردازنده است به جای دایرکتوری حاوی فایل منبع اصلی. اگر در آنجا پیدا نشود، به صورت عادی در بقیهٔ زنجیرهٔ جستجوی "#include "..."" جستجو می‌شود.

اگر چندین گزینه -include داده شده باشد، فایل‌ها به ترتیبی که در خط فرمان ظاهر شده‌اند گنجانده می‌شوند.

دقیقاً مانند -include عمل می‌کند، به جز اینکه هر خروجی تولیدشده از پویش file دور ریخته می‌شود. ماکروهایی که تعریف می‌کند، تعریف‌شده باقی می‌مانند. این ویژگی به شما امکان می‌دهد تمام ماکروها را از یک فایل سرآیند، بدون پردازش اعلان‌های آن، به دست آورید.

تمام فایل‌های تعیین‌شده با -imacros پیش از تمام فایل‌های تعیین‌شده با -include پردازش می‌شوند.

هیچ ماکروی مختص سیستم یا مختص GCC را از پیش تعریف نکن. ماکروهای استاندارد از پیش تعریف‌شده همچنان تعریف‌شده باقی می‌مانند.
تعریف ماکروهای اضافی مورد نیاز برای استفاده از کتابخانه نخ‌های POSIX. شما باید از این گزینه به‌طور پیوسته هم برای کامپایل و هم برای پیوند استفاده کنید. این گزینه روی مقصدهای GNU/Linux، بیشتر مشتقات یونیکس، و همچنین روی مقصدهای x86 Cygwin و MinGW پشتیبانی می‌شود.
به جای خروجی دادن نتیجهٔ پیش‌پردازش، قاعده‌ای مناسب برای make خروجی داده می‌شود که وابستگی‌های فایل منبع اصلی را توصیف می‌کند. پیش‌پردازنده یک قاعدهٔ make خروجی می‌دهد که شامل نام فایل شیء (object file) برای آن فایل منبع، یک دونقطه، و نام تمام فایل‌های گنجانده‌شده است، از جمله فایل‌هایی که از گزینه‌های خط فرمان -include یا -imacros آمده‌اند.

مگر اینکه صراحتاً (با -MT یا -MQ) مشخص شده باشد، نام فایل شیء شامل نام فایل منبع است که هر پسوند آن با پسوند فایل شیء جایگزین شده و هر بخش دایرکتوری ابتدایی آن حذف شده است. اگر فایل‌های گنجانده‌شدهٔ زیادی وجود داشته باشد، قاعده با استفاده از \-newline به چند خط تقسیم می‌شود. این قاعده هیچ دستوری ندارد.

این گزینه خروجی اشکال‌زدایی پیش‌پردازنده مانند -dM را متوقف نمی‌کند. برای جلوگیری از مخلوط شدن چنین خروجی اشکال‌زدایی با قواعد وابستگی، باید صراحتاً فایل خروجی وابستگی را با -MF مشخص کنید، یا از یک متغیر محیطی مانند DEPENDENCIES_OUTPUT استفاده نمایید. خروجی اشکال‌زدایی همچنان طبق معمول به جریان خروجی عادی فرستاده می‌شود.

ارسال -M به درایور مستلزم -E است، و هشدارها را با یک -w ضمنی نادیده می‌گیرد.

مانند -M عمل می‌کند اما فایل‌های سرآیندی که در دایرکتوری‌های سرآیند سیستمی پیدا می‌شوند، و همچنین فایل‌های سرآیندی که مستقیماً یا غیرمستقیم از چنین سرآیندی گنجانده شده‌اند را ذکر نمی‌کند.

این بدان معناست که انتخاب علامت قلاب (angle brackets) یا گیومه در یک دستورالعمل #include به‌خودی‌خود تعیین نمی‌کند که آیا آن سرآیند در خروجی وابستگی -MM ظاهر می‌شود یا خیر.

هنگامی که همراه با -M یا -MM استفاده شود، فایلی را مشخص می‌کند که وابستگی‌ها در آن نوشته شوند. اگر هیچ سوییچ -MF داده نشود، پیش‌پردازنده قواعد را به همان مکانی ارسال می‌کند که خروجی پیش‌پردازش‌شده را ارسال می‌کرد.

هنگامی که همراه با گزینه‌های درایور -MD یا -MMD استفاده شود، -MF بر فایل خروجی وابستگی پیش‌فرض اولویت می‌یابد.

اگر file برابر - باشد، وابستگی‌ها در stdout نوشته می‌شوند.

در همراهی با گزینه‌ای مانند -M که درخواست ایجاد وابستگی می‌کند، -MG فرض می‌کند که فایل‌های سرآیند مفقود، فایل‌های تولیدشده هستند و آن‌ها را بدون ایجاد خطا به فهرست وابستگی‌ها می‌افزاید. نام فایل وابستگی مستقیماً از دستورالعمل "#include" بدون اضافه کردن هیچ مسیری در ابتدا گرفته می‌شود. -MG همچنین خروجی پیش‌پردازش‌شده را متوقف می‌کند، زیرا یک فایل سرآیند مفقود این خروجی را بی‌فایده می‌سازد.

این قابلیت در به‌روزرسانی خودکار makefileها استفاده می‌شود.

غیرفعال کردن تولید وابستگی برای رابط‌های ماژول کامپایل‌شده.
این گزینه به CPP دستور می‌دهد تا یک هدف ساختگی (phony target) برای هر وابستگی به‌جز فایل اصلی اضافه کند، که باعث می‌شود هر یک به هیچ چیزی وابسته نباشند. این قواعد ساختگی، خطاهایی را که make در صورت حذف فایل‌های سرآیند بدون به‌روزرسانی فایل Makefile مربوطه می‌دهد دور می‌زنند.

این یک نمونه خروجی معمول است:

test.o: test.c test.h

test.h:
تغییر هدفِ قاعده‌ای که توسط تولید وابستگی صادر می‌شود. به‌طور پیش‌فرض، CPP نام فایل ورودی اصلی را می‌گیرد، هرگونه اجزای دایرکتوری و هر پسوند فایلی مانند .c را حذف می‌کند، و پسوند شیء معمول پلتفرم را به آن می‌افزاید. نتیجه، هدف نهایی است.

یک گزینهٔ -MT هدف را دقیقاً روی رشته‌ای که شما مشخص می‌کنید تنظیم می‌کند. اگر چندین هدف می‌خواهید، می‌توانید آن‌ها را به صورت یک آرگومان واحد برای -MT مشخص کنید، یا از چندین گزینهٔ -MT استفاده نمایید.

برای مثال، -MT '$(objpfx)foo.o' ممکن است چنین خروجی بدهد:

        $(objpfx)foo.o: foo.c
همانند -MT است، اما هر نویسه‌ای را که برای Make معنای خاصی دارد نقل‌قول می‌کند. -MQ '$(objpfx)foo.o' نتیجه می‌دهد:
        $$(objpfx)foo.o: foo.c

هدف (target) پیش‌فرض به‌طور خودکار نقل‌قول می‌شود، درست مانند اینکه با -MQ مشخص شده باشد.

-MD معادل -M -MF file است، با این تفاوت که -E ضمنی نیست. درایور file را بر اساس اینکه گزینهٔ -o داده شده است یا نه تعیین می‌کند. اگر داده شده باشد، درایور از آرگومان آن اما با پسوند .d استفاده می‌کند، در غیر این صورت نام فایل ورودی را گرفته، بخش‌های مربوط به دایرکتوری و پسوند آن را حذف کرده و یک پسوند .d اعمال می‌کند.

اگر -MD همراه با -E استفاده شود، هر سوییچ -o به عنوان مشخص‌کنندهٔ فایل خروجی وابستگی‌ها در نظر گرفته می‌شود، اما اگر بدون -E استفاده شود، هر -o به عنوان مشخص‌کنندهٔ یک فایل شیء هدف در نظر گرفته می‌شود.

از آنجا که -E ضمنی نیست، می‌توان از -MD برای تولید یک فایل خروجی وابستگی به عنوان اثر جانبی فرایند کامپایل استفاده کرد.

مانند -MD است، با این تفاوت که فقط به فایل‌های سرآیند کاربر اشاره می‌کند، نه فایل‌های سرآیند سیستم.
به پیش‌پردازنده اعلام می‌کند که فایل ورودی قبلاً پیش‌پردازش شده است. این کار مواردی مانند گسترش ماکرو، تبدیل سه‌نویسه‌ای‌ها، ادغام خط جدید با نویسهٔ گریز و پردازش بیشتر دستورها را غیرفعال می‌کند. پیش‌پردازنده همچنان توضیحات (کامنت‌ها) را تشخیص داده و حذف می‌کند، به‌طوری که می‌توانید فایلی را که با -C پیش‌پردازش شده است بدون مشکل به کامپایلر ارسال کنید. در این حالت، پیش‌پردازندهٔ یکپارچه چیزی فراتر از یک توکن‌ساز برای پیشانه‌ها نیست.

اگر فایل ورودی دارای یکی از پسوندهای .i، .ii یا .mi باشد، -fpreprocessed به‌طور ضمنی فعال می‌شود. این‌ها پسوندهایی هستند که GCC برای فایل‌های پیش‌پردازش‌شدهٔ ایجاد شده توسط -save-temps استفاده می‌کند.

هنگام پیش‌پردازش، دستورها را پردازش می‌کند، اما ماکروها را گسترش نمی‌دهد.

رفتار این گزینه به گزینه‌های -E و -fpreprocessed بستگی دارد.

با -E، پیش‌پردازش محدود به مدیریت دستورهایی مانند "#define"، "#ifdef" و "#error" می‌شود. سایر عملیات‌های پیش‌پردازنده، مانند گسترش ماکرو و تبدیل سه‌نویسه‌ای انجام نمی‌شوند. علاوه بر این، گزینهٔ -dD به‌طور ضمنی فعال می‌شود.

با -fpreprocessed، پیش‌تعریف ماکروهای خط فرمان و بیشتر ماکروهای توکار غیرفعال می‌شود. ماکروهایی مانند "__LINE__" که وابسته به زمینه هستند، به طور عادی پردازش می‌شوند. این کار کامپایل فایل‌هایی را که قبلاً با "-E -fdirectives-only" پیش‌پردازش شده‌اند ممکن می‌سازد.

با استفادهٔ هم‌زمان از -E و -fpreprocessed، قوانین مربوط به -fpreprocessed اولویت دارند. این کار پیش‌پردازش کامل فایل‌هایی را که قبلاً با "-E -fdirectives-only" پیش‌پردازش شده‌اند امکان‌پذیر می‌کند.

نویسهٔ $ را در شناسه‌ها می‌پذیرد.
نام‌های نویسهٔ فراگیر و نویسه‌های گسترش‌یافته را در شناسه‌ها می‌پذیرد. این گزینه به‌طور پیش‌فرض برای C99 (و نسخه‌های استاندارد بعدی C) و C++ فعال است.
هنگام پیش‌پردازش، مسیرهای سرآیند سیستم را با کانونیکال‌سازی کوتاه نمی‌کند.
حداکثر عمق تو در تو بودن دستورهای #include را تعیین می‌کند. مقدار پیش‌فرض ۲۰۰ است.
فایل‌های ورودی را نه‌تنها در دایرکتوری جاری، بلکه در مسیر #include نیز جستجو می‌کند. این ویژگی به‌ویژه برای ماژول‌های C++20 مفید است که در آن‌ها هم واحدهای سرآیند و هم واحدهای واسط ماژول باید مستقیماً کامپایل شوند: 
g++ -c -std=c++20 -fmodules -fsearch-include-path bits/stdc++.h bits/std.cc

مقدار پیش‌فرض kind برابر user است که در مسیر جستجوی #include "..." جستجو می‌کند؛ همچنین می‌توانید به‌طور صریح system را برای مسیر جستجوی "#include <...>" مشخص کنید.

فاصلهٔ بین ایستگاه‌های تب را تعیین می‌کند. این کار به پیش‌پردازنده کمک می‌کند تا شماره ستون‌های صحیح را در هشدارها یا خطاها گزارش دهد، حتی اگر تب‌ها در خط وجود داشته باشند. اگر مقدار کمتر از ۱ یا بیشتر از ۱۰۰ باشد، گزینه نادیده گرفته می‌شود. مقدار پیش‌فرض ۸ است.
موقعیت توکن‌ها را در طول گسترش ماکروها ردیابی می‌کند. این به کامپایلر اجازه می‌دهد در صورت بروز خطای کامپایل درون یک گسترش ماکرو، اطلاعات تشخیصی دربارهٔ پشتهٔ گسترش ماکروی فعلی صادر کند. استفاده از این گزینه باعث مصرف حافظهٔ بیشتر توسط پیش‌پردازنده و کامپایلر می‌شود. پارامتر level می‌تواند برای انتخاب سطح دقت ردیابی موقعیت توکن و در نتیجه کاهش مصرف حافظه در صورت لزوم استفاده شود. مقدار 0 برای level این گزینه را غیرفعال می‌کند. مقدار 1 موقعیت توکن‌ها را در یک حالت کاهش‌یافته برای به حداقل رساندن بار اضافی حافظه ردیابی می‌کند. در این حالت، تمام توکن‌های حاصل از گسترش یک آرگومان از یک ماکروی تابع‌گونه دارای موقعیت یکسانی خواهند بود. مقدار 2 موقعیت توکن‌ها را به‌طور کامل ردیابی می‌کند. این مقدار بیشترین مصرف حافظه را دارد. هنگامی که این گزینه بدون آرگومان داده شود، مقدار پیش‌فرض پارامتر 2 است.

توجه داشته باشید که "-ftrack-macro-expansion=2" به‌طور پیش‌فرض فعال است.

هنگام پیش‌پردازش فایل‌های مستقر در دایرکتوری old، ماکروهای "__FILE__" و "__BASE_FILE__" را به‌گونه‌ای گسترش می‌دهد که گویی فایل‌ها در دایرکتوری new قرار دارند. این گزینه می‌تواند برای تبدیل یک مسیر مطلق به یک مسیر نسبی با استفاده از . برای new استفاده شود، که می‌تواند به ساخت‌های تکرارپذیرتر و مستقل از مکان منجر شود. این گزینه همچنین بر "__builtin_FILE()" در حین کامپایل اثر می‌گذارد. همچنین ببینید: -ffile-prefix-map و -fcanon-prefix-map.
مجموعه‌نویسهٔ اجرایی را که برای ثابت‌های رشته‌ای و نویسه‌ای استفاده می‌شود، تعیین می‌کند. مقدار پیش‌فرض UTF-8 است. charset می‌تواند هر کدگذاری پشتیبانی‌شده توسط تابع کتابخانه‌ای "iconv" در سیستم باشد.
مجموعه‌نویسهٔ اجرایی عریض را که برای ثابت‌های رشته‌ای و نویسه‌ای عریض استفاده می‌شود، تعیین می‌کند. مقدار پیش‌فرض یکی از گزینه‌های UTF-32BE، UTF-32LE، UTF-16BE یا UTF-16LE است، بسته به اینکه کدام‌یک با عرض "wchar_t" و ترتیب بایتِ مه‌بایتی یا که‌بایتی مورد استفاده برای تولید کد مطابقت داشته باشد. همانند -fexec-charset، پارامتر charset می‌تواند هر کدگذاری پشتیبانی‌شده توسط تابع کتابخانه‌ای "iconv" در سیستم باشد؛ با این حال، با کدگذاری‌هایی که دقیقاً در "wchar_t" جا نمی‌شوند دچار مشکل خواهید شد.
مجموعه‌نویسهٔ ورودی را تعیین می‌کند که برای تبدیل از مجموعه‌نویسهٔ فایل ورودی به مجموعه‌نویسهٔ منبع مورد استفاده توسط GCC به کار می‌رود. مقدار پیش‌فرض UTF-8 است. charset می‌تواند هر کدگذاری پشتیبانی‌شده توسط تابع کتابخانه‌ای "iconv" در سیستم باشد.

اگر مجموعه‌نویسهٔ ورودی UTF-8 باشد، در صورت فعال بودن -Winvalid-utf8 هشدارهایی دربارهٔ توالی‌های بدشکل یکای کد صادر می‌شود. در غیر این صورت، وقتی مجموعه‌نویسهٔ ورودی با مجموعه‌نویسهٔ اجرایی مطابقت داشته باشد، هیچ پیام تشخیصی صادر نمی‌شود. اگر آن‌ها متفاوت باشند، توالی‌های بدشکل یکای کد در طول تبدیل کدگذاری به مجموعه‌نویسهٔ اجرایی منجر به خطا می‌شوند.

تولید نشانگرهای خط را در خروجی پیش‌پردازنده فعال می‌کند تا کامپایلر از دایرکتوری کاری فعلی در زمان پیش‌پردازش مطلع شود. هنگامی که این گزینه فعال باشد، پیش‌پردازنده پس از نشانگر خط اولیه، یک نشانگر خط دوم با دایرکتوری کاری فعلی به همراه دو اسلش صادر می‌کند. GCC از این دایرکتوری، در صورت وجود در ورودی پیش‌پردازش‌شده، به عنوان دایرکتوری ثبت‌شده به عنوان دایرکتوری کاری فعلی در برخی قالب‌های اطلاعات اشکال‌زدایی استفاده می‌کند. این گزینه در صورت فعال بودن اطلاعات اشکال‌زدایی به‌طور ضمنی فعال است، اما می‌توان آن را با شکل نقیض -fno-working-directory غیرفعال کرد. اگر پرچم -P در خط فرمان وجود داشته باشد، این گزینه هیچ تاثیری نخواهد داشت، زیرا اصلاً هیچ دستور "#line" صادر نمی‌شود.
یک ادعا با گزارهٔ predicate و پاسخ answer ایجاد می‌کند. این شکل بر شکل قدیمی‌تر -A predicate(answer) که همچنان پشتیبانی می‌شود ترجیح داده می‌شود، زیرا از نویسه‌های خاص شل استفاده نمی‌کند.

ادعاها یک ویژگی منسوخ‌شده در پیش‌پردازنده هستند که فقط برای سازگاری با سرآیندهای سیستم قدیمی در برخی اهداف پشتیبانی می‌شوند.

یک ادعا را با گزارهٔ predicate و پاسخ answer لغو می‌کند..IP -C 4
کامنت‌ها را دور نریزید. تمام کامنت‌ها به فایل خروجی فرستاده می‌شوند، به جز کامنت‌های درون دستورالعمل‌های پردازش‌شده که همراه با خود دستورالعمل حذف می‌شوند.

هنگام استفاده از -C باید برای عوارض جانبی آماده باشید؛ این گزینه باعث می‌شود پیش‌پردازنده با کامنت‌ها به عنوان نشانه‌هایی مستقل رفتار کند. برای مثال، کامنت‌هایی که در ابتدای یک خط که قرار است خط دستورالعمل باشد ظاهر می‌شوند، این اثر را دارند که آن خط را به یک خط منبع معمولی تبدیل می‌کنند، زیرا نخستین نشانه در آن خط دیگر یک # نخواهد بود.

کامنت‌ها را حتی در طول بسط ماکرو حذف نکنید. این شبیه -C است، با این تفاوت که کامنت‌های درون ماکروها نیز در جایی که ماکرو بسط می‌یابد، به فایل خروجی منتقل می‌شوند.

علاوه بر عوارض جانبی گزینهٔ -C، گزینهٔ -CC باعث می‌شود همهٔ کامنت‌های سبک C++ درون یک ماکرو به کامنت‌های سبک C تبدیل شوند. این برای جلوگیری از آن است که استفاده‌های بعدی از آن ماکرو به‌طور ناخواسته بقیهٔ خط منبع را به کامنت تبدیل نکنند.

گزینهٔ -CC عموماً برای پشتیبانی از کامنت‌های lint استفاده می‌شود.

از تولید نشانگرهای خط (linemarkers) در خروجی پیش‌پردازنده جلوگیری می‌کند. این گزینه ممکن است زمانی مفید باشد که پیش‌پردازنده روی چیزی غیر از کد C اجرا می‌شود و خروجی قرار است به برنامه‌ای ارسال شود که ممکن است با این نشانگرهای خط دچار سردرگمی شود.
تلاش برای تقلید از رفتار پیش‌پردازنده‌های C پیش از استاندارد، در مقایسه با پیش‌پردازنده‌های ISO C.

توجه داشته باشید که GCC در غیر این صورت تلاشی برای شبیه‌سازی یک کامپایلر C پیش از استاندارد انجام نمی‌دهد، و این گزینه‌ها فقط با سوئیچ -E یا هنگام فراخوانی صریح CPP پشتیبانی می‌شوند.

از سه‌نگاره‌های (trigraphs) استاندارد ISO C پشتیبانی می‌کند. این‌ها توالی‌های سه‌کاراکتری هستند که همگی با ?? شروع می‌شوند و توسط ISO C تعریف شده‌اند تا نمایانگر کاراکترهای تکی باشند. برای نمونه، ??/ بیانگر \ است، بنابراین '??/n' یک ثابت کاراکتری برای خط جدید است.

به‌طور پیش‌فرض، GCC سه‌نگاره‌ها را نادیده می‌گیرد، اما در حالت‌های منطبق بر استاندارد آن‌ها را تبدیل می‌کند. گزینه‌های -std و -ansi را ببینید.

کد ویژه‌ای را برای دور زدن محدودیت سیستم‌های فایلی که فقط نام‌های بسیار کوتاه فایل را مجاز می‌دانند، مانند MS-DOS، فعال می‌کند.
علاوه بر سایر فعالیت‌های عادی، نام هر فایل سرایندِ استفاده‌شده را چاپ می‌کند. هر نام برای نشان دادن عمق آن در پشتهٔ #include دندانه‌دار می‌شود. فایل‌های سرایند پیش‌کامپایل‌شده نیز چاپ می‌شوند، حتی اگر نامعتبر تشخیص داده شوند؛ یک فایل سرایند پیش‌کامپایل‌شدهٔ نامعتبر با ...x و یک فایل معتبر با ...! چاپ می‌شود.
مشخص می‌کند که در حین کامپایل، دامپ‌های اشکال‌زدایی طبق آنچه توسط letters تعیین شده، ایجاد شوند. پرچم‌های مستندشده در اینجا مواردی هستند که به پیش‌پردازنده مربوط می‌شوند. سایر letters توسط خود کامپایلر تفسیر می‌شوند یا برای نسخه‌های بعدی GCC رزرو شده‌اند و بنابراین بی‌صدا نادیده گرفته می‌شوند. اگر مواردی از letters را مشخص کنید که رفتارشان با هم در تضاد است، نتیجه تعریف‌نشده (undefined) خواهد بود.
به جای خروجی عادی، فهرستی از دستورالعمل‌های #define را برای همهٔ ماکروهای تعریف‌شده در حین اجرای پیش‌پردازنده، شامل ماکروهای از پیش تعریف‌شده، تولید می‌کند. این روش راهی را در اختیارتان می‌گذارد تا دریابید چه چیزهایی در نسخهٔ پیش‌پردازندهٔ شما از پیش تعریف شده است. با فرض اینکه فایلی به نام foo.h ندارید، دستور 
touch foo.h; cpp -dM foo.h

تمام ماکروهای از پیش تعریف‌شده را نمایش می‌دهد.

مانند -dM است با این تفاوت که هم دستورالعمل‌های #define و هم نتیجهٔ پیش‌پردازش را در خروجی قرار می‌دهد. هر دو نوع خروجی به فایل خروجی استاندارد ارسال می‌شوند.
مانند -dD است، اما فقط نام ماکروها را صادر می‌کند، نه بسط آن‌ها را.
دستورالعمل‌های #include را علاوه بر نتیجهٔ پیش‌پردازش در خروجی قرار می‌دهد.
مانند -dD است با این تفاوت که فقط ماکروهایی که بسط داده می‌شوند یا تعریف‌شدگی آن‌ها در دستورالعمل‌های پیش‌پردازنده بررسی می‌شود، در خروجی می‌آیند؛ خروجی تا زمان استفاده یا بررسی ماکرو به تأخیر می‌افتد؛ و دستورالعمل‌های #undef نیز برای ماکروهایی که بررسی شده اما در آن زمان تعریف‌نشده بودند، در خروجی درج می‌شوند.
این گزینه فقط برای اشکال‌زدایی GCC مفید است. هنگامی که از CPP یا همراه با -E استفاده شود، اطلاعات اشکال‌زدایی را دربارهٔ نقشه‌های موقعیت (location maps) دامپ می‌کند. پیش از هر نشانه در خروجی، دامپ نقشه‌ای که موقعیت آن متعلق به آن است می‌آید.

هنگامی که از GCC بدون -E استفاده شود، این گزینه هیچ تأثیری ندارد.

دایرکتوری dir را به فهرست دایرکتوری‌هایی که در طول پیش‌پردازش برای فایل‌های سرایند جستجو می‌شوند، می‌افزاید. --include-directory یک نام مستعار برای -I است، در حالی که --include-directory-after نام مستعاری برای -idirafter است.

اگر dir با = یا $SYSROOT آغاز شود، آنگاه = یا $SYSROOT با پیشوند sysroot جایگزین می‌شود؛ به --sysroot و -isysroot مراجعه کنید.

دایرکتوری‌های مشخص‌شده با -iquote فقط برای شکل نقل‌قولی (کوتیشن‌دار) دستورالعمل، یعنی "#include "file"" اعمال می‌شوند. دایرکتوری‌های مشخص‌شده با -I، -isystem یا -idirafter برای جستجوی هر دو دستورالعمل "#include "file"" و "#include <file>" اعمال می‌شوند.

می‌توانید هر تعداد یا ترکیبی از این گزینه‌ها را در خط فرمان مشخص کنید تا فایل‌های سرایند در چندین دایرکتوری جستجو شوند. ترتیب جستجو به شرح زیر است:

برای حالت نقل‌قولیِ دستور include، ابتدا دایرکتوریِ فایل فعلی جستجو می‌شود.
2.
برای حالت نقل‌قولیِ دستور include، دایرکتوری‌های مشخص‌شده با گزینه‌های -iquote به ترتیب از چپ به راست، همان‌گونه که در خط فرمان آمده‌اند، جستجو می‌شوند.
3.
دایرکتوری‌های مشخص‌شده با گزینه‌های -I به ترتیب از چپ به راست پیمایش می‌شوند.
4.
دایرکتوری‌های مشخص‌شده با گزینه‌های -isystem به ترتیب از چپ به راست پیمایش می‌شوند.
5.
دایرکتوری‌های استاندارد سیستم پیمایش می‌شوند.
6.
دایرکتوری‌های مشخص‌شده با گزینه‌های -idirafter به ترتیب از چپ به راست پیمایش می‌شوند.

می‌توانید از -I برای بازنویسی و جایگزینی فایل سرآیند سیستمی با نسخهٔ خودتان استفاده کنید، چرا که این دایرکتوری‌ها پیش از دایرکتوری‌های فایل‌های سرآیند استاندارد سیستم جستجو می‌شوند. با این حال، نباید از این گزینه برای افزودن دایرکتوری‌های حاوی فایل‌های سرآیند سیستمی ارائه‌شده توسط سازنده استفاده کنید؛ برای این منظور از -isystem استفاده نمایید.

گزینه‌های -isystem و -idirafter همچنین دایرکتوری را به عنوان یک دایرکتوری سیستمی علامت‌گذاری می‌کنند، تا همان رفتار ویژه‌ای که بر دایرکتوری‌های استاندارد سیستم اعمال می‌شود، برای آن نیز اعمال گردد.

اگر یک دایرکتوری استاندارد include سیستم، یا دایرکتوریِ مشخص‌شده با -isystem، با -I نیز مشخص شده باشد، گزینهٔ -I نادیده گرفته می‌شود. دایرکتوری همچنان جستجو می‌شود اما به عنوان یک دایرکتوری سیستمی در جایگاه معمول خود در زنجیرهٔ include سیستم. این امر برای اطمینان از این است که سازوکار GCC برای اصلاح سرآیندهای سیستمی معیوب و ترتیب دستور "#include_next" سهواً تغییر نکند. اگر واقعاً نیاز به تغییر ترتیب جستجوی دایرکتوری‌های سیستمی دارید، از گزینه‌های -nostdinc و/یا -isystem استفاده کنید.

مسیر include را تفکیک می‌کند. این گزینه منسوخ شده است. لطفاً برای دایرکتوری‌های -I قبل از -I- به‌جای آن از -iquote استفاده کرده و گزینهٔ -I- را حذف کنید.

هر دایرکتوری مشخص‌شده با گزینه‌های -I پیش از -I- تنها برای سرآیندهای درخواست‌شده با "#include "file"" جستجو می‌شوند؛ آن‌ها برای "#include <file>" جستجو نخواهند شد. اگر دایرکتوری‌های دیگری پس از -I- با گزینه‌های -I مشخص شوند، آن دایرکتوری‌ها برای تمامی دستورهای #include جستجو می‌شوند.

علاوه بر این، -I- از استفاده از دایرکتوریِ فایل فعلی به عنوان نخستین دایرکتوری جستجو برای "#include "file"" جلوگیری می‌کند. هیچ راهی برای لغو این اثر -I- وجود ندارد.

prefix را به عنوان پیشوند برای گزینه‌های بعدیِ -iwithprefix تعیین می‌کند. اگر پیشوند نمایانگر یک دایرکتوری است، باید اسلش انتهایی / را نیز قرار دهید.
dir را به پیشوندی که پیش‌تر با -iprefix مشخص شده پیوست کرده و دایرکتوری حاصل را به مسیر جستجوی include اضافه می‌کند. -iwithprefixbefore آن را در همان جایی قرار می‌دهد که -I قرار می‌داد؛ -iwithprefix آن را در جایی قرار می‌دهد که -idirafter می‌گذاشت.

هر دو گزینهٔ --include-with-prefix و --include-with-prefix-after نام‌های مستعاری برای -iwithprefix هستند، در حالی که --include-with-prefix-before نام مستعاری برای -iwithprefixbefore است.

این گزینه مشابه گزینهٔ --sysroot است، اما تنها برای فایل‌های سرآیند اعمال می‌شود (به جز مقصدهای Darwin، که در آن هم بر روی فایل‌های سرآیند و هم کتابخانه‌ها اعمال می‌گردد). برای اطلاعات بیشتر گزینهٔ --sysroot را ببینید.
از dir به عنوان زیردایرکتوریِ دایرکتوریِ حاوی سرآیندهای ++C ویژهٔ مقصد استفاده می‌کند.
از dir به عنوان زیردایرکتوریِ دایرکتوریِ حاوی سرآیندهای ++C ویژهٔ معماری استفاده می‌کند.
دایرکتوری‌های استاندارد سیستم را برای فایل‌های سرآیند جستجو نمی‌کند. تنها دایرکتوری‌هایی که صراحتاً با گزینه‌های -I، -iquote، -isystem و/یا -idirafter تعیین شده‌اند (و در صورت لزوم، دایرکتوری فایل فعلی) جستجو می‌شوند.
برای فایل‌های سرآیند در دایرکتوری‌های استاندارد ویژهٔ ++C جستجو نمی‌کند، اما دیگر دایرکتوری‌های استاندارد را همچنان جستجو می‌کند. (این گزینه هنگام ساخت کتابخانهٔ ++C به کار می‌رود.)
دایرکتوری dir را به فهرست دایرکتوری‌های مورد جستجو برای دستور پیش‌پردازندهٔ "#embed" یا ماکروی "__has_embed" اضافه می‌کند. هیچ دایرکتوری پیش‌فرضی برای "#embed" وجود ندارد.

اگر dir با = یا $SYSROOT شروع شود، آنگاه = یا $SYSROOT با پیشوند sysroot جایگزین می‌شود؛ گزینه‌های --sysroot و -isysroot را ببینید.

هر زمان که توالی آغاز توضیح /* درون یک توضیح /* پدیدار شود، یا هرگاه که یک بک‌اسلش-خط‌جدید درون یک توضیح // بیاید، هشدار می‌دهد. این هشدار با -Wall فعال می‌شود.
اگر سه‌نویسه‌ای (trigraph) دیده شود که ممکن است معنای برنامه را تغییر دهد، هشدار می‌دهد. در مورد سه‌نویسه‌های درون توضیحات هشداری داده نمی‌شود، مگر مواردی که یک خط‌جدیدِ گریزخورده تشکیل دهند.

این گزینه به‌طور ضمنی توسط -Wall اعمال می‌شود. اگر -Wall داده نشود، این گزینه همچنان فعال است مگر اینکه سه‌نویسه‌ها فعال شده باشند. برای به‌دست‌آوردن تبدیل سه‌نویسه‌ها بدون هشدار، اما دریافت سایر هشدارهای -Wall، از -trigraphs -Wall -Wno-trigraphs استفاده کنید.

اگر شناسهٔ تعریف‌نشده‌ای در دستور "#if" ارزیابی شود، هشدار می‌دهد. چنین شناسه‌هایی با صفر جایگزین می‌شوند.
هر زمان که defined در بسط یک ماکرو دیده شود (شامل حالتی که ماکرو با یک دستور #if بسط می‌یابد)، هشدار می‌دهد. چنین کاربردی سازگار و قابل‌حمل نیست. این هشدار با -Wpedantic و -Wextra نیز فعال می‌گردد.
دربارهٔ ماکروهای تعریف‌شده در فایل اصلی که بلااستفاده مانده‌اند هشدار می‌دهد. یک ماکرو در صورتی استفاده‌شده در نظر گرفته می‌شود که دست‌کم یک بار بسط داده شود یا وجود آن بررسی گردد. پیش‌پردازنده همچنین در صورتی که ماکرو در زمان بازتعریف یا حذف تعریف استفاده نشده باشد، هشدار می‌دهد.

دربارهٔ ماکروهای توکار، ماکروهای تعریف‌شده در خط فرمان، و ماکروهای تعریف‌شده در فایل‌های include هشداری داده نمی‌شود.

نکته: اگر ماکرویی واقعاً استفاده شده باشد، اما تنها در بلوک‌های شرطیِ نادیده‌گرفته‌شده استفاده شود، پیش‌پردازنده آن را بلااستفاده گزارش می‌کند. برای پرهیز از هشدار در چنین حالتی، می‌توانید محدودهٔ تعریف ماکرو را بهبود دهید؛ برای نمونه، با انتقال آن به نخستین بلوکِ نادیده‌گرفته‌شده. در غیر این صورت، می‌توانید با چیزی شبیه به این یک استفادهٔ صوری ایجاد کنید:

        #if defined the_macro_causing_the_warning
        #endif
هرگاه پس از "#else" یا "#endif" متنی قرار گرفت، هشدار داده نشود.
این وضعیت گاهی در برنامه‌های قدیمی‌تر با کدهایی به این شکل رخ می‌دهد:
        #if FOO
        ...
        #else FOO
        ...
        #endif FOO

دومین و سومین "FOO" باید درون توضیحات (کامنت‌ها) باشند. این هشدار به‌طور پیش‌فرض فعال است.

این بخش متغیرهای محیطی اثرگذار بر نحوه عملکرد CPP را شرح می‌دهد. می‌توانید از آن‌ها برای تعیین دایرکتوری‌ها یا پیشوندهایی که هنگام جستجو برای فایل‌های include به کار می‌روند، یا برای کنترل خروجی وابستگی‌ها استفاده کنید.

توجه داشته باشید که همچنین می‌توانید با استفاده از گزینه‌هایی مانند -I مکان‌های جستجو را مشخص کنید، و خروجی وابستگی‌ها را با گزینه‌هایی مانند -M کنترل نمایید. این گزینه‌ها بر متغیرهای محیطی اولویت دارند، و متغیرهای محیطی نیز به نوبه خود بر پیکربندی GCC اولویت دارند.

مقدار هر متغیر فهرستی از دایرکتوری‌ها است که با یک نویسه خاص، بسیار شبیه به PATH، از هم جدا شده‌اند تا در آن‌ها به دنبال فایل‌های هدر جستجو شود. نویسه خاص، "PATH_SEPARATOR"، وابسته به سیستم مقصد است و در زمان ساخت GCC تعیین می‌شود. برای مقصدهای مبتنی بر Microsoft Windows، این نویسه یک نقطه‌ویرگول (semicolon) است و برای تقریباً تمام مقصدهای دیگر یک دونقطه (colon) است.

CPATH فهرستی از دایرکتوری‌ها را مشخص می‌کند که باید طوری جستجو شوند که گویی با -I مشخص شده‌اند، اما پس از هر مسیری که با گزینه‌های -I در خط فرمان تعیین شده باشد. این متغیر محیطی بدون توجه به اینکه چه زبانی پیش‌پردازش می‌شود استفاده می‌شود.

بقیه متغیرهای محیطی تنها هنگام پیش‌پردازش زبان مشخص‌شده اعمال می‌شوند. هر یک فهرستی از دایرکتوری‌ها را مشخص می‌کند که باید طوری جستجو شوند که گویی با -isystem مشخص شده‌اند، اما پس از هر مسیری که با گزینه‌های -isystem در خط فرمان داده شده باشد.

در تمام این متغیرها، یک عنصر خالی به کامپایلر دستور می‌دهد که دایرکتوری کاری جاری خود را جستجو کند. عناصر خالی می‌توانند در ابتدا یا انتهای یک مسیر ظاهر شوند. برای نمونه، اگر مقدار CPATH برابر ":/special/include" باشد، اثری مشابه با -I. -I/special/include دارد.

اگر این متغیر تنظیم شده باشد، مقدار آن نحوه خروجی وابستگی‌ها را برای Make بر اساس فایل‌های هدر غیرسیستمی پردازش‌شده توسط کامپایلر تعیین می‌کند. فایل‌های هدر سیستمی در خروجی وابستگی نادیده گرفته می‌شوند.

مقدار DEPENDENCIES_OUTPUT می‌تواند صرفاً نام یک فایل باشد، که در این حالت قواعد Make در آن فایل نوشته می‌شوند و نام هدف از روی نام فایل منبع حدس زده می‌شود. یا اینکه مقدار می‌تواند به فرم file target باشد، که در این صورت قواعد در فایل file با استفاده از target به عنوان نام هدف نوشته می‌شوند.

به بیان دیگر، این متغیر محیطی معادل ترکیب گزینه‌های -MM و -MF، همراه با یک سوییچ اختیاری -MT است.

این متغیر مانند DEPENDENCIES_OUTPUT است (بالا را ببینید)، با این تفاوت که فایل‌های هدر سیستمی نادیده گرفته نمی‌شوند، بنابراین به جای -MM بر -M دلالت دارد. با این حال، وابستگی به فایل ورودی اصلی حذف می‌شود.
اگر این متغیر تنظیم شده باشد، مقدار آن یک برچسب زمانی UNIX را مشخص می‌کند تا به جای تاریخ و زمان فعلی در ماکروهای "__DATE__" و "__TIME__" استفاده شود، به طوری که برچسب‌های زمانی تعبیه‌شده بازتولیدپذیر گردند.

مقدار SOURCE_DATE_EPOCH باید یک برچسب زمانی UNIX باشد، که به عنوان تعداد ثانیه‌ها (بدون احتساب ثانیه‌های کبیسه) از 01 Jan 1970 00:00:00 با نمایش اسکی (ASCII) تعریف می‌شود؛ درست مانند خروجی دستور "date +%s" در GNU/Linux و سایر سیستم‌هایی که از پسوند %s در دستور "date" پشتیبانی می‌کنند.

این مقدار باید یک برچسب زمانی شناخته‌شده مانند آخرین زمان تغییر کد منبع یا بسته باشد و باید توسط فرایند ساخت تنظیم شود.

gpl(7)، gfdl(7)، fsf-funding(7)، gcc(1)، و مدخل‌های Info برای cpp و gcc.

Copyright (c) 1987-2026 Free Software Foundation, Inc.

اجازه کپی، توزیع و/یا تغییر این سند تحت شرایط «مجوز مستندات آزاد گنو» (GNU Free Documentation License)، نسخه 1.3 یا هر نسخه بالاتر منتشر شده توسط بنیاد نرم‌افزار آزاد اعطا می‌شود. نسخه‌ای از این مجوز در صفحه راهنمای gfdl(7) گنجانده شده است. این راهنما هیچ بخش تغییرناپذیری ندارد. متن‌های روی جلد (a) (پایین را ببینید) و متن‌های پشت جلد (b) (پایین را ببینید) هستند.

(a) متن روی جلد FSF عبارت است از:

A GNU Manual

(b) متن پشت جلد FSF عبارت است از:

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.
2026-08-07 gcc-16.2.0