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