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
andi
(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 aserror
.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 aconst 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 adiagnostic_execution_path
, where thediagnostic_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)