Message buffers

type diagnostic_message_buffer

A diagnostic_message_buffer is a buffer into which text can be accumulated, before being used:

This is to allow more flexible creation of messages than a “format string plus variadic arguments” API.

diagnostic_message_buffer *diagnostic_message_buffer_new(void)

This function creates a new diagnostic_message_buffer.

The caller is responsible for cleaning it up, either by handing it off to one of the API entrypoints that takes ownership of it (such as diagnostic_finish_via_msg_buf()), or by calling diagnostic_message_buffer_release() on it.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer
void diagnostic_message_buffer_release(diagnostic_message_buffer *msg_buf)

This function releases msg_buf.

Typically you don’t need to call this, but instead will pass the buffer to one of the API entrypoints that takes over ownership of it (such as diagnostic_finish_via_msg_buf()); calling it after this would lead to a double-free bug, as you no longer “own” the buffer.

msg_buf must be non-NULL.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer
void diagnostic_message_buffer_append_str(diagnostic_message_buffer *msg_buf, const char *p)

This function appends the null-terminated string p to the buffer. The string is assumed to be UTF-8 encoded.

msg_buf and p must both be non-NULL.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer
void diagnostic_message_buffer_append_text(diagnostic_message_buffer *msg_buf, const char *p, size_t len)

This function appends len bytes from p to the buffer. The bytes are assumed to be UTF-8 encoded.

msg_buf and p must both be non-NULL.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer
void diagnostic_message_buffer_append_byte(diagnostic_message_buffer *msg_buf, char ch)

This function appends ch to the buffer. This should be either ASCII, or part of UTF-8 encoded text.

msg_buf must be non-NULL.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer
void diagnostic_message_buffer_append_printf(diagnostic_message_buffer *msg_buf, const char *fmt, ...)

This function appends a formatted string to the buffer, using the formatting rules for printf.

The string is assumed to be UTF-8 encoded.

msg_buf and fmt must both be non-NULL.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer
void diagnostic_message_buffer_append_event_id(diagnostic_message_buffer *msg_buf, diagnostic_event_id event_id)

This function appends a diagnostic_event_id to the buffer.

msg_buf must be non-NULL.

For text output, the event will be printed in the form (1).

This is analogous to the %@ message formatting code.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer

Quoted text

void diagnostic_message_buffer_begin_quote(diagnostic_message_buffer *msg_buf)

This function indicates the beginning of a run of text that should be printed in quotes. The run of text should be closed with a matching call to diagnostic_message_buffer_end_quote().

msg_buf must be non-NULL.

For text output in a suitably modern terminal, the run of text will appear in bold. be emitted as a clickable hyperlink to the URL.

For SARIF sinks, the run of text will be emitted using SARIF’s embedded link syntax.

This is analogous to the %<message formatting code.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer
void diagnostic_message_buffer_end_url(diagnostic_message_buffer *msg_buf)

This function ends a run of text within the buffer started with diagnostic_message_buffer_begin_url().

msg_buf must be non-NULL.

This is analogous to the %> message formatting code.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer

Color

void diagnostic_message_buffer_begin_color(diagnostic_message_buffer *msg_buf, const char *color)

This function indicates the beginning of a run of text that should be colorized as the given color. The run of text should be closed with a matching call to diagnostic_message_buffer_end_color().

The precise set of available color names is currently undocumented.

msg_buf and color must both be non-NULL.

For text output in a suitable terminal, the run of text will be colorized.

For SARIF sinks, the run of text will be emitted using SARIF’s embedded link syntax.

This is analogous to the %r message formatting code.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer
void diagnostic_message_buffer_end_color(diagnostic_message_buffer *msg_buf)

This function ends a run of text within the buffer started with diagnostic_message_buffer_begin_color().

msg_buf must be non-NULL.

This is analogous to the %R message formatting code.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer

Debugging a message buffer

void diagnostic_message_buffer_dump(const diagnostic_message_buffer *msg_buf, FILE *outf)

This function writes a representation of the contents of msg_buf to outf, for debugging.

msg_buf can be NULL or non-NULL. outf must be non-NULL.

This function was added in LIBGDIAGNOSTICS_ABI_4; you can test for its presence using

#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer