diff options
Diffstat (limited to 'include/printf_buffer.h')
| -rw-r--r-- | include/printf_buffer.h | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/include/printf_buffer.h b/include/printf_buffer.h new file mode 100644 index 0000000000..ad08a72b71 --- /dev/null +++ b/include/printf_buffer.h @@ -0,0 +1,281 @@ +/* Multibyte and wide buffers for implementing printf-related functions. + Copyright (C) 2022 Free Software Foundation, Inc. + This file is part of the GNU C Library. + + The GNU C Library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + The GNU C Library 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 + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with the GNU C Library; if not, see + <https://www.gnu.org/licenses/>. */ + +/* The naming of the multibyte and wide variants is intentionally + consistent, so that it is possible to use the Xprintf macro in + stdio-common/printf_buffer-char.h and + stdio-common/printf_buffer-wchar_t.h to select between them in + type-generic code. */ + +#ifndef PRINTF_BUFFER_H +#define PRINTF_BUFFER_H + +#include <stdbool.h> +#include <stdint.h> +#include <wchar.h> + +/* <printf_buffer_as_file.h> introduces a way to use struct + __printf_buffer objects from FILE * streams. To avoid storing a + function pointer (or vtable pointer) in struct __printf_buffer + (which would defeat libio vtable hardening), a switch statement + over the different flush implementations is used to implement + __printf_buffer_flush. + + __printf_buffer_mode_failed is special: it is the sticky failure + indicator. Unlike struct alloc_buffer, this is not folded into + write_ptr, so that snprintf and other string-writing functions can + discover the end of the string even in the error case, to be able + to add the null terminator. */ +enum __printf_buffer_mode + { + __printf_buffer_mode_failed, + __printf_buffer_mode_to_file, + }; + +/* Buffer for fast character writing with overflow handling. + Typically embedded in another struct with further data that is used + by the flush function. */ +struct __printf_buffer +{ + /* These pointer members follow FILE streams. write_ptr and + write_end must be initialized to cover the target buffer. See + __printf_buffer_init. + + Data can be written directly to *write_ptr while write_ptr != + write_end, and write_ptr can be advanced accordingly. Note that + is not possible to use the apparently-unused part of the buffer + as scratch space because sprintf (and snprintf, but that is a bit + iffy) must only write the minimum number of characters produced + by the format string and its arguments. + + write_base must be initialized to be equal to write_ptr. The + framework uses this pointer to compute the total number of + written bytes, together with the written field. See + __printf_buffer_done. + + write_base and write_end are only read by the generic functions + after initialization, only the flush implementation called from + __printf_buffer_flush might change these pointers. See the + comment on Xprintf (buffer_do_flush) in Xprintf_buffer_flush.c + for details regarding the flush operation. */ + char *write_base; + char *write_ptr; + char *write_end; + + /* Number of characters written so far (excluding the current + buffer). Potentially updated on flush. The actual number of + written bytes also includes the unflushed-but-written buffer + part, write_ptr - write_base. A 64-bit value is used to avoid + the need for overflow checks. */ + uint64_t written; + + /* Identifies the flush callback. */ + enum __printf_buffer_mode mode; +}; + +/* Marks the buffer as failed, so that __printf_buffer_has_failed + returns true and future flush operations are no-ops. */ +static inline void +__printf_buffer_mark_failed (struct __printf_buffer *buf) +{ + buf->mode = __printf_buffer_mode_failed; +} + +/* Returns true if the sticky error indicator of the buffer has been + set to failed. */ +static inline bool __attribute_warn_unused_result__ +__printf_buffer_has_failed (struct __printf_buffer *buf) +{ + return buf->mode == __printf_buffer_mode_failed; +} + +/* Initialization of a buffer, using the memory region from [BASE, BASE +LEN) + as the initial buffer contents. LEN can be zero. */ +static inline void +__printf_buffer_init (struct __printf_buffer *buf, char *base, size_t len, + enum __printf_buffer_mode mode) +{ + buf->write_base = base; + buf->write_ptr = base; + buf->write_end = base + len; + buf->written = 0; + buf->mode = mode; +} + +/* Called by printf_buffer_putc for a full buffer. */ +void __printf_buffer_putc_1 (struct __printf_buffer *buf, char ch) + attribute_hidden; + +/* Writes CH to BUF. */ +static inline void +__printf_buffer_putc (struct __printf_buffer *buf, char ch) +{ + if (buf->write_ptr != buf->write_end) + *buf->write_ptr++ = ch; + else + __printf_buffer_putc_1 (buf, ch); +} + +/* Writes COUNT repeats of CH to BUF. */ +void __printf_buffer_pad_1 (struct __printf_buffer *buf, + char ch, size_t count) attribute_hidden; + +/* __printf_buffer_pad with fast path for no padding. COUNT is a + long int, to accomodate signed uses in printf and elsewhere. */ +static inline void +__printf_buffer_pad (struct __printf_buffer *buf, char ch, long int count) +{ + if (count > 0) + __printf_buffer_pad_1 (buf, ch, count); +} + +/* Write COUNT bytes starting at S to BUF. S must not overlap with + the internal buffer. */ +void __printf_buffer_write (struct __printf_buffer *buf, const char *s, + size_t count) attribute_hidden; + +/* Write S to BUF. S must not overlap with the internal buffer. */ +void __printf_buffer_puts_1 (struct __printf_buffer *buf, const char *s) + attribute_hidden; +static inline void +__printf_buffer_puts (struct __printf_buffer *buf, const char *s) +{ + if (__builtin_constant_p (__builtin_strlen (s))) + __printf_buffer_write (buf, s, __builtin_strlen (s)); + else + __printf_buffer_puts_1 (buf, s); +} + +/* Returns the number of bytes written through the buffer, or -1 if + there was an error (that is, __printf_buffer_has_failed (BUF) is true). + + The number of written bytes includes pending bytes in the buffer + (between BUF->write_base and BUF->write_ptr). + + If the number is larger than INT_MAX, returns -1 and sets errno to + EOVERFLOW. This function does not flush the buffer. If the caller + needs the side effect of flushing, it has to do this + separately. */ +int __printf_buffer_done (struct __printf_buffer *buf) attribute_hidden; + +/* Internally used to call the flush function. This can be called + explicitly for certain modes to flush the buffer prematuraly. In + such cases, it is often the case that the buffer mode is statically + known, and the flush implementation can be called directly. */ +bool __printf_buffer_flush (struct __printf_buffer *buf) attribute_hidden; + +/* Wide version of struct __printf_buffer follows. */ + +enum __wprintf_buffer_mode + { + __wprintf_buffer_mode_failed, + __wprintf_buffer_mode_to_file, + }; + +struct __wprintf_buffer +{ + wchar_t *write_base; + wchar_t *write_ptr; + wchar_t *write_end; + uint64_t written; + enum __wprintf_buffer_mode mode; +}; + +static inline void +__wprintf_buffer_mark_failed (struct __wprintf_buffer *buf) +{ + buf->mode = __wprintf_buffer_mode_failed; +} + +static inline bool __attribute_warn_unused_result__ +__wprintf_buffer_has_failed (struct __wprintf_buffer *buf) +{ + return buf->mode == __wprintf_buffer_mode_failed; +} + +static inline void +__wprintf_buffer_init (struct __wprintf_buffer *buf, + wchar_t *base, size_t len, + enum __wprintf_buffer_mode mode) +{ + buf->write_base = base; + buf->write_ptr = base; + buf->write_end = base + len; + buf->written = 0; + buf->mode = mode; +} + +void __wprintf_buffer_putc_1 (struct __wprintf_buffer *buf, wchar_t ch) + attribute_hidden; + +static inline void +__wprintf_buffer_putc (struct __wprintf_buffer *buf, wchar_t ch) +{ + if (buf->write_ptr != buf->write_end) + *buf->write_ptr++ = ch; + else + __wprintf_buffer_putc_1 (buf, ch); +} + +void __wprintf_buffer_pad_1 (struct __wprintf_buffer *buf, + wchar_t ch, size_t count) attribute_hidden; + +static inline void +__wprintf_buffer_pad (struct __wprintf_buffer *buf, char ch, long int count) +{ + if (count > 0) + __wprintf_buffer_pad_1 (buf, ch, count); +} + +void __wprintf_buffer_write (struct __wprintf_buffer *buf, const wchar_t *s, + size_t count) attribute_hidden; + +void __wprintf_buffer_puts (struct __wprintf_buffer *buf, const wchar_t *s) + attribute_hidden; + +int __wprintf_buffer_done (struct __wprintf_buffer *buf) attribute_hidden; + +bool __wprintf_buffer_flush (struct __wprintf_buffer *buf) attribute_hidden; + +/* Type-generic convenience macros. They are useful if + printf_buffer-char.h or printf_buffer-wchar_t.h is included as + well. */ + +#define Xprintf_buffer Xprintf (buffer) +#define Xprintf_buffer_done Xprintf (buffer_done) +#define Xprintf_buffer_flush Xprintf (buffer_flush) +#define Xprintf_buffer_has_failed Xprintf (buffer_has_failed) +#define Xprintf_buffer_mark_failed Xprintf (buffer_mark_failed) +#define Xprintf_buffer_pad Xprintf (buffer_pad) +#define Xprintf_buffer_putc Xprintf (buffer_putc) +#define Xprintf_buffer_puts Xprintf (buffer_puts) +#define Xprintf_buffer_write Xprintf (buffer_write) + +/* Flush function implementations follow. They are called from + __printf_buffer_flush. Generic code should not call these flush + functions directly. Some modes have inline implementations. */ + +struct __printf_buffer_to_file; +void __printf_buffer_flush_to_file (struct __printf_buffer_to_file *) + attribute_hidden; + +struct __wprintf_buffer_to_file; +void __wprintf_buffer_flush_to_file (struct __wprintf_buffer_to_file *) + attribute_hidden; + +#endif /* PRINTF_BUFFER_H */ |