|
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
- <html>
- <!-- Copyright (C) 1988-2020 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3 or
- any later version published by the Free Software Foundation; with the
- Invariant Sections being "Funding Free Software", the Front-Cover
- Texts being (a) (see below), and with the Back-Cover Texts being (b)
- (see below). A copy of the license is included in the section entitled
- "GNU Free Documentation License".
-
- (a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
- (b) The FSF's Back-Cover Text is:
-
- 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. -->
- <!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <title>Diagnostic Message Formatting Options (Using the GNU Compiler Collection (GCC))</title>
-
- <meta name="description" content="Diagnostic Message Formatting Options (Using the GNU Compiler Collection (GCC))">
- <meta name="keywords" content="Diagnostic Message Formatting Options (Using the GNU Compiler Collection (GCC))">
- <meta name="resource-type" content="document">
- <meta name="distribution" content="global">
- <meta name="Generator" content="makeinfo">
- <link href="index.html#Top" rel="start" title="Top">
- <link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
- <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
- <link href="Invoking-GCC.html#Invoking-GCC" rel="up" title="Invoking GCC">
- <link href="Warning-Options.html#Warning-Options" rel="next" title="Warning Options">
- <link href="Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html#Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options" rel="prev" title="Objective-C and Objective-C++ Dialect Options">
- <style type="text/css">
- <!--
- a.summary-letter {text-decoration: none}
- blockquote.indentedblock {margin-right: 0em}
- blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
- blockquote.smallquotation {font-size: smaller}
- div.display {margin-left: 3.2em}
- div.example {margin-left: 3.2em}
- div.lisp {margin-left: 3.2em}
- div.smalldisplay {margin-left: 3.2em}
- div.smallexample {margin-left: 3.2em}
- div.smalllisp {margin-left: 3.2em}
- kbd {font-style: oblique}
- pre.display {font-family: inherit}
- pre.format {font-family: inherit}
- pre.menu-comment {font-family: serif}
- pre.menu-preformatted {font-family: serif}
- pre.smalldisplay {font-family: inherit; font-size: smaller}
- pre.smallexample {font-size: smaller}
- pre.smallformat {font-family: inherit; font-size: smaller}
- pre.smalllisp {font-size: smaller}
- span.nolinebreak {white-space: nowrap}
- span.roman {font-family: initial; font-weight: normal}
- span.sansserif {font-family: sans-serif; font-weight: normal}
- ul.no-bullet {list-style: none}
- -->
- </style>
-
-
- </head>
-
- <body lang="en">
- <a name="Diagnostic-Message-Formatting-Options"></a>
- <div class="header">
- <p>
- Next: <a href="Warning-Options.html#Warning-Options" accesskey="n" rel="next">Warning Options</a>, Previous: <a href="Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html#Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options" accesskey="p" rel="prev">Objective-C and Objective-C++ Dialect Options</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <hr>
- <a name="Options-to-Control-Diagnostic-Messages-Formatting"></a>
- <h3 class="section">3.7 Options to Control Diagnostic Messages Formatting</h3>
- <a name="index-options-to-control-diagnostics-formatting"></a>
- <a name="index-diagnostic-messages"></a>
- <a name="index-message-formatting"></a>
-
- <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 compact="compact">
- <dt><code>-fmessage-length=<var>n</var></code></dt>
- <dd><a name="index-fmessage_002dlength"></a>
- <p>Try to format error messages so that they fit on lines of about
- <var>n</var> characters. If <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>#error</samp>’ and
- ‘<samp>#warning</samp>’ pre-processor directives, and the ‘<samp>deprecated</samp>’
- function/type/variable attribute. It does not however affect the
- ‘<samp>pragma GCC warning</samp>’ and ‘<samp>pragma GCC error</samp>’ pragmas.
- </p>
- </dd>
- <dt><code>-fdiagnostics-show-location=once</code></dt>
- <dd><a name="index-fdiagnostics_002dshow_002dlocation"></a>
- <p>Only meaningful in line-wrapping mode. Instructs the diagnostic messages
- reporter to emit source location information <em>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>-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><code>-fdiagnostics-color[=<var>WHEN</var>]</code></dt>
- <dt><code>-fno-diagnostics-color</code></dt>
- <dd><a name="index-fdiagnostics_002dcolor"></a>
- <a name="index-highlight_002c-color"></a>
- <a name="index-GCC_005fCOLORS-environment-variable"></a>
- <p>Use color in diagnostics. <var>WHEN</var> is ‘<samp>never</samp>’, ‘<samp>always</samp>’,
- or ‘<samp>auto</samp>’. The default depends on how the compiler has been configured,
- it can be any of the above <var>WHEN</var> options or also ‘<samp>never</samp>’
- if <code>GCC_COLORS</code> environment variable isn’t present in the environment,
- and ‘<samp>auto</samp>’ otherwise.
- ‘<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>-fdiagnostics-color</samp> and <samp>-fno-diagnostics-color</samp> are
- aliases for <samp>-fdiagnostics-color=always</samp> and
- <samp>-fdiagnostics-color=never</samp>, respectively.
- </p>
- <p>The colors are defined by the environment variable <code>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>1</samp>’ for bold,
- ‘<samp>4</samp>’ for underline,
- ‘<samp>5</samp>’ for blink,
- ‘<samp>7</samp>’ for inverse,
- ‘<samp>39</samp>’ for default foreground color,
- ‘<samp>30</samp>’ to ‘<samp>37</samp>’ for foreground colors,
- ‘<samp>90</samp>’ to ‘<samp>97</samp>’ for 16-color mode foreground colors,
- ‘<samp>38;5;0</samp>’ to ‘<samp>38;5;255</samp>’
- for 88-color and 256-color modes foreground colors,
- ‘<samp>49</samp>’ for default background color,
- ‘<samp>40</samp>’ to ‘<samp>47</samp>’ for background colors,
- ‘<samp>100</samp>’ to ‘<samp>107</samp>’ for 16-color mode background colors,
- and ‘<samp>48;5;0</samp>’ to ‘<samp>48;5;255</samp>’
- for 88-color and 256-color modes background colors.
- </p>
- <p>The default <code>GCC_COLORS</code> is
- </p><div class="smallexample">
- <pre class="smallexample">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
- </pre></div>
- <p>where ‘<samp>01;31</samp>’ is bold red, ‘<samp>01;35</samp>’ is bold magenta,
- ‘<samp>01;36</samp>’ is bold cyan, ‘<samp>32</samp>’ is green, ‘<samp>34</samp>’ is blue,
- ‘<samp>01</samp>’ is bold, and ‘<samp>31</samp>’ is red.
- Setting <code>GCC_COLORS</code> to the empty string disables colors.
- Supported capabilities are as follows.
- </p>
- <dl compact="compact">
- <dt><code>error=</code></dt>
- <dd><a name="index-error-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for error: markers.
- </p>
- </dd>
- <dt><code>warning=</code></dt>
- <dd><a name="index-warning-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for warning: markers.
- </p>
- </dd>
- <dt><code>note=</code></dt>
- <dd><a name="index-note-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for note: markers.
- </p>
- </dd>
- <dt><code>path=</code></dt>
- <dd><a name="index-path-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for colorizing paths of control-flow events as printed
- via <samp>-fdiagnostics-path-format=</samp>, such as the identifiers of
- individual events and lines indicating interprocedural calls and returns.
- </p>
- </dd>
- <dt><code>range1=</code></dt>
- <dd><a name="index-range1-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for first additional range.
- </p>
- </dd>
- <dt><code>range2=</code></dt>
- <dd><a name="index-range2-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for second additional range.
- </p>
- </dd>
- <dt><code>locus=</code></dt>
- <dd><a name="index-locus-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for location information, ‘<samp>file:line</samp>’ or
- ‘<samp>file:line:column</samp>’ etc.
- </p>
- </dd>
- <dt><code>quote=</code></dt>
- <dd><a name="index-quote-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for information printed within quotes.
- </p>
- </dd>
- <dt><code>fixit-insert=</code></dt>
- <dd><a name="index-fixit_002dinsert-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for fix-it hints suggesting text to
- be inserted or replaced.
- </p>
- </dd>
- <dt><code>fixit-delete=</code></dt>
- <dd><a name="index-fixit_002ddelete-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for fix-it hints suggesting text to
- be deleted.
- </p>
- </dd>
- <dt><code>diff-filename=</code></dt>
- <dd><a name="index-diff_002dfilename-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for filename headers within generated patches.
- </p>
- </dd>
- <dt><code>diff-hunk=</code></dt>
- <dd><a name="index-diff_002dhunk-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for the starts of hunks within generated patches.
- </p>
- </dd>
- <dt><code>diff-delete=</code></dt>
- <dd><a name="index-diff_002ddelete-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for deleted lines within generated patches.
- </p>
- </dd>
- <dt><code>diff-insert=</code></dt>
- <dd><a name="index-diff_002dinsert-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for inserted lines within generated patches.
- </p>
- </dd>
- <dt><code>type-diff=</code></dt>
- <dd><a name="index-type_002ddiff-GCC_005fCOLORS-capability"></a>
- <p>SGR substring for highlighting mismatching types within template
- arguments in the C++ frontend.
- </p></dd>
- </dl>
-
- </dd>
- <dt><code>-fdiagnostics-urls[=<var>WHEN</var>]</code></dt>
- <dd><a name="index-fdiagnostics_002durls"></a>
- <a name="index-urls"></a>
- <a name="index-GCC_005fURLS-environment-variable"></a>
- <a name="index-TERM_005fURLS-environment-variable"></a>
- <p>Use escape sequences to embed URLs in diagnostics. For example, when
- <samp>-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>WHEN</var> is ‘<samp>never</samp>’, ‘<samp>always</samp>’, or ‘<samp>auto</samp>’.
- ‘<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>WHEN</var> options.
- </p>
- <p>GCC can also be configured (via the
- <samp>--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>auto</samp>’
- if either <code>GCC_URLS</code> or <code>TERM_URLS</code> environment variables are
- present and non-empty in the environment of the compiler, or ‘<samp>never</samp>’
- if neither are.
- </p>
- <p>However, even with <samp>-fdiagnostics-urls=always</samp> the behavior is
- dependent on those environment variables:
- If <code>GCC_URLS</code> is set to empty or ‘<samp>no</samp>’, do not embed URLs in
- diagnostics. If set to ‘<samp>st</samp>’, URLs use ST escape sequences.
- If set to ‘<samp>bel</samp>’, the default, URLs use BEL escape sequences.
- Any other non-empty value enables the feature.
- If <code>GCC_URLS</code> is not set, use <code>TERM_URLS</code> as a fallback.
- Note: ST is an ANSI escape sequence, string terminator ‘<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>-fdiagnostics-urls=always</samp>.
- </p>
- </dd>
- <dt><code>-fno-diagnostics-show-option</code></dt>
- <dd><a name="index-fno_002ddiagnostics_002dshow_002doption"></a>
- <a name="index-fdiagnostics_002dshow_002doption"></a>
- <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>-fno-diagnostics-show-option</samp> flag suppresses that behavior.
- </p>
- </dd>
- <dt><code>-fno-diagnostics-show-caret</code></dt>
- <dd><a name="index-fno_002ddiagnostics_002dshow_002dcaret"></a>
- <a name="index-fdiagnostics_002dshow_002dcaret"></a>
- <p>By default, each diagnostic emitted includes the original source line
- and a caret ‘<samp>^</samp>’ indicating the column. This option suppresses this
- information. The source line is truncated to <var>n</var> characters, if
- the <samp>-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>COLUMNS</code> environment variable or, if not set, to the terminal width.
- </p>
- </dd>
- <dt><code>-fno-diagnostics-show-labels</code></dt>
- <dd><a name="index-fno_002ddiagnostics_002dshow_002dlabels"></a>
- <a name="index-fdiagnostics_002dshow_002dlabels"></a>
- <p>By default, when printing source code (via <samp>-fdiagnostics-show-caret</samp>),
- diagnostics can label ranges of source code with pertinent information, such
- as the types of expressions:
- </p>
- <div class="smallexample">
- <pre class="smallexample"> 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><code>-fno-diagnostics-show-cwe</code></dt>
- <dd><a name="index-fno_002ddiagnostics_002dshow_002dcwe"></a>
- <a name="index-fdiagnostics_002dshow_002dcwe"></a>
- <p>Diagnostic messages can optionally have an associated
- <a href="https://cwe.mitre.org/index.html">CWE</a> identifier.
- GCC itself only provides such metadata for some of the <samp>-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><code>-fno-diagnostics-show-line-numbers</code></dt>
- <dd><a name="index-fno_002ddiagnostics_002dshow_002dline_002dnumbers"></a>
- <a name="index-fdiagnostics_002dshow_002dline_002dnumbers"></a>
- <p>By default, when printing source code (via <samp>-fdiagnostics-show-caret</samp>),
- a left margin is printed, showing line numbers. This option suppresses this
- left margin.
- </p>
- </dd>
- <dt><code>-fdiagnostics-minimum-margin-width=<var>width</var></code></dt>
- <dd><a name="index-fdiagnostics_002dminimum_002dmargin_002dwidth"></a>
- <p>This option controls the minimum width of the left margin printed by
- <samp>-fdiagnostics-show-line-numbers</samp>. It defaults to 6.
- </p>
- </dd>
- <dt><code>-fdiagnostics-parseable-fixits</code></dt>
- <dd><a name="index-fdiagnostics_002dparseable_002dfixits"></a>
- <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="smallexample">
- <pre class="smallexample">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="smallexample">
- <pre class="smallexample">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><code>-fdiagnostics-generate-patch</code></dt>
- <dd><a name="index-fdiagnostics_002dgenerate_002dpatch"></a>
- <p>Print fix-it hints to stderr in unified diff format, after any diagnostics
- are printed. For example:
- </p>
- <div class="smallexample">
- <pre class="smallexample">--- 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>-fdiagnostics-color</samp>).
- </p>
- </dd>
- <dt><code>-fdiagnostics-show-template-tree</code></dt>
- <dd><a name="index-fdiagnostics_002dshow_002dtemplate_002dtree"></a>
-
- <p>In the C++ frontend, when printing diagnostics showing mismatching
- template types, such as:
- </p>
- <div class="smallexample">
- <pre class="smallexample"> could not convert 'std::map<int, std::vector<double> >()'
- from 'map<[...],vector<double>>' to 'map<[...],vector<float>>
- </pre></div>
-
- <p>the <samp>-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="smallexample">
- <pre class="smallexample"> map<
- [...],
- vector<
- [double != float]>>
- </pre></div>
-
- <p>The parts that differ are highlighted with color (“double” and
- “float” in this case).
- </p>
- </dd>
- <dt><code>-fno-elide-type</code></dt>
- <dd><a name="index-fno_002delide_002dtype"></a>
- <a name="index-felide_002dtype"></a>
- <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="smallexample">
- <pre class="smallexample"> could not convert 'std::map<int, std::vector<double> >()'
- from 'map<[...],vector<double>>' to 'map<[...],vector<float>>
- </pre></div>
-
- <p>Specifying the <samp>-fno-elide-type</samp> flag suppresses that behavior.
- This flag also affects the output of the
- <samp>-fdiagnostics-show-template-tree</samp> flag.
- </p>
- </dd>
- <dt><code>-fdiagnostics-path-format=<var>KIND</var></code></dt>
- <dd><a name="index-fdiagnostics_002dpath_002dformat"></a>
- <p>Specify how to print paths of control-flow events for diagnostics that
- have such a path associated with them.
- </p>
- <p><var>KIND</var> is ‘<samp>none</samp>’, ‘<samp>separate-events</samp>’, or ‘<samp>inline-events</samp>’,
- the default.
- </p>
- <p>‘<samp>none</samp>’ means to not print diagnostic paths.
- </p>
- <p>‘<samp>separate-events</samp>’ means to print a separate “note” diagnostic for
- each event within the diagnostic. For example:
- </p>
- <div class="smallexample">
- <pre class="smallexample">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>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="smallexample">
- <pre class="smallexample"> '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="smallexample">
- <pre class="smallexample"> '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><code>-fdiagnostics-show-path-depths</code></dt>
- <dd><a name="index-fdiagnostics_002dshow_002dpath_002ddepths"></a>
- <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>-fdiagnostics-path-format=separate-events</samp>.
- </p>
- <p>This is intended for use by GCC developers and plugin developers when
- debugging diagnostics that report interprocedural control flow.
- </p>
- </dd>
- <dt><code>-fno-show-column</code></dt>
- <dd><a name="index-fno_002dshow_002dcolumn"></a>
- <a name="index-fshow_002dcolumn"></a>
- <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>dejagnu</code>.
- </p>
- </dd>
- <dt><code>-fdiagnostics-format=<var>FORMAT</var></code></dt>
- <dd><a name="index-fdiagnostics_002dformat"></a>
- <p>Select a different format for printing diagnostics.
- <var>FORMAT</var> is ‘<samp>text</samp>’ or ‘<samp>json</samp>’.
- The default is ‘<samp>text</samp>’.
- </p>
- <p>The ‘<samp>json</samp>’ format consists of a top-level JSON array containing JSON
- objects representing the diagnostics.
- </p>
- <p>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="smallexample">
- <pre class="smallexample">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="smallexample">
- <pre class="smallexample">[
- {
- "kind": "warning",
- "locations": [
- {
- "caret": {
- "column": 3,
- "file": "misleading-indentation.c",
- "line": 15
- },
- "finish": {
- "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": {
- "column": 5,
- "file": "misleading-indentation.c",
- "line": 17
- }
- }
- ],
- "message": "...this statement, but the latter is …"
- }
- ]
- },
- …
- ]
- </pre></div>
-
- <p>where the <code>note</code> is a child of the <code>warning</code>.
- </p>
- <p>A diagnostic has a <code>kind</code>. If this is <code>warning</code>, then there is
- an <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 up
- to three positions within it: a <code>caret</code> position and optional
- <code>start</code> and <code>finish</code> positions. A location can also have
- an optional <code>label</code> string. For example, this error:
- </p>
- <div class="smallexample">
- <pre class="smallexample">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="smallexample">
- <pre class="smallexample"> {
- "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}"
- }
- ],
- "message": "invalid operands to binary + …"
- }
- </pre></div>
-
- <p>If a diagnostic contains fix-it hints, it has a <code>fixits</code> array,
- consisting of half-open intervals, similar to the output of
- <samp>-fdiagnostics-parseable-fixits</samp>. For example, this diagnostic
- with a replacement fix-it hint:
- </p>
- <div class="smallexample">
- <pre class="smallexample">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="smallexample">
- <pre class="smallexample"> {
- "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
- }
- }
- ],
- "message": "\u2018struct s\u2019 has no member named …"
- }
- </pre></div>
-
- <p>where the fix-it hint suggests replacing the text from <code>start</code> up
- to but not including <code>next</code> with <code>string</code>’s value. Deletions
- are expressed via an empty value for <code>string</code>, insertions by
- having <code>start</code> equal <code>next</code>.
- </p>
- <p>If the diagnostic has a path of control-flow events associated with it,
- it has a <code>path</code> array of objects representing the events. Each
- event object has a <code>description</code> string, a <code>location</code> object,
- along with a <code>function</code> string and a <code>depth</code> number for
- representing interprocedural paths. The <code>function</code> represents the
- current function at that event, and the <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>-fdiagnostics-path-format=</samp> might have this JSON for its path:
- </p>
- <div class="smallexample">
- <pre class="smallexample"> "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>
-
- </dd>
- </dl>
-
- <hr>
- <div class="header">
- <p>
- Next: <a href="Warning-Options.html#Warning-Options" accesskey="n" rel="next">Warning Options</a>, Previous: <a href="Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html#Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options" accesskey="p" rel="prev">Objective-C and Objective-C++ Dialect Options</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
- </div>
-
-
-
- </body>
- </html>
|
