| 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 |
|