diff options
Diffstat (limited to 'share/man/man1/arm-none-eabi-cpp.1')
| -rw-r--r-- | share/man/man1/arm-none-eabi-cpp.1 | 953 |
1 files changed, 953 insertions, 0 deletions
diff --git a/share/man/man1/arm-none-eabi-cpp.1 b/share/man/man1/arm-none-eabi-cpp.1 new file mode 100644 index 0000000..525fada --- /dev/null +++ b/share/man/man1/arm-none-eabi-cpp.1 @@ -0,0 +1,953 @@ +.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) +.\" +.\" 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 +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. 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 turned on, 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 +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "CPP 1" +.TH CPP 1 "2023-10-09" "gcc-13.2.1" "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" +cpp \- The C Preprocessor +.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 +Only the most useful options are given above; see below for a more +complete list of preprocessor-specific options. +In addition, \fBcpp\fR accepts most \fBgcc\fR driver options, which +are not listed here. Refer to the \s-1GCC\s0 documentation for details. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The C preprocessor, often known as \fIcpp\fR, is a \fImacro processor\fR +that is used automatically by the C compiler to transform your program +before compilation. It is called a macro processor because it allows +you to define \fImacros\fR, which are brief abbreviations for longer +constructs. +.PP +The C preprocessor is intended to be used only with C, \*(C+, and +Objective-C source code. In the past, it has been abused as a general +text processor. It will choke on input which does not obey C's lexical +rules. For example, apostrophes will be interpreted as the beginning of +character constants, and cause errors. Also, you cannot rely on it +preserving characteristics of the input which are not significant to +C\-family languages. If a Makefile is preprocessed, all the hard tabs +will be removed, and the Makefile will not work. +.PP +Having said that, you can often get away with using cpp on things which +are not C. Other Algol-ish programming languages are often safe +(Ada, etc.) So is assembly, with caution. \fB\-traditional\-cpp\fR +mode preserves more white space, and is otherwise more permissive. Many +of the problems can be avoided by writing C or \*(C+ style comments +instead of native language comments, and keeping macros simple. +.PP +Wherever possible, you should use a preprocessor geared to the language +you are writing in. Modern versions of the \s-1GNU\s0 assembler have macro +facilities. Most high level programming languages have their own +conditional compilation and inclusion mechanism. If all else fails, +try a true general text processor, such as \s-1GNU M4.\s0 +.PP +C preprocessors vary in some details. This manual discusses the \s-1GNU C\s0 +preprocessor, which provides a small superset of the features of \s-1ISO\s0 +Standard C. In its default mode, the \s-1GNU C\s0 preprocessor does not do a +few things required by the standard. These are features which are +rarely, if ever, used, and may cause surprising changes to the meaning +of a program which does not expect them. To get strict \s-1ISO\s0 Standard C, +you should use the \fB\-std=c90\fR, \fB\-std=c99\fR, +\&\fB\-std=c11\fR or \fB\-std=c17\fR options, depending +on which version of the standard you want. To get all the mandatory +diagnostics, you must also use \fB\-pedantic\fR. +.PP +This manual describes the behavior of the \s-1ISO\s0 preprocessor. To +minimize gratuitous differences, where the \s-1ISO\s0 preprocessor's +behavior does not conflict with traditional semantics, the +traditional preprocessor should behave the same way. The various +differences that do exist are detailed in the section \fBTraditional +Mode\fR. +.PP +For clarity, unless noted otherwise, references to \fB\s-1CPP\s0\fR in this +manual refer to \s-1GNU CPP.\s0 +.SH "OPTIONS" +.IX Header "OPTIONS" +The \fBcpp\fR command expects two file names as arguments, \fIinfile\fR and +\&\fIoutfile\fR. The preprocessor reads \fIinfile\fR together with any +other files it specifies with \fB#include\fR. All the output generated +by the combined input files is written in \fIoutfile\fR. +.PP +Either \fIinfile\fR or \fIoutfile\fR may be \fB\-\fR, which as +\&\fIinfile\fR means to read from standard input and as \fIoutfile\fR +means to write to standard output. If either file is omitted, it +means the same as if \fB\-\fR had been specified for that file. +You can also use the \fB\-o\fR \fIoutfile\fR option to specify the +output file. +.PP +Unless otherwise noted, or the option ends in \fB=\fR, all options +which take an argument may have that argument appear either immediately +after the option, or with a space between option and argument: +\&\fB\-Ifoo\fR and \fB\-I foo\fR have the same effect. +.PP +Many options have multi-letter names; therefore multiple single-letter +options may \fInot\fR be grouped: \fB\-dM\fR is very different from +\&\fB\-d\ \-M\fR. +.IP "\fB\-D\fR \fIname\fR" 4 +.IX Item "-D name" +Predefine \fIname\fR as a macro, with definition \f(CW1\fR. +.IP "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4 +.IX Item "-D name=definition" +The contents of \fIdefinition\fR are tokenized and processed as if +they appeared during translation phase three in a \fB#define\fR +directive. In particular, the definition is truncated by +embedded newline characters. +.Sp +If you are invoking the preprocessor from a shell or shell-like +program you may need to use the shell's quoting syntax to protect +characters such as spaces that have a meaning in the shell syntax. +.Sp +If you wish to define a function-like macro on the command line, write +its argument list with surrounding parentheses before the equals sign +(if any). Parentheses are meaningful to most shells, so you should +quote the option. With \fBsh\fR and \fBcsh\fR, +\&\fB\-D'\fR\fIname\fR\fB(\fR\fIargs...\fR\fB)=\fR\fIdefinition\fR\fB'\fR works. +.Sp +\&\fB\-D\fR and \fB\-U\fR options are processed in the order they +are given on the command line. All \fB\-imacros\fR \fIfile\fR and +\&\fB\-include\fR \fIfile\fR options are processed after all +\&\fB\-D\fR and \fB\-U\fR options. +.IP "\fB\-U\fR \fIname\fR" 4 +.IX Item "-U name" +Cancel any previous definition of \fIname\fR, either built in or +provided with a \fB\-D\fR option. +.IP "\fB\-include\fR \fIfile\fR" 4 +.IX Item "-include file" +Process \fIfile\fR as if \f(CW\*(C`#include "file"\*(C'\fR appeared as the first +line of the primary source file. However, the first directory searched +for \fIfile\fR is the preprocessor's working directory \fIinstead of\fR +the directory containing the main source file. If not found there, it +is searched for in the remainder of the \f(CW\*(C`#include "..."\*(C'\fR search +chain as normal. +.Sp +If multiple \fB\-include\fR options are given, the files are included +in the order they appear on the command line. +.IP "\fB\-imacros\fR \fIfile\fR" 4 +.IX Item "-imacros file" +Exactly like \fB\-include\fR, except that any output produced by +scanning \fIfile\fR is thrown away. Macros it defines remain defined. +This allows you to acquire all the macros from a header without also +processing its declarations. +.Sp +All files specified by \fB\-imacros\fR are processed before all files +specified by \fB\-include\fR. +.IP "\fB\-undef\fR" 4 +.IX Item "-undef" +Do not predefine any system-specific or GCC-specific macros. The +standard predefined macros remain defined. +.IP "\fB\-pthread\fR" 4 +.IX Item "-pthread" +Define additional macros required for using the \s-1POSIX\s0 threads library. +You should use this option consistently for both compilation and linking. +This option is supported on GNU/Linux targets, most other Unix derivatives, +and also on x86 Cygwin and MinGW targets. +.IP "\fB\-M\fR" 4 +.IX Item "-M" +Instead of outputting the result of preprocessing, output a rule +suitable for \fBmake\fR describing the dependencies of the main +source file. The preprocessor outputs one \fBmake\fR rule containing +the object file name for that source file, a colon, and the names of all +the included files, including those coming from \fB\-include\fR or +\&\fB\-imacros\fR command-line options. +.Sp +Unless specified explicitly (with \fB\-MT\fR or \fB\-MQ\fR), the +object file name consists of the name of the source file with any +suffix replaced with object file suffix and with any leading directory +parts removed. If there are many included files then the rule is +split into several lines using \fB\e\fR\-newline. The rule has no +commands. +.Sp +This option does not suppress the preprocessor's debug output, such as +\&\fB\-dM\fR. To avoid mixing such debug output with the dependency +rules you should explicitly specify the dependency output file with +\&\fB\-MF\fR, or use an environment variable like +\&\fB\s-1DEPENDENCIES_OUTPUT\s0\fR. Debug output +is still sent to the regular output stream as normal. +.Sp +Passing \fB\-M\fR to the driver implies \fB\-E\fR, and suppresses +warnings with an implicit \fB\-w\fR. +.IP "\fB\-MM\fR" 4 +.IX Item "-MM" +Like \fB\-M\fR but do not mention header files that are found in +system header directories, nor header files that are included, +directly or indirectly, from such a header. +.Sp +This implies that the choice of angle brackets or double quotes in an +\&\fB#include\fR directive does not in itself determine whether that +header appears in \fB\-MM\fR dependency output. +.IP "\fB\-MF\fR \fIfile\fR" 4 +.IX Item "-MF file" +When used with \fB\-M\fR or \fB\-MM\fR, specifies a +file to write the dependencies to. If no \fB\-MF\fR switch is given +the preprocessor sends the rules to the same place it would send +preprocessed output. +.Sp +When used with the driver options \fB\-MD\fR or \fB\-MMD\fR, +\&\fB\-MF\fR overrides the default dependency output file. +.Sp +If \fIfile\fR is \fI\-\fR, then the dependencies are written to \fIstdout\fR. +.IP "\fB\-MG\fR" 4 +.IX Item "-MG" +In conjunction with an option such as \fB\-M\fR requesting +dependency generation, \fB\-MG\fR assumes missing header files are +generated files and adds them to the dependency list without raising +an error. The dependency filename is taken directly from the +\&\f(CW\*(C`#include\*(C'\fR directive without prepending any path. \fB\-MG\fR +also suppresses preprocessed output, as a missing header file renders +this useless. +.Sp +This feature is used in automatic updating of makefiles. +.IP "\fB\-Mno\-modules\fR" 4 +.IX Item "-Mno-modules" +Disable dependency generation for compiled module interfaces. +.IP "\fB\-MP\fR" 4 +.IX Item "-MP" +This option instructs \s-1CPP\s0 to add a phony target for each dependency +other than the main file, causing each to depend on nothing. These +dummy rules work around errors \fBmake\fR gives if you remove header +files without updating the \fIMakefile\fR to match. +.Sp +This is typical output: +.Sp +.Vb 1 +\& test.o: test.c test.h +\& +\& test.h: +.Ve +.IP "\fB\-MT\fR \fItarget\fR" 4 +.IX Item "-MT target" +Change the target of the rule emitted by dependency generation. By +default \s-1CPP\s0 takes the name of the main input file, deletes any +directory components and any file suffix such as \fB.c\fR, and +appends the platform's usual object suffix. The result is the target. +.Sp +An \fB\-MT\fR option sets the target to be exactly the string you +specify. If you want multiple targets, you can specify them as a single +argument to \fB\-MT\fR, or use multiple \fB\-MT\fR options. +.Sp +For example, \fB\-MT\ '$(objpfx)foo.o'\fR might give +.Sp +.Vb 1 +\& $(objpfx)foo.o: foo.c +.Ve +.IP "\fB\-MQ\fR \fItarget\fR" 4 +.IX Item "-MQ target" +Same as \fB\-MT\fR, but it quotes any characters which are special to +Make. \fB\-MQ\ '$(objpfx)foo.o'\fR gives +.Sp +.Vb 1 +\& $$(objpfx)foo.o: foo.c +.Ve +.Sp +The default target is automatically quoted, as if it were given with +\&\fB\-MQ\fR. +.IP "\fB\-MD\fR" 4 +.IX Item "-MD" +\&\fB\-MD\fR is equivalent to \fB\-M \-MF\fR \fIfile\fR, except that +\&\fB\-E\fR is not implied. The driver determines \fIfile\fR based on +whether an \fB\-o\fR option is given. If it is, the driver uses its +argument but with a suffix of \fI.d\fR, otherwise it takes the name +of the input file, removes any directory components and suffix, and +applies a \fI.d\fR suffix. +.Sp +If \fB\-MD\fR is used in conjunction with \fB\-E\fR, any +\&\fB\-o\fR switch is understood to specify the dependency output file, but if used without \fB\-E\fR, each \fB\-o\fR +is understood to specify a target object file. +.Sp +Since \fB\-E\fR is not implied, \fB\-MD\fR can be used to generate +a dependency output file as a side effect of the compilation process. +.IP "\fB\-MMD\fR" 4 +.IX Item "-MMD" +Like \fB\-MD\fR except mention only user header files, not system +header files. +.IP "\fB\-fpreprocessed\fR" 4 +.IX Item "-fpreprocessed" +Indicate to the preprocessor that the input file has already been +preprocessed. This suppresses things like macro expansion, trigraph +conversion, escaped newline splicing, and processing of most directives. +The preprocessor still recognizes and removes comments, so that you can +pass a file preprocessed with \fB\-C\fR to the compiler without +problems. In this mode the integrated preprocessor is little more than +a tokenizer for the front ends. +.Sp +\&\fB\-fpreprocessed\fR is implicit if the input file has one of the +extensions \fB.i\fR, \fB.ii\fR or \fB.mi\fR. These are the +extensions that \s-1GCC\s0 uses for preprocessed files created by +\&\fB\-save\-temps\fR. +.IP "\fB\-fdirectives\-only\fR" 4 +.IX Item "-fdirectives-only" +When preprocessing, handle directives, but do not expand macros. +.Sp +The option's behavior depends on the \fB\-E\fR and \fB\-fpreprocessed\fR +options. +.Sp +With \fB\-E\fR, preprocessing is limited to the handling of directives +such as \f(CW\*(C`#define\*(C'\fR, \f(CW\*(C`#ifdef\*(C'\fR, and \f(CW\*(C`#error\*(C'\fR. Other +preprocessor operations, such as macro expansion and trigraph +conversion are not performed. In addition, the \fB\-dD\fR option is +implicitly enabled. +.Sp +With \fB\-fpreprocessed\fR, predefinition of command line and most +builtin macros is disabled. Macros such as \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, which are +contextually dependent, are handled normally. This enables compilation of +files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR. +.Sp +With both \fB\-E\fR and \fB\-fpreprocessed\fR, the rules for +\&\fB\-fpreprocessed\fR take precedence. This enables full preprocessing of +files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR. +.IP "\fB\-fdollars\-in\-identifiers\fR" 4 +.IX Item "-fdollars-in-identifiers" +Accept \fB$\fR in identifiers. +.IP "\fB\-fextended\-identifiers\fR" 4 +.IX Item "-fextended-identifiers" +Accept universal character names and extended characters in +identifiers. This option is enabled by default for C99 (and later C +standard versions) and \*(C+. +.IP "\fB\-fno\-canonical\-system\-headers\fR" 4 +.IX Item "-fno-canonical-system-headers" +When preprocessing, do not shorten system header paths with canonicalization. +.IP "\fB\-fmax\-include\-depth=\fR\fIdepth\fR" 4 +.IX Item "-fmax-include-depth=depth" +Set the maximum depth of the nested #include. The default is 200. +.IP "\fB\-ftabstop=\fR\fIwidth\fR" 4 +.IX Item "-ftabstop=width" +Set the distance between tab stops. This helps the preprocessor report +correct column numbers in warnings or errors, even if tabs appear on the +line. If the value is less than 1 or greater than 100, the option is +ignored. The default is 8. +.IP "\fB\-ftrack\-macro\-expansion\fR[\fB=\fR\fIlevel\fR]" 4 +.IX Item "-ftrack-macro-expansion[=level]" +Track locations of tokens across macro expansions. This allows the +compiler to emit diagnostic about the current macro expansion stack +when a compilation error occurs in a macro expansion. Using this +option makes the preprocessor and the compiler consume more +memory. The \fIlevel\fR parameter can be used to choose the level of +precision of token location tracking thus decreasing the memory +consumption if necessary. Value \fB0\fR of \fIlevel\fR de-activates +this option. Value \fB1\fR tracks tokens locations in a +degraded mode for the sake of minimal memory overhead. In this mode +all tokens resulting from the expansion of an argument of a +function-like macro have the same location. Value \fB2\fR tracks +tokens locations completely. This value is the most memory hungry. +When this option is given no argument, the default parameter value is +\&\fB2\fR. +.Sp +Note that \f(CW\*(C`\-ftrack\-macro\-expansion=2\*(C'\fR is activated by default. +.IP "\fB\-fmacro\-prefix\-map=\fR\fIold\fR\fB=\fR\fInew\fR" 4 +.IX Item "-fmacro-prefix-map=old=new" +When preprocessing files residing in directory \fI\fIold\fI\fR, +expand the \f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_BASE_FILE_\|_\*(C'\fR macros as if the +files resided in directory \fI\fInew\fI\fR instead. This can be used +to change an absolute path to a relative path by using \fI.\fR for +\&\fInew\fR which can result in more reproducible builds that are +location independent. This option also affects +\&\f(CW\*(C`_\|_builtin_FILE()\*(C'\fR during compilation. See also +\&\fB\-ffile\-prefix\-map\fR and \fB\-fcanon\-prefix\-map\fR. +.IP "\fB\-fexec\-charset=\fR\fIcharset\fR" 4 +.IX Item "-fexec-charset=charset" +Set the execution character set, used for string and character +constants. The default is \s-1UTF\-8. \s0\fIcharset\fR can be any encoding +supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine. +.IP "\fB\-fwide\-exec\-charset=\fR\fIcharset\fR" 4 +.IX Item "-fwide-exec-charset=charset" +Set the wide execution character set, used for wide string and +character constants. The default is one of \s-1UTF\-32BE, UTF\-32LE, UTF\-16BE,\s0 +or \s-1UTF\-16LE,\s0 whichever corresponds to the width of \f(CW\*(C`wchar_t\*(C'\fR and the +big-endian or little-endian byte order being used for code generation. As +with \fB\-fexec\-charset\fR, \fIcharset\fR can be any encoding supported +by the system's \f(CW\*(C`iconv\*(C'\fR library routine; however, you will have +problems with encodings that do not fit exactly in \f(CW\*(C`wchar_t\*(C'\fR. +.IP "\fB\-finput\-charset=\fR\fIcharset\fR" 4 +.IX Item "-finput-charset=charset" +Set the input character set, used for translation from the character +set of the input file to the source character set used by \s-1GCC. \s0 If the +locale does not specify, or \s-1GCC\s0 cannot get this information from the +locale, the default is \s-1UTF\-8. \s0 This can be overridden by either the locale +or this command-line option. Currently the command-line option takes +precedence if there's a conflict. \fIcharset\fR can be any encoding +supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine. +.IP "\fB\-fworking\-directory\fR" 4 +.IX Item "-fworking-directory" +Enable generation of linemarkers in the preprocessor output that +let the compiler know the current working directory at the time of +preprocessing. When this option is enabled, the preprocessor +emits, after the initial linemarker, a second linemarker with the +current working directory followed by two slashes. \s-1GCC\s0 uses this +directory, when it's present in the preprocessed input, as the +directory emitted as the current working directory in some debugging +information formats. This option is implicitly enabled if debugging +information is enabled, but this can be inhibited with the negated +form \fB\-fno\-working\-directory\fR. If the \fB\-P\fR flag is +present in the command line, this option has no effect, since no +\&\f(CW\*(C`#line\*(C'\fR directives are emitted whatsoever. +.IP "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4 +.IX Item "-A predicate=answer" +Make an assertion with the predicate \fIpredicate\fR and answer +\&\fIanswer\fR. This form is preferred to the older form \fB\-A\fR +\&\fIpredicate\fR\fB(\fR\fIanswer\fR\fB)\fR, which is still supported, because +it does not use shell special characters. +.IP "\fB\-A \-\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4 +.IX Item "-A -predicate=answer" +Cancel an assertion with the predicate \fIpredicate\fR and answer +\&\fIanswer\fR. +.IP "\fB\-C\fR" 4 +.IX Item "-C" +Do not discard comments. All comments are passed through to the output +file, except for comments in processed directives, which are deleted +along with the directive. +.Sp +You should be prepared for side effects when using \fB\-C\fR; it +causes the preprocessor to treat comments as tokens in their own right. +For example, comments appearing at the start of what would be a +directive line have the effect of turning that line into an ordinary +source line, since the first token on the line is no longer a \fB#\fR. +.IP "\fB\-CC\fR" 4 +.IX Item "-CC" +Do not discard comments, including during macro expansion. This is +like \fB\-C\fR, except that comments contained within macros are +also passed through to the output file where the macro is expanded. +.Sp +In addition to the side effects of the \fB\-C\fR option, the +\&\fB\-CC\fR option causes all \*(C+\-style comments inside a macro +to be converted to C\-style comments. This is to prevent later use +of that macro from inadvertently commenting out the remainder of +the source line. +.Sp +The \fB\-CC\fR option is generally used to support lint comments. +.IP "\fB\-P\fR" 4 +.IX Item "-P" +Inhibit generation of linemarkers in the output from the preprocessor. +This might be useful when running the preprocessor on something that is +not C code, and will be sent to a program which might be confused by the +linemarkers. +.IP "\fB\-traditional\fR" 4 +.IX Item "-traditional" +.PD 0 +.IP "\fB\-traditional\-cpp\fR" 4 +.IX Item "-traditional-cpp" +.PD +Try to imitate the behavior of pre-standard C preprocessors, as +opposed to \s-1ISO C\s0 preprocessors. +.Sp +Note that \s-1GCC\s0 does not otherwise attempt to emulate a pre-standard +C compiler, and these options are only supported with the \fB\-E\fR +switch, or when invoking \s-1CPP\s0 explicitly. +.IP "\fB\-trigraphs\fR" 4 +.IX Item "-trigraphs" +Support \s-1ISO C\s0 trigraphs. +These are three-character sequences, all starting with \fB??\fR, that +are defined by \s-1ISO C\s0 to stand for single characters. For example, +\&\fB??/\fR stands for \fB\e\fR, so \fB'??/n'\fR is a character +constant for a newline. +.Sp +By default, \s-1GCC\s0 ignores trigraphs, but in +standard-conforming modes it converts them. See the \fB\-std\fR and +\&\fB\-ansi\fR options. +.IP "\fB\-remap\fR" 4 +.IX Item "-remap" +Enable special code to work around file systems which only permit very +short file names, such as MS-DOS. +.IP "\fB\-H\fR" 4 +.IX Item "-H" +Print the name of each header file used, in addition to other normal +activities. Each name is indented to show how deep in the +\&\fB#include\fR stack it is. Precompiled header files are also +printed, even if they are found to be invalid; an invalid precompiled +header file is printed with \fB...x\fR and a valid one with \fB...!\fR . +.IP "\fB\-d\fR\fIletters\fR" 4 +.IX Item "-dletters" +Says to make debugging dumps during compilation as specified by +\&\fIletters\fR. The flags documented here are those relevant to the +preprocessor. Other \fIletters\fR are interpreted +by the compiler proper, or reserved for future versions of \s-1GCC,\s0 and so +are silently ignored. If you specify \fIletters\fR whose behavior +conflicts, the result is undefined. +.RS 4 +.IP "\fB\-dM\fR" 4 +.IX Item "-dM" +Instead of the normal output, generate a list of \fB#define\fR +directives for all the macros defined during the execution of the +preprocessor, including predefined macros. This gives you a way of +finding out what is predefined in your version of the preprocessor. +Assuming you have no file \fIfoo.h\fR, the command +.Sp +.Vb 1 +\& touch foo.h; cpp \-dM foo.h +.Ve +.Sp +shows all the predefined macros. +.IP "\fB\-dD\fR" 4 +.IX Item "-dD" +Like \fB\-dM\fR except in two respects: it does \fInot\fR include the +predefined macros, and it outputs \fIboth\fR the \fB#define\fR +directives and the result of preprocessing. Both kinds of output go to +the standard output file. +.IP "\fB\-dN\fR" 4 +.IX Item "-dN" +Like \fB\-dD\fR, but emit only the macro names, not their expansions. +.IP "\fB\-dI\fR" 4 +.IX Item "-dI" +Output \fB#include\fR directives in addition to the result of +preprocessing. +.IP "\fB\-dU\fR" 4 +.IX Item "-dU" +Like \fB\-dD\fR except that only macros that are expanded, or whose +definedness is tested in preprocessor directives, are output; the +output is delayed until the use or test of the macro; and +\&\fB#undef\fR directives are also output for macros tested but +undefined at the time. +.RE +.RS 4 +.RE +.IP "\fB\-fdebug\-cpp\fR" 4 +.IX Item "-fdebug-cpp" +This option is only useful for debugging \s-1GCC. \s0 When used from \s-1CPP\s0 or with +\&\fB\-E\fR, it dumps debugging information about location maps. Every +token in the output is preceded by the dump of the map its location +belongs to. +.Sp +When used from \s-1GCC\s0 without \fB\-E\fR, this option has no effect. +.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" +.PD +Add the directory \fIdir\fR to the list of directories to be searched +for header files during preprocessing. +.Sp +If \fIdir\fR begins with \fB=\fR or \f(CW$SYSROOT\fR, then the \fB=\fR +or \f(CW$SYSROOT\fR is replaced by the sysroot prefix; see +\&\fB\-\-sysroot\fR and \fB\-isysroot\fR. +.Sp +Directories specified with \fB\-iquote\fR apply only to the quote +form of the directive, \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR. +Directories specified with \fB\-I\fR, \fB\-isystem\fR, +or \fB\-idirafter\fR apply to lookup for both the +\&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR and +\&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR directives. +.Sp +You can specify any number or combination of these options on the +command line to search for header files in several directories. +The lookup order is as follows: +.RS 4 +.IP "1." 4 +.IX Item "1." +For the quote form of the include directive, the directory of the current +file is searched first. +.IP "2." 4 +.IX Item "2." +For the quote form of the include directive, the directories specified +by \fB\-iquote\fR options are searched in left-to-right order, +as they appear on the command line. +.IP "3." 4 +.IX Item "3." +Directories specified with \fB\-I\fR options are scanned in +left-to-right order. +.IP "4." 4 +.IX Item "4." +Directories specified with \fB\-isystem\fR options are scanned in +left-to-right order. +.IP "5." 4 +.IX Item "5." +Standard system directories are scanned. +.IP "6." 4 +.IX Item "6." +Directories specified with \fB\-idirafter\fR options are scanned in +left-to-right order. +.RE +.RS 4 +.Sp +You can use \fB\-I\fR to override a system header +file, substituting your own version, since these directories are +searched before the standard system header file directories. +However, you should +not use this option to add directories that contain vendor-supplied +system header files; use \fB\-isystem\fR for that. +.Sp +The \fB\-isystem\fR and \fB\-idirafter\fR options also mark the directory +as a system directory, so that it gets the same special treatment that +is applied to the standard system directories. +.Sp +If a standard system include directory, or a directory specified with +\&\fB\-isystem\fR, is also specified with \fB\-I\fR, the \fB\-I\fR +option is ignored. The directory is still searched but as a +system directory at its normal position in the system include chain. +This is to ensure that \s-1GCC\s0's procedure to fix buggy system headers and +the ordering for the \f(CW\*(C`#include_next\*(C'\fR directive are not inadvertently +changed. +If you really need to change the search order for system directories, +use the \fB\-nostdinc\fR and/or \fB\-isystem\fR options. +.RE +.IP "\fB\-I\-\fR" 4 +.IX Item "-I-" +Split the include path. +This option has been deprecated. Please use \fB\-iquote\fR instead for +\&\fB\-I\fR directories before the \fB\-I\-\fR and remove the \fB\-I\-\fR +option. +.Sp +Any directories specified with \fB\-I\fR +options before \fB\-I\-\fR are searched only for headers requested with +\&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for +\&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR. If additional directories are +specified with \fB\-I\fR options after the \fB\-I\-\fR, those +directories are searched for all \fB#include\fR directives. +.Sp +In addition, \fB\-I\-\fR inhibits the use of the directory of the current +file directory as the first search directory for \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR. There is no way to override this effect of \fB\-I\-\fR. +.IP "\fB\-iprefix\fR \fIprefix\fR" 4 +.IX Item "-iprefix prefix" +Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR +options. If the prefix represents a directory, you should include the +final \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" +.PD +Append \fIdir\fR to the prefix specified previously with +\&\fB\-iprefix\fR, and add the resulting directory to the include search +path. \fB\-iwithprefixbefore\fR puts it in the same place \fB\-I\fR +would; \fB\-iwithprefix\fR puts it where \fB\-idirafter\fR would. +.IP "\fB\-isysroot\fR \fIdir\fR" 4 +.IX Item "-isysroot dir" +This option is like the \fB\-\-sysroot\fR option, but applies only to +header files (except for Darwin targets, where it applies to both header +files and libraries). See the \fB\-\-sysroot\fR option for more +information. +.IP "\fB\-imultilib\fR \fIdir\fR" 4 +.IX Item "-imultilib dir" +Use \fIdir\fR as a subdirectory of the directory containing +target-specific \*(C+ headers. +.IP "\fB\-nostdinc\fR" 4 +.IX Item "-nostdinc" +Do not search the standard system directories for header files. +Only the directories explicitly specified with \fB\-I\fR, +\&\fB\-iquote\fR, \fB\-isystem\fR, and/or \fB\-idirafter\fR +options (and the directory of the current file, if appropriate) +are searched. +.IP "\fB\-nostdinc++\fR" 4 +.IX Item "-nostdinc++" +Do not search for header files in the \*(C+\-specific standard directories, +but do still search the other standard directories. (This option is +used when building the \*(C+ library.) +.IP "\fB\-Wcomment\fR" 4 +.IX Item "-Wcomment" +.PD 0 +.IP "\fB\-Wcomments\fR" 4 +.IX Item "-Wcomments" +.PD +Warn whenever a comment-start sequence \fB/*\fR appears in a \fB/*\fR +comment, or whenever a backslash-newline appears in a \fB//\fR comment. +This warning is enabled by \fB\-Wall\fR. +.IP "\fB\-Wtrigraphs\fR" 4 +.IX Item "-Wtrigraphs" +Warn if any trigraphs are encountered that might change the meaning of +the program. Trigraphs within comments are not warned about, +except those that would form escaped newlines. +.Sp +This option is implied by \fB\-Wall\fR. If \fB\-Wall\fR is not +given, this option is still enabled unless trigraphs are enabled. To +get trigraph conversion without warnings, but get the other +\&\fB\-Wall\fR warnings, use \fB\-trigraphs \-Wall \-Wno\-trigraphs\fR. +.IP "\fB\-Wundef\fR" 4 +.IX Item "-Wundef" +Warn if an undefined identifier is evaluated in an \f(CW\*(C`#if\*(C'\fR directive. +Such identifiers are replaced with zero. +.IP "\fB\-Wexpansion\-to\-defined\fR" 4 +.IX Item "-Wexpansion-to-defined" +Warn whenever \fBdefined\fR is encountered in the expansion of a macro +(including the case where the macro is expanded by an \fB#if\fR directive). +Such usage is not portable. +This warning is also enabled by \fB\-Wpedantic\fR and \fB\-Wextra\fR. +.IP "\fB\-Wunused\-macros\fR" 4 +.IX Item "-Wunused-macros" +Warn about macros defined in the main file that are unused. A macro +is \fIused\fR if it is expanded or tested for existence at least once. +The preprocessor also warns if the macro has not been used at the +time it is redefined or undefined. +.Sp +Built-in macros, macros defined on the command line, and macros +defined in include files are not warned about. +.Sp +\&\fINote:\fR If a macro is actually used, but only used in skipped +conditional blocks, then the preprocessor reports it as unused. To avoid the +warning in such a case, you might improve the scope of the macro's +definition by, for example, moving it into the first skipped block. +Alternatively, you could provide a dummy use with something like: +.Sp +.Vb 2 +\& #if defined the_macro_causing_the_warning +\& #endif +.Ve +.IP "\fB\-Wno\-endif\-labels\fR" 4 +.IX Item "-Wno-endif-labels" +Do not warn whenever an \f(CW\*(C`#else\*(C'\fR or an \f(CW\*(C`#endif\*(C'\fR are followed by text. +This sometimes happens in older programs with code of the form +.Sp +.Vb 5 +\& #if FOO +\& ... +\& #else FOO +\& ... +\& #endif FOO +.Ve +.Sp +The second and third \f(CW\*(C`FOO\*(C'\fR should be in comments. +This warning is on by default. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +This section describes the environment variables that affect how \s-1CPP\s0 +operates. You can use them to specify directories or prefixes to use +when searching for include files, or to control dependency output. +.PP +Note that you can also specify places to search using options such as +\&\fB\-I\fR, and control dependency output with options like +\&\fB\-M\fR. These take precedence over +environment variables, which in turn take precedence over the +configuration of \s-1GCC.\s0 +.IP "\fB\s-1CPATH\s0\fR" 4 +.IX Item "CPATH" +.PD 0 +.IP "\fBC_INCLUDE_PATH\fR" 4 +.IX Item "C_INCLUDE_PATH" +.IP "\fB\s-1CPLUS_INCLUDE_PATH\s0\fR" 4 +.IX Item "CPLUS_INCLUDE_PATH" +.IP "\fB\s-1OBJC_INCLUDE_PATH\s0\fR" 4 +.IX Item "OBJC_INCLUDE_PATH" +.PD +Each variable's value is a list of directories separated by a special +character, much like \fB\s-1PATH\s0\fR, in which to look for header files. +The special character, \f(CW\*(C`PATH_SEPARATOR\*(C'\fR, is target-dependent and +determined at \s-1GCC\s0 build time. For Microsoft Windows-based targets it is a +semicolon, and for almost all other targets it is a colon. +.Sp +\&\fB\s-1CPATH\s0\fR specifies a list of directories to be searched as if +specified with \fB\-I\fR, but after any paths given with \fB\-I\fR +options on the command line. This environment variable is used +regardless of which language is being preprocessed. +.Sp +The remaining environment variables apply only when preprocessing the +particular language indicated. Each specifies a list of directories +to be searched as if specified with \fB\-isystem\fR, but after any +paths given with \fB\-isystem\fR options on the command line. +.Sp +In all these variables, an empty element instructs the compiler to +search its current working directory. Empty elements can appear at the +beginning or end of a path. For instance, if the value of +\&\fB\s-1CPATH\s0\fR is \f(CW\*(C`:/special/include\*(C'\fR, that has the same +effect as \fB\-I.\ \-I/special/include\fR. +.IP "\fB\s-1DEPENDENCIES_OUTPUT\s0\fR" 4 +.IX Item "DEPENDENCIES_OUTPUT" +If this variable is set, its value specifies how to output +dependencies for Make based on the non-system header files processed +by the compiler. System header files are ignored in the dependency +output. +.Sp +The value of \fB\s-1DEPENDENCIES_OUTPUT\s0\fR can be just a file name, in +which case the Make rules are written to that file, guessing the target +name from the source file name. Or the value can have the form +\&\fIfile\fR\fB \fR\fItarget\fR, in which case the rules are written to +file \fIfile\fR using \fItarget\fR as the target name. +.Sp +In other words, this environment variable is equivalent to combining +the options \fB\-MM\fR and \fB\-MF\fR, +with an optional \fB\-MT\fR switch too. +.IP "\fB\s-1SUNPRO_DEPENDENCIES\s0\fR" 4 +.IX Item "SUNPRO_DEPENDENCIES" +This variable is the same as \fB\s-1DEPENDENCIES_OUTPUT\s0\fR (see above), +except that system header files are not ignored, so it implies +\&\fB\-M\fR rather than \fB\-MM\fR. However, the dependence on the +main input file is omitted. +.IP "\fB\s-1SOURCE_DATE_EPOCH\s0\fR" 4 +.IX Item "SOURCE_DATE_EPOCH" +If this variable is set, its value specifies a \s-1UNIX\s0 timestamp to be +used in replacement of the current date and time in the \f(CW\*(C`_\|_DATE_\|_\*(C'\fR +and \f(CW\*(C`_\|_TIME_\|_\*(C'\fR macros, so that the embedded timestamps become +reproducible. +.Sp +The value of \fB\s-1SOURCE_DATE_EPOCH\s0\fR must be a \s-1UNIX\s0 timestamp, +defined as the number of seconds (excluding leap seconds) since +01 Jan 1970 00:00:00 represented in \s-1ASCII\s0; identical to the output of +\&\f(CW\*(C`date +%s\*(C'\fR on GNU/Linux and other systems that support the +\&\f(CW%s\fR extension in the \f(CW\*(C`date\*(C'\fR command. +.Sp +The value should be a known timestamp such as the last modification +time of the source or package and it should be set by the build +process. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7), +\&\fIgcc\fR\|(1), and the Info entries for \fIcpp\fR and \fIgcc\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1987\-2023 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +man page \fIgfdl\fR\|(7). +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). +.PP +(a) The \s-1FSF\s0's Front-Cover Text is: +.PP +.Vb 1 +\& A GNU Manual +.Ve +.PP +(b) The \s-1FSF\s0's Back-Cover Text is: +.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 |