Debian Codegraph @

gcc/doc/libgdiagnostics/topics/message-formatting.rst

raw
1 .. Copyright (C) 2024-2025 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <[email protected]>
3
4 This is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see
16 <https://www.gnu.org/licenses/>.
17
18 .. default-domain:: c
19
20 Message formatting
21 ==================
22
23 Various libgdiagnostics entrypoints take a format string and
24 variadic arguments.
25
26 The format strings take codes prefixed by ``%``, or ``%q`` to put
27 the result in quotes. For example::
28
29 "hello %s", "world"
30
31 would print::
32
33 hello world
34
35 whereas::
36
37 "hello %qs", "world"
38
39 would print::
40
41 hello `world'
42
43 where ```world'`` would be displayed in bold if colorization were enabled
44 in the terminal.
45
46 The following format specifiers are accepted:
47
48
49 Numbers
50 *******
51
52 ``d`` and ``i`` (``signed int``), ``u`` (``unsigned int``)
53 ``%d``, ``%i``, and ``%u`` print integers in base ten. For example::
54
55 "the answer is %i", 42
56
57 would print::
58
59 the answer is 42
60
61 ``o`` (``unsigned int``)
62 Print the integer in base eight
63
64 ``x`` (``unsigned int``)
65 Print the integer in base sixteen
66
67 The above can be prefixed with ``l`` and ``ll`` prefixes to take
68 ``long`` and ``long long`` values of the appropriate signedness.
69
70 For example::
71
72 "address: %lx", (unsigned long)0x108b516
73
74 would print::
75
76 address: 108b516
77
78 Similarly, the prefix ``z`` can be used for ``size_t``::
79
80 "size: %zd", sizeof(struct foo)
81 size: 32
82
83 and ``t`` for ptrdiff_t.
84
85 ``f`` (``double``)
86 ``%f`` prints a floating-point value. For example::
87
88 "value: %f", 1.0
89
90 might print::
91
92 value: 1.000000
93
94
95 Strings
96 *******
97
98 ``c`` (``char``)
99 ``%c`` prints a single character.
100
101 ``s`` (``const char *``)
102 ``%s`` prints a string.
103
104 Note that if the string refers to something that might
105 appear in the input file (such as the name of a function), it's better
106 to quote the value; for example::
107
108 "unrecognized identifier: %qs", "foo"
109
110 might print::
111
112 unrecognized identifier: `foo'
113
114 ``m`` (no argument)
115 Prints ``strerror(errno)``, for example::
116
117 "can't open %qs: %m"
118
119 might print::
120
121 can't open `foo.txt': No such file or directory
122
123 ``%`` (no argument)
124 ``%%`` prints a `%` character, for example::
125
126 "8%% of 75 is 75%% of 8, and is thus 6"
127
128 prints::
129
130 8% of 75 is 75% of 8, and is thus 6
131
132 ``'`` (no argument)
133 ``%'`` prints an apostrophe. This should only be used in untranslated messages;
134 translations should use appropriate punctuation directly.
135
136
137 Other format specifiers
138 ***********************
139
140 ``p`` (pointer)
141 ``%p`` prints a pointer, although the precise format is
142 implementation-defined.
143
144 ``r`` (``const char *``)
145 ``%r`` starts colorization on suitable text sinks, where the argument
146 specifies the name of the kind of entity to be colored, such as ``error``.
147
148 ``R`` (no argument)
149 ``%R`` stops colorization
150
151 ``<`` and ``>`` (no arguments)
152 ``%<`` adds an opening quote and ``%>`` a closing quote, such as::
153
154 "missing element %<%s:%s%>", ns, name
155
156 which might be printed as::
157
158 missing element `xhtml:head'
159
160 If the thing to be quoted can be handled with another format specifier,
161 then it's simpler to use ``q`` with it. For example, it's much
162 simpler to print a ``const char *`` in quotes via::
163
164 "%qs", str
165
166 rather than the error-prone::
167
168 "%<%s%>", str
169
170 ``{`` (``const char *``)
171 ``%{`` starts a link; the argument is the URL. This will be displayed
172 in a suitably-capable terminal if a text sink is directly connected to
173 a tty, and will be captured in SARIF output.
174
175 ``}`` (no argument)
176 ``%}`` stops a link started with ``%{``.
177
178 For example::
179
180 "for more information see %{the documentation%}", "https://example.com"
181
182 would be printed as::
183
184 for more information see the documentation
185
186 with the URL emitted in suitable output sinks.
187
188 ``@`` (``diagnostic_event_id *``)
189 ``%@`` prints a reference to an event in a
190 :type:`diagnostic_execution_path`, where the :type:`diagnostic_event_id`
191 is passed by pointer.
192
193 For example, if ``event_id`` refers to the first event in a path, then::
194
195 "double-%qs of %qs; first %qs was at %@",
196 function, ptr, function, &event_id
197
198 might print::
199
200 double-`free' of `p'; first `free` was at (1)
201
202 .. :
203
204 TODO:
205
206 %.*s: a substring the length of which is specified by an argument
207 integer.
208 %Ns: likewise, but length specified as constant in the format string.
209 %Z: Requires two arguments - array of int, and len. Prints elements
210 of the array.
211
212 %e: Consumes a pp_element * argument.
213
214 Arguments can be used sequentially, or through %N$ resp. *N$
215 notation Nth argument after the format string. If %N$ / *N$
216 notation is used, it must be used for all arguments, except %m, %%,
217 %<, %>, %} and %', which may not have a number, as they do not consume
218 an argument. When %M$.*N$s is used, M must be N + 1. (This may
219 also be written %M$.*s, provided N is not otherwise used.) The
220 format string must have conversion specifiers with argument numbers
221 1 up to highest argument; each argument may only be used once.
222 A format string can have at most 30 arguments. */
223
224