diff options
| author | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
| commit | 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 (patch) | |
| tree | f1190704f78f04a2b0b4c977d20fe96a828377f1 /devdocs/gcc~13/diagnostic-message-formatting-options.html | |
new repository
Diffstat (limited to 'devdocs/gcc~13/diagnostic-message-formatting-options.html')
| -rw-r--r-- | devdocs/gcc~13/diagnostic-message-formatting-options.html | 398 |
1 files changed, 398 insertions, 0 deletions
diff --git a/devdocs/gcc~13/diagnostic-message-formatting-options.html b/devdocs/gcc~13/diagnostic-message-formatting-options.html new file mode 100644 index 00000000..aad486eb --- /dev/null +++ b/devdocs/gcc~13/diagnostic-message-formatting-options.html @@ -0,0 +1,398 @@ +<div class="section-level-extent" id="Diagnostic-Message-Formatting-Options"> <div class="nav-panel"> <p> Next: <a href="warning-options" accesskey="n" rel="next">Options to Request or Suppress Warnings</a>, Previous: <a href="objective-c-and-objective-c_002b_002b-dialect-options" accesskey="p" rel="prev">Options Controlling Objective-C and Objective-C++ Dialects</a>, Up: <a href="invoking-gcc" accesskey="u" rel="up">GCC Command Options</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div> <h1 class="section" id="Options-to-Control-Diagnostic-Messages-Formatting"><span>3.7 Options to Control Diagnostic Messages Formatting<a class="copiable-link" href="#Options-to-Control-Diagnostic-Messages-Formatting"> ¶</a></span></h1> <p>Traditionally, diagnostic messages have been formatted irrespective of the output device’s aspect (e.g. its width, …). You can use the options described below to control the formatting algorithm for diagnostic messages, e.g. how many characters per line, how often source location information should be reported. Note that some language front ends may not honor these options. </p> <dl class="table"> <dt> +<span><code class="code">-fmessage-length=<var class="var">n</var></code><a class="copiable-link" href="#index-fmessage-length"> ¶</a></span> +</dt> <dd> +<p>Try to format error messages so that they fit on lines of about <var class="var">n</var> characters. If <var class="var">n</var> is zero, then no line-wrapping is done; each error message appears on a single line. This is the default for all front ends. </p> <p>Note - this option also affects the display of the ‘<samp class="samp">#error</samp>’ and ‘<samp class="samp">#warning</samp>’ pre-processor directives, and the ‘<samp class="samp">deprecated</samp>’ function/type/variable attribute. It does not however affect the ‘<samp class="samp">pragma GCC warning</samp>’ and ‘<samp class="samp">pragma GCC error</samp>’ pragmas. </p> </dd> <dt><code class="code">-fdiagnostics-plain-output</code></dt> <dd> +<p>This option requests that diagnostic output look as plain as possible, which may be useful when running <code class="command">dejagnu</code> or other utilities that need to parse diagnostics output and prefer that it remain more stable over time. <samp class="option">-fdiagnostics-plain-output</samp> is currently equivalent to the following options: </p> +<div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">-fno-diagnostics-show-caret +-fno-diagnostics-show-line-numbers +-fdiagnostics-color=never +-fdiagnostics-urls=never +-fdiagnostics-path-format=separate-events</pre> +</div> <p>In the future, if GCC changes the default appearance of its diagnostics, the corresponding option to disable the new behavior will be added to this list. </p> </dd> <dt> +<span><code class="code">-fdiagnostics-show-location=once</code><a class="copiable-link" href="#index-fdiagnostics-show-location"> ¶</a></span> +</dt> <dd> +<p>Only meaningful in line-wrapping mode. Instructs the diagnostic messages reporter to emit source location information <em class="emph">once</em>; that is, in case the message is too long to fit on a single physical line and has to be wrapped, the source location won’t be emitted (as prefix) again, over and over, in subsequent continuation lines. This is the default behavior. </p> </dd> <dt><code class="code">-fdiagnostics-show-location=every-line</code></dt> <dd> +<p>Only meaningful in line-wrapping mode. Instructs the diagnostic messages reporter to emit the same source location information (as prefix) for physical lines that result from the process of breaking a message which is too long to fit on a single line. </p> </dd> <dt> + <span><code class="code">-fdiagnostics-color[=<var class="var">WHEN</var>]</code><a class="copiable-link" href="#index-fdiagnostics-color"> ¶</a></span> +</dt> <dt><code class="code">-fno-diagnostics-color</code></dt> <dd> +<p>Use color in diagnostics. <var class="var">WHEN</var> is ‘<samp class="samp">never</samp>’, ‘<samp class="samp">always</samp>’, or ‘<samp class="samp">auto</samp>’. The default depends on how the compiler has been configured, it can be any of the above <var class="var">WHEN</var> options or also ‘<samp class="samp">never</samp>’ if <code class="env">GCC_COLORS</code> environment variable isn’t present in the environment, and ‘<samp class="samp">auto</samp>’ otherwise. ‘<samp class="samp">auto</samp>’ makes GCC use color only when the standard error is a terminal, and when not executing in an emacs shell. The forms <samp class="option">-fdiagnostics-color</samp> and <samp class="option">-fno-diagnostics-color</samp> are aliases for <samp class="option">-fdiagnostics-color=always</samp> and <samp class="option">-fdiagnostics-color=never</samp>, respectively. </p> <p>The colors are defined by the environment variable <code class="env">GCC_COLORS</code>. Its value is a colon-separated list of capabilities and Select Graphic Rendition (SGR) substrings. SGR commands are interpreted by the terminal or terminal emulator. (See the section in the documentation of your text terminal for permitted values and their meanings as character attributes.) These substring values are integers in decimal representation and can be concatenated with semicolons. Common values to concatenate include ‘<samp class="samp">1</samp>’ for bold, ‘<samp class="samp">4</samp>’ for underline, ‘<samp class="samp">5</samp>’ for blink, ‘<samp class="samp">7</samp>’ for inverse, ‘<samp class="samp">39</samp>’ for default foreground color, ‘<samp class="samp">30</samp>’ to ‘<samp class="samp">37</samp>’ for foreground colors, ‘<samp class="samp">90</samp>’ to ‘<samp class="samp">97</samp>’ for 16-color mode foreground colors, ‘<samp class="samp">38;5;0</samp>’ to ‘<samp class="samp">38;5;255</samp>’ for 88-color and 256-color modes foreground colors, ‘<samp class="samp">49</samp>’ for default background color, ‘<samp class="samp">40</samp>’ to ‘<samp class="samp">47</samp>’ for background colors, ‘<samp class="samp">100</samp>’ to ‘<samp class="samp">107</samp>’ for 16-color mode background colors, and ‘<samp class="samp">48;5;0</samp>’ to ‘<samp class="samp">48;5;255</samp>’ for 88-color and 256-color modes background colors. </p> <p>The default <code class="env">GCC_COLORS</code> is </p> +<div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">error=01;31:warning=01;35:note=01;36:range1=32:range2=34:locus=01:\ +quote=01:path=01;36:fixit-insert=32:fixit-delete=31:\ +diff-filename=01:diff-hunk=32:diff-delete=31:diff-insert=32:\ +type-diff=01;32:fnname=01;32:targs=35</pre> +</div> <p>where ‘<samp class="samp">01;31</samp>’ is bold red, ‘<samp class="samp">01;35</samp>’ is bold magenta, ‘<samp class="samp">01;36</samp>’ is bold cyan, ‘<samp class="samp">32</samp>’ is green, ‘<samp class="samp">34</samp>’ is blue, ‘<samp class="samp">01</samp>’ is bold, and ‘<samp class="samp">31</samp>’ is red. Setting <code class="env">GCC_COLORS</code> to the empty string disables colors. Supported capabilities are as follows. </p> <dl class="table"> <dt> +<span><code class="code">error=</code><a class="copiable-link" href="#index-error-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for error: markers. </p> </dd> <dt> +<span><code class="code">warning=</code><a class="copiable-link" href="#index-warning-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for warning: markers. </p> </dd> <dt> +<span><code class="code">note=</code><a class="copiable-link" href="#index-note-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for note: markers. </p> </dd> <dt> +<span><code class="code">path=</code><a class="copiable-link" href="#index-path-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for colorizing paths of control-flow events as printed via <samp class="option">-fdiagnostics-path-format=</samp>, such as the identifiers of individual events and lines indicating interprocedural calls and returns. </p> </dd> <dt> +<span><code class="code">range1=</code><a class="copiable-link" href="#index-range1-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for first additional range. </p> </dd> <dt> +<span><code class="code">range2=</code><a class="copiable-link" href="#index-range2-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for second additional range. </p> </dd> <dt> +<span><code class="code">locus=</code><a class="copiable-link" href="#index-locus-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for location information, ‘<samp class="samp">file:line</samp>’ or ‘<samp class="samp">file:line:column</samp>’ etc. </p> </dd> <dt> +<span><code class="code">quote=</code><a class="copiable-link" href="#index-quote-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for information printed within quotes. </p> </dd> <dt> +<span><code class="code">fnname=</code><a class="copiable-link" href="#index-fnname-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for names of C++ functions. </p> </dd> <dt> +<span><code class="code">targs=</code><a class="copiable-link" href="#index-targs-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for C++ function template parameter bindings. </p> </dd> <dt> +<span><code class="code">fixit-insert=</code><a class="copiable-link" href="#index-fixit-insert-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for fix-it hints suggesting text to be inserted or replaced. </p> </dd> <dt> +<span><code class="code">fixit-delete=</code><a class="copiable-link" href="#index-fixit-delete-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for fix-it hints suggesting text to be deleted. </p> </dd> <dt> +<span><code class="code">diff-filename=</code><a class="copiable-link" href="#index-diff-filename-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for filename headers within generated patches. </p> </dd> <dt> +<span><code class="code">diff-hunk=</code><a class="copiable-link" href="#index-diff-hunk-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for the starts of hunks within generated patches. </p> </dd> <dt> +<span><code class="code">diff-delete=</code><a class="copiable-link" href="#index-diff-delete-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for deleted lines within generated patches. </p> </dd> <dt> +<span><code class="code">diff-insert=</code><a class="copiable-link" href="#index-diff-insert-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd> +<p>SGR substring for inserted lines within generated patches. </p> </dd> <dt> +<span><code class="code">type-diff=</code><a class="copiable-link" href="#index-type-diff-GCC_005fCOLORS-capability"> ¶</a></span> +</dt> <dd><p>SGR substring for highlighting mismatching types within template arguments in the C++ frontend. </p></dd> </dl> </dd> <dt> + <span><code class="code">-fdiagnostics-urls[=<var class="var">WHEN</var>]</code><a class="copiable-link" href="#index-fdiagnostics-urls"> ¶</a></span> +</dt> <dd> +<p>Use escape sequences to embed URLs in diagnostics. For example, when <samp class="option">-fdiagnostics-show-option</samp> emits text showing the command-line option controlling a diagnostic, embed a URL for documentation of that option. </p> <p><var class="var">WHEN</var> is ‘<samp class="samp">never</samp>’, ‘<samp class="samp">always</samp>’, or ‘<samp class="samp">auto</samp>’. ‘<samp class="samp">auto</samp>’ makes GCC use URL escape sequences only when the standard error is a terminal, and when not executing in an emacs shell or any graphical terminal which is known to be incompatible with this feature, see below. </p> <p>The default depends on how the compiler has been configured. It can be any of the above <var class="var">WHEN</var> options. </p> <p>GCC can also be configured (via the <samp class="option">--with-diagnostics-urls=auto-if-env</samp> configure-time option) so that the default is affected by environment variables. Under such a configuration, GCC defaults to using ‘<samp class="samp">auto</samp>’ if either <code class="env">GCC_URLS</code> or <code class="env">TERM_URLS</code> environment variables are present and non-empty in the environment of the compiler, or ‘<samp class="samp">never</samp>’ if neither are. </p> <p>However, even with <samp class="option">-fdiagnostics-urls=always</samp> the behavior is dependent on those environment variables: If <code class="env">GCC_URLS</code> is set to empty or ‘<samp class="samp">no</samp>’, do not embed URLs in diagnostics. If set to ‘<samp class="samp">st</samp>’, URLs use ST escape sequences. If set to ‘<samp class="samp">bel</samp>’, the default, URLs use BEL escape sequences. Any other non-empty value enables the feature. If <code class="env">GCC_URLS</code> is not set, use <code class="env">TERM_URLS</code> as a fallback. Note: ST is an ANSI escape sequence, string terminator ‘<samp class="samp">ESC \</samp>’, BEL is an ASCII character, CTRL-G that usually sounds like a beep. </p> <p>At this time GCC tries to detect also a few terminals that are known to not implement the URL feature, and have bugs or at least had bugs in some versions that are still in use, where the URL escapes are likely to misbehave, i.e. print garbage on the screen. That list is currently xfce4-terminal, certain known to be buggy gnome-terminal versions, the linux console, and mingw. This check can be skipped with the <samp class="option">-fdiagnostics-urls=always</samp>. </p> </dd> <dt> + <span><code class="code">-fno-diagnostics-show-option</code><a class="copiable-link" href="#index-fno-diagnostics-show-option"> ¶</a></span> +</dt> <dd> +<p>By default, each diagnostic emitted includes text indicating the command-line option that directly controls the diagnostic (if such an option is known to the diagnostic machinery). Specifying the <samp class="option">-fno-diagnostics-show-option</samp> flag suppresses that behavior. </p> </dd> <dt> + <span><code class="code">-fno-diagnostics-show-caret</code><a class="copiable-link" href="#index-fno-diagnostics-show-caret"> ¶</a></span> +</dt> <dd> +<p>By default, each diagnostic emitted includes the original source line and a caret ‘<samp class="samp">^</samp>’ indicating the column. This option suppresses this information. The source line is truncated to <var class="var">n</var> characters, if the <samp class="option">-fmessage-length=n</samp> option is given. When the output is done to the terminal, the width is limited to the width given by the <code class="env">COLUMNS</code> environment variable or, if not set, to the terminal width. </p> </dd> <dt> + <span><code class="code">-fno-diagnostics-show-labels</code><a class="copiable-link" href="#index-fno-diagnostics-show-labels"> ¶</a></span> +</dt> <dd> +<p>By default, when printing source code (via <samp class="option">-fdiagnostics-show-caret</samp>), diagnostics can label ranges of source code with pertinent information, such as the types of expressions: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">printf ("foo %s bar", long_i + long_j); + ~^ ~~~~~~~~~~~~~~~ + | | + char * long int</pre> +</div> <p>This option suppresses the printing of these labels (in the example above, the vertical bars and the “char *” and “long int” text). </p> </dd> <dt> + <span><code class="code">-fno-diagnostics-show-cwe</code><a class="copiable-link" href="#index-fno-diagnostics-show-cwe"> ¶</a></span> +</dt> <dd> +<p>Diagnostic messages can optionally have an associated <a class="uref" href="https://cwe.mitre.org/index.html">CWE</a> identifier. GCC itself only provides such metadata for some of the <samp class="option">-fanalyzer</samp> diagnostics. GCC plugins may also provide diagnostics with such metadata. By default, if this information is present, it will be printed with the diagnostic. This option suppresses the printing of this metadata. </p> </dd> <dt> + <span><code class="code">-fno-diagnostics-show-rules</code><a class="copiable-link" href="#index-fno-diagnostics-show-rules"> ¶</a></span> +</dt> <dd> +<p>Diagnostic messages can optionally have rules associated with them, such as from a coding standard, or a specification. GCC itself does not do this for any of its diagnostics, but plugins may do so. By default, if this information is present, it will be printed with the diagnostic. This option suppresses the printing of this metadata. </p> </dd> <dt> + <span><code class="code">-fno-diagnostics-show-line-numbers</code><a class="copiable-link" href="#index-fno-diagnostics-show-line-numbers"> ¶</a></span> +</dt> <dd> +<p>By default, when printing source code (via <samp class="option">-fdiagnostics-show-caret</samp>), a left margin is printed, showing line numbers. This option suppresses this left margin. </p> </dd> <dt> +<span><code class="code">-fdiagnostics-minimum-margin-width=<var class="var">width</var></code><a class="copiable-link" href="#index-fdiagnostics-minimum-margin-width"> ¶</a></span> +</dt> <dd> +<p>This option controls the minimum width of the left margin printed by <samp class="option">-fdiagnostics-show-line-numbers</samp>. It defaults to 6. </p> </dd> <dt> +<span><code class="code">-fdiagnostics-parseable-fixits</code><a class="copiable-link" href="#index-fdiagnostics-parseable-fixits"> ¶</a></span> +</dt> <dd> +<p>Emit fix-it hints in a machine-parseable format, suitable for consumption by IDEs. For each fix-it, a line will be printed after the relevant diagnostic, starting with the string “fix-it:”. For example: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">fix-it:"test.c":{45:3-45:21}:"gtk_widget_show_all"</pre> +</div> <p>The location is expressed as a half-open range, expressed as a count of bytes, starting at byte 1 for the initial column. In the above example, bytes 3 through 20 of line 45 of “test.c” are to be replaced with the given string: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">00000000011111111112222222222 +12345678901234567890123456789 + gtk_widget_showall (dlg); + ^^^^^^^^^^^^^^^^^^ + gtk_widget_show_all</pre> +</div> <p>The filename and replacement string escape backslash as “\\", tab as “\t”, newline as “\n”, double quotes as “\"”, non-printable characters as octal (e.g. vertical tab as “\013”). </p> <p>An empty replacement string indicates that the given range is to be removed. An empty range (e.g. “45:3-45:3”) indicates that the string is to be inserted at the given position. </p> </dd> <dt> +<span><code class="code">-fdiagnostics-generate-patch</code><a class="copiable-link" href="#index-fdiagnostics-generate-patch"> ¶</a></span> +</dt> <dd> +<p>Print fix-it hints to stderr in unified diff format, after any diagnostics are printed. For example: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">--- test.c ++++ test.c +@ -42,5 +42,5 @ + + void show_cb(GtkDialog *dlg) + { +- gtk_widget_showall(dlg); ++ gtk_widget_show_all(dlg); + }</pre> +</div> <p>The diff may or may not be colorized, following the same rules as for diagnostics (see <samp class="option">-fdiagnostics-color</samp>). </p> </dd> <dt> +<span><code class="code">-fdiagnostics-show-template-tree</code><a class="copiable-link" href="#index-fdiagnostics-show-template-tree"> ¶</a></span> +</dt> <dd> <p>In the C++ frontend, when printing diagnostics showing mismatching template types, such as: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">could not convert 'std::map<int, std::vector<double> >()' + from 'map<[...],vector<double>>' to 'map<[...],vector<float>></pre> +</div> <p>the <samp class="option">-fdiagnostics-show-template-tree</samp> flag enables printing a tree-like structure showing the common and differing parts of the types, such as: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">map< + [...], + vector< + [double != float]>></pre> +</div> <p>The parts that differ are highlighted with color (“double” and “float” in this case). </p> </dd> <dt> + <span><code class="code">-fno-elide-type</code><a class="copiable-link" href="#index-fno-elide-type"> ¶</a></span> +</dt> <dd> +<p>By default when the C++ frontend prints diagnostics showing mismatching template types, common parts of the types are printed as “[...]” to simplify the error message. For example: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">could not convert 'std::map<int, std::vector<double> >()' + from 'map<[...],vector<double>>' to 'map<[...],vector<float>></pre> +</div> <p>Specifying the <samp class="option">-fno-elide-type</samp> flag suppresses that behavior. This flag also affects the output of the <samp class="option">-fdiagnostics-show-template-tree</samp> flag. </p> </dd> <dt> +<span><code class="code">-fdiagnostics-path-format=<var class="var">KIND</var></code><a class="copiable-link" href="#index-fdiagnostics-path-format"> ¶</a></span> +</dt> <dd> +<p>Specify how to print paths of control-flow events for diagnostics that have such a path associated with them. </p> <p><var class="var">KIND</var> is ‘<samp class="samp">none</samp>’, ‘<samp class="samp">separate-events</samp>’, or ‘<samp class="samp">inline-events</samp>’, the default. </p> <p>‘<samp class="samp">none</samp>’ means to not print diagnostic paths. </p> <p>‘<samp class="samp">separate-events</samp>’ means to print a separate “note” diagnostic for each event within the diagnostic. For example: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">test.c:29:5: error: passing NULL as argument 1 to 'PyList_Append' which requires a non-NULL parameter +test.c:25:10: note: (1) when 'PyList_New' fails, returning NULL +test.c:27:3: note: (2) when 'i < count' +test.c:29:5: note: (3) when calling 'PyList_Append', passing NULL from (1) as argument 1</pre> +</div> <p>‘<samp class="samp">inline-events</samp>’ means to print the events “inline” within the source code. This view attempts to consolidate the events into runs of sufficiently-close events, printing them as labelled ranges within the source. </p> <p>For example, the same events as above might be printed as: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">'test': events 1-3 + | + | 25 | list = PyList_New(0); + | | ^~~~~~~~~~~~~ + | | | + | | (1) when 'PyList_New' fails, returning NULL + | 26 | + | 27 | for (i = 0; i < count; i++) { + | | ~~~ + | | | + | | (2) when 'i < count' + | 28 | item = PyLong_FromLong(random()); + | 29 | PyList_Append(list, item); + | | ~~~~~~~~~~~~~~~~~~~~~~~~~ + | | | + | | (3) when calling 'PyList_Append', passing NULL from (1) as argument 1 + |</pre> +</div> <p>Interprocedural control flow is shown by grouping the events by stack frame, and using indentation to show how stack frames are nested, pushed, and popped. </p> <p>For example: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">'test': events 1-2 + | + | 133 | { + | | ^ + | | | + | | (1) entering 'test' + | 134 | boxed_int *obj = make_boxed_int (i); + | | ~~~~~~~~~~~~~~~~~~ + | | | + | | (2) calling 'make_boxed_int' + | + +--> 'make_boxed_int': events 3-4 + | + | 120 | { + | | ^ + | | | + | | (3) entering 'make_boxed_int' + | 121 | boxed_int *result = (boxed_int *)wrapped_malloc (sizeof (boxed_int)); + | | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + | | | + | | (4) calling 'wrapped_malloc' + | + +--> 'wrapped_malloc': events 5-6 + | + | 7 | { + | | ^ + | | | + | | (5) entering 'wrapped_malloc' + | 8 | return malloc (size); + | | ~~~~~~~~~~~~~ + | | | + | | (6) calling 'malloc' + | + <-------------+ + | + 'test': event 7 + | + | 138 | free_boxed_int (obj); + | | ^~~~~~~~~~~~~~~~~~~~ + | | | + | | (7) calling 'free_boxed_int' + | +(etc)</pre> +</div> </dd> <dt> +<span><code class="code">-fdiagnostics-show-path-depths</code><a class="copiable-link" href="#index-fdiagnostics-show-path-depths"> ¶</a></span> +</dt> <dd> +<p>This option provides additional information when printing control-flow paths associated with a diagnostic. </p> <p>If this is option is provided then the stack depth will be printed for each run of events within <samp class="option">-fdiagnostics-path-format=inline-events</samp>. If provided with <samp class="option">-fdiagnostics-path-format=separate-events</samp>, then the stack depth and function declaration will be appended when printing each event. </p> <p>This is intended for use by GCC developers and plugin developers when debugging diagnostics that report interprocedural control flow. </p> </dd> <dt> + <span><code class="code">-fno-show-column</code><a class="copiable-link" href="#index-fno-show-column"> ¶</a></span> +</dt> <dd> +<p>Do not print column numbers in diagnostics. This may be necessary if diagnostics are being scanned by a program that does not understand the column numbers, such as <code class="command">dejagnu</code>. </p> </dd> <dt> +<span><code class="code">-fdiagnostics-column-unit=<var class="var">UNIT</var></code><a class="copiable-link" href="#index-fdiagnostics-column-unit"> ¶</a></span> +</dt> <dd> +<p>Select the units for the column number. This affects traditional diagnostics (in the absence of <samp class="option">-fno-show-column</samp>), as well as JSON format diagnostics if requested. </p> <p>The default <var class="var">UNIT</var>, ‘<samp class="samp">display</samp>’, considers the number of display columns occupied by each character. This may be larger than the number of bytes required to encode the character, in the case of tab characters, or it may be smaller, in the case of multibyte characters. For example, the character “GREEK SMALL LETTER PI (U+03C0)” occupies one display column, and its UTF-8 encoding requires two bytes; the character “SLIGHTLY SMILING FACE (U+1F642)” occupies two display columns, and its UTF-8 encoding requires four bytes. </p> <p>Setting <var class="var">UNIT</var> to ‘<samp class="samp">byte</samp>’ changes the column number to the raw byte count in all cases, as was traditionally output by GCC prior to version 11.1.0. </p> </dd> <dt> +<span><code class="code">-fdiagnostics-column-origin=<var class="var">ORIGIN</var></code><a class="copiable-link" href="#index-fdiagnostics-column-origin"> ¶</a></span> +</dt> <dd> +<p>Select the origin for column numbers, i.e. the column number assigned to the first column. The default value of 1 corresponds to traditional GCC behavior and to the GNU style guide. Some utilities may perform better with an origin of 0; any non-negative value may be specified. </p> </dd> <dt> +<span><code class="code">-fdiagnostics-escape-format=<var class="var">FORMAT</var></code><a class="copiable-link" href="#index-fdiagnostics-escape-format"> ¶</a></span> +</dt> <dd> +<p>When GCC prints pertinent source lines for a diagnostic it normally attempts to print the source bytes directly. However, some diagnostics relate to encoding issues in the source file, such as malformed UTF-8, or issues with Unicode normalization. These diagnostics are flagged so that GCC will escape bytes that are not printable ASCII when printing their pertinent source lines. </p> <p>This option controls how such bytes should be escaped. </p> <p>The default <var class="var">FORMAT</var>, ‘<samp class="samp">unicode</samp>’ displays Unicode characters that are not printable ASCII in the form ‘<samp class="samp"><U+XXXX></samp>’, and bytes that do not correspond to a Unicode character validly-encoded in UTF-8-encoded will be displayed as hexadecimal in the form ‘<samp class="samp"><XX></samp>’. </p> <p>For example, a source line containing the string ‘<samp class="samp">before</samp>’ followed by the Unicode character U+03C0 (“GREEK SMALL LETTER PI”, with UTF-8 encoding 0xCF 0x80) followed by the byte 0xBF (a stray UTF-8 trailing byte), followed by the string ‘<samp class="samp">after</samp>’ will be printed for such a diagnostic as: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">before<U+03C0><BF>after</pre> +</div> <p>Setting <var class="var">FORMAT</var> to ‘<samp class="samp">bytes</samp>’ will display all non-printable-ASCII bytes in the form ‘<samp class="samp"><XX></samp>’, thus showing the underlying encoding of non-ASCII Unicode characters. For the example above, the following will be printed: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">before<CF><80><BF>after</pre> +</div> </dd> <dt> +<span><code class="code">-fdiagnostics-format=<var class="var">FORMAT</var></code><a class="copiable-link" href="#index-fdiagnostics-format"> ¶</a></span> +</dt> <dd> +<p>Select a different format for printing diagnostics. <var class="var">FORMAT</var> is ‘<samp class="samp">text</samp>’, ‘<samp class="samp">sarif-stderr</samp>’, ‘<samp class="samp">sarif-file</samp>’, ‘<samp class="samp">json</samp>’, ‘<samp class="samp">json-stderr</samp>’, or ‘<samp class="samp">json-file</samp>’. </p> <p>The default is ‘<samp class="samp">text</samp>’. </p> <p>The ‘<samp class="samp">sarif-stderr</samp>’ and ‘<samp class="samp">sarif-file</samp>’ formats both emit diagnostics in SARIF Version 2.1.0 format, either to stderr, or to a file named <samp class="file"><var class="var">source</var>.sarif</samp>, respectively. </p> <p>The ‘<samp class="samp">json</samp>’ format is a synonym for ‘<samp class="samp">json-stderr</samp>’. The ‘<samp class="samp">json-stderr</samp>’ and ‘<samp class="samp">json-file</samp>’ formats are identical, apart from where the JSON is emitted to - with the former, the JSON is emitted to stderr, whereas with ‘<samp class="samp">json-file</samp>’ it is written to <samp class="file"><var class="var">source</var>.gcc.json</samp>. </p> <p>The emitted JSON consists of a top-level JSON array containing JSON objects representing the diagnostics. The JSON is emitted as one line, without formatting; the examples below have been formatted for clarity. </p> <p>Diagnostics can have child diagnostics. For example, this error and note: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">misleading-indentation.c:15:3: warning: this 'if' clause does not + guard... [-Wmisleading-indentation] + 15 | if (flag) + | ^~ +misleading-indentation.c:17:5: note: ...this statement, but the latter + is misleadingly indented as if it were guarded by the 'if' + 17 | y = 2; + | ^</pre> +</div> <p>might be printed in JSON form (after formatting) like this: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">[ + { + "kind": "warning", + "locations": [ + { + "caret": { + "display-column": 3, + "byte-column": 3, + "column": 3, + "file": "misleading-indentation.c", + "line": 15 + }, + "finish": { + "display-column": 4, + "byte-column": 4, + "column": 4, + "file": "misleading-indentation.c", + "line": 15 + } + } + ], + "message": "this \u2018if\u2019 clause does not guard...", + "option": "-Wmisleading-indentation", + "option_url": "https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wmisleading-indentation", + "children": [ + { + "kind": "note", + "locations": [ + { + "caret": { + "display-column": 5, + "byte-column": 5, + "column": 5, + "file": "misleading-indentation.c", + "line": 17 + } + } + ], + "escape-source": false, + "message": "...this statement, but the latter is …" + } + ] + "escape-source": false, + "column-origin": 1, + } +]</pre> +</div> <p>where the <code class="code">note</code> is a child of the <code class="code">warning</code>. </p> <p>A diagnostic has a <code class="code">kind</code>. If this is <code class="code">warning</code>, then there is an <code class="code">option</code> key describing the command-line option controlling the warning. </p> <p>A diagnostic can contain zero or more locations. Each location has an optional <code class="code">label</code> string and up to three positions within it: a <code class="code">caret</code> position and optional <code class="code">start</code> and <code class="code">finish</code> positions. A position is described by a <code class="code">file</code> name, a <code class="code">line</code> number, and three numbers indicating a column position: </p> +<ul class="itemize mark-bullet"> <li> +<code class="code">display-column</code> counts display columns, accounting for tabs and multibyte characters. </li> +<li> +<code class="code">byte-column</code> counts raw bytes. </li> +<li> +<code class="code">column</code> is equal to one of the previous two, as dictated by the <samp class="option">-fdiagnostics-column-unit</samp> option. </li> +</ul> <p>All three columns are relative to the origin specified by <samp class="option">-fdiagnostics-column-origin</samp>, which is typically equal to 1 but may be set, for instance, to 0 for compatibility with other utilities that number columns from 0. The column origin is recorded in the JSON output in the <code class="code">column-origin</code> tag. In the remaining examples below, the extra column number outputs have been omitted for brevity. </p> <p>For example, this error: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">bad-binary-ops.c:64:23: error: invalid operands to binary + (have 'S' {aka + 'struct s'} and 'T' {aka 'struct t'}) + 64 | return callee_4a () + callee_4b (); + | ~~~~~~~~~~~~ ^ ~~~~~~~~~~~~ + | | | + | | T {aka struct t} + | S {aka struct s}</pre> +</div> <p>has three locations. Its primary location is at the “+” token at column 23. It has two secondary locations, describing the left and right-hand sides of the expression, which have labels. It might be printed in JSON form as: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">{ + "children": [], + "kind": "error", + "locations": [ + { + "caret": { + "column": 23, "file": "bad-binary-ops.c", "line": 64 + } + }, + { + "caret": { + "column": 10, "file": "bad-binary-ops.c", "line": 64 + }, + "finish": { + "column": 21, "file": "bad-binary-ops.c", "line": 64 + }, + "label": "S {aka struct s}" + }, + { + "caret": { + "column": 25, "file": "bad-binary-ops.c", "line": 64 + }, + "finish": { + "column": 36, "file": "bad-binary-ops.c", "line": 64 + }, + "label": "T {aka struct t}" + } + ], + "escape-source": false, + "message": "invalid operands to binary + …" +}</pre> +</div> <p>If a diagnostic contains fix-it hints, it has a <code class="code">fixits</code> array, consisting of half-open intervals, similar to the output of <samp class="option">-fdiagnostics-parseable-fixits</samp>. For example, this diagnostic with a replacement fix-it hint: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">demo.c:8:15: error: 'struct s' has no member named 'colour'; did you + mean 'color'? + 8 | return ptr->colour; + | ^~~~~~ + | color</pre> +</div> <p>might be printed in JSON form as: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">{ + "children": [], + "fixits": [ + { + "next": { + "column": 21, + "file": "demo.c", + "line": 8 + }, + "start": { + "column": 15, + "file": "demo.c", + "line": 8 + }, + "string": "color" + } + ], + "kind": "error", + "locations": [ + { + "caret": { + "column": 15, + "file": "demo.c", + "line": 8 + }, + "finish": { + "column": 20, + "file": "demo.c", + "line": 8 + } + } + ], + "escape-source": false, + "message": "\u2018struct s\u2019 has no member named …" +}</pre> +</div> <p>where the fix-it hint suggests replacing the text from <code class="code">start</code> up to but not including <code class="code">next</code> with <code class="code">string</code>’s value. Deletions are expressed via an empty value for <code class="code">string</code>, insertions by having <code class="code">start</code> equal <code class="code">next</code>. </p> <p>If the diagnostic has a path of control-flow events associated with it, it has a <code class="code">path</code> array of objects representing the events. Each event object has a <code class="code">description</code> string, a <code class="code">location</code> object, along with a <code class="code">function</code> string and a <code class="code">depth</code> number for representing interprocedural paths. The <code class="code">function</code> represents the current function at that event, and the <code class="code">depth</code> represents the stack depth relative to some baseline: the higher, the more frames are within the stack. </p> <p>For example, the intraprocedural example shown for <samp class="option">-fdiagnostics-path-format=</samp> might have this JSON for its path: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">"path": [ + { + "depth": 0, + "description": "when 'PyList_New' fails, returning NULL", + "function": "test", + "location": { + "column": 10, + "file": "test.c", + "line": 25 + } + }, + { + "depth": 0, + "description": "when 'i < count'", + "function": "test", + "location": { + "column": 3, + "file": "test.c", + "line": 27 + } + }, + { + "depth": 0, + "description": "when calling 'PyList_Append', passing NULL from (1) as argument 1", + "function": "test", + "location": { + "column": 5, + "file": "test.c", + "line": 29 + } + } +]</pre> +</div> <p>Diagnostics have a boolean attribute <code class="code">escape-source</code>, hinting whether non-ASCII bytes should be escaped when printing the pertinent lines of source code (<code class="code">true</code> for diagnostics involving source encoding issues). </p> </dd> </dl> </div> <div class="nav-panel"> <p> Next: <a href="warning-options">Options to Request or Suppress Warnings</a>, Previous: <a href="objective-c-and-objective-c_002b_002b-dialect-options">Options Controlling Objective-C and Objective-C++ Dialects</a>, Up: <a href="invoking-gcc">GCC Command Options</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div><div class="_attribution"> + <p class="_attribution-p"> + © Free Software Foundation<br>Licensed under the GNU Free Documentation License, Version 1.3.<br> + <a href="https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Diagnostic-Message-Formatting-Options.html" class="_attribution-link">https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Diagnostic-Message-Formatting-Options.html</a> + </p> +</div> |