include/printf_buffer.h

   1 /* Multibyte and wide buffers for implementing printf-related functions.
   2    Copyright (C) 2022-2024 Free Software Foundation, Inc.
   3    This file is part of the GNU C Library.
   4
   5    The GNU C Library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2.1 of the License, or (at your option) any later version.
   9
  10    The GNU C Library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with the GNU C Library; if not, see
  17    <https://www.gnu.org/licenses/>.  */
  18
  19 /* The naming of the multibyte and wide variants is intentionally
  20    consistent, so that it is possible to use the Xprintf macro in
  21    stdio-common/printf_buffer-char.h and
  22    stdio-common/printf_buffer-wchar_t.h to select between them in
  23    type-generic code.  */
  24
  25 #ifndef PRINTF_BUFFER_H
  26 #define PRINTF_BUFFER_H
  27
  28 #include <stdbool.h>
  29 #include <stdint.h>
  30 #include <sys/types.h>
  31 #include <wchar.h>
  32
  33 /* <printf_buffer_as_file.h> introduces a way to use struct
  34    __printf_buffer objects from FILE * streams.  To avoid storing a
  35    function pointer (or vtable pointer) in struct __printf_buffer
  36    (which would defeat libio vtable hardening), a switch statement
  37    over the different flush implementations is used to implement
  38    __printf_buffer_flush.
  39
  40    __printf_buffer_mode_failed is special: it is the sticky failure
  41    indicator.  Unlike struct alloc_buffer, this is not folded into
  42    write_ptr, so that snprintf and other string-writing functions can
  43    discover the end of the string even in the error case, to be able
  44    to add the null terminator.  */
  45 enum __printf_buffer_mode
  46   {
  47     __printf_buffer_mode_failed,
  48     __printf_buffer_mode_sprintf,
  49     __printf_buffer_mode_snprintf,
  50     __printf_buffer_mode_sprintf_chk,
  51     __printf_buffer_mode_to_file,
  52     __printf_buffer_mode_asprintf,
  53     __printf_buffer_mode_dprintf,
  54     __printf_buffer_mode_strfmon,
  55     __printf_buffer_mode_fp,         /* For __printf_fp_l_buffer.  */
  56     __printf_buffer_mode_fp_to_wide, /* For __wprintf_fp_l_buffer.  */
  57     __printf_buffer_mode_fphex_to_wide, /* For __wprintf_fphex_l_buffer.  */
  58     __printf_buffer_mode_obstack,    /* For __printf_buffer_flush_obstack.  */
  59   };
  60
  61 /* Buffer for fast character writing with overflow handling.
  62    Typically embedded in another struct with further data that is used
  63    by the flush function.  */
  64 struct __printf_buffer
  65 {
  66   /* These pointer members follow FILE streams.  write_ptr and
  67      write_end must be initialized to cover the target buffer.  See
  68      __printf_buffer_init.
  69
  70      Data can be written directly to *write_ptr while write_ptr !=
  71      write_end, and write_ptr can be advanced accordingly.  Note that
  72      is not possible to use the apparently-unused part of the buffer
  73      as scratch space because sprintf (and snprintf, but that is a bit
  74      iffy) must only write the minimum number of characters produced
  75      by the format string and its arguments.
  76
  77      write_base must be initialized to be equal to write_ptr.  The
  78      framework uses this pointer to compute the total number of
  79      written bytes, together with the written field.  See
  80      __printf_buffer_done.
  81
  82      write_base and write_end are only read by the generic functions
  83      after initialization, only the flush implementation called from
  84      __printf_buffer_flush might change these pointers.  See the
  85      comment on Xprintf (buffer_do_flush) in Xprintf_buffer_flush.c
  86      for details regarding the flush operation.  */
  87   char *write_base;
  88   char *write_ptr;
  89   char *write_end;
  90
  91   /* Number of characters written so far (excluding the current
  92      buffer).  Potentially updated on flush.  The actual number of
  93      written bytes also includes the unflushed-but-written buffer
  94      part, write_ptr - write_base.  A 64-bit value is used to avoid
  95      the need for overflow checks.  */
  96   uint64_t written;
  97
  98   /* Identifies the flush callback.  */
  99   enum __printf_buffer_mode mode;
 100 };
 101
 102 /* Marks the buffer as failed, so that __printf_buffer_has_failed
 103    returns true and future flush operations are no-ops.  */
 104 static inline void
 105 __printf_buffer_mark_failed (struct __printf_buffer *buf)
 106 {
 107   buf->mode = __printf_buffer_mode_failed;
 108 }
 109
 110 /* Returns true if the sticky error indicator of the buffer has been
 111    set to failed.  */
 112 static inline bool __attribute_warn_unused_result__
 113 __printf_buffer_has_failed (struct __printf_buffer *buf)
 114 {
 115   return buf->mode == __printf_buffer_mode_failed;
 116 }
 117
 118 /* Initialization of a buffer, using the memory region from [BASE,
 119    END) as the initial buffer contents.  */
 120 static inline void
 121 __printf_buffer_init_end (struct __printf_buffer *buf, char *base, char *end,
 122                           enum __printf_buffer_mode mode)
 123 {
 124   buf->write_base = base;
 125   buf->write_ptr = base;
 126   buf->write_end = end;
 127   buf->written = 0;
 128   buf->mode = mode;
 129 }
 130
 131 /* Initialization of a buffer, using the memory region from [BASE, BASE +LEN)
 132    as the initial buffer contents.  LEN can be zero.  */
 133 static inline void
 134 __printf_buffer_init (struct __printf_buffer *buf, char *base, size_t len,
 135                       enum __printf_buffer_mode mode)
 136 {
 137   __printf_buffer_init_end (buf, base, base + len, mode);
 138 }
 139
 140 /* Called by printf_buffer_putc for a full buffer.  */
 141 void __printf_buffer_putc_1 (struct __printf_buffer *buf, char ch)
 142   attribute_hidden;
 143
 144 /* Writes CH to BUF.  */
 145 static inline void
 146 __printf_buffer_putc (struct __printf_buffer *buf, char ch)
 147 {
 148   if (buf->write_ptr != buf->write_end)
 149       *buf->write_ptr++ = ch;
 150   else
 151     __printf_buffer_putc_1 (buf, ch);
 152 }
 153
 154 /* Writes COUNT repeats of CH to BUF.  */
 155 void __printf_buffer_pad_1 (struct __printf_buffer *buf,
 156                             char ch, size_t count) attribute_hidden;
 157
 158 /* __printf_buffer_pad with fast path for no padding.  COUNT is
 159    ssize_t to accommodate signed uses in printf and elsewhere.  */
 160 static inline void
 161 __printf_buffer_pad (struct __printf_buffer *buf, char ch, ssize_t count)
 162 {
 163   if (count > 0)
 164     __printf_buffer_pad_1 (buf, ch, count);
 165 }
 166
 167 /* Write COUNT bytes starting at S to BUF.  S must not overlap with
 168    the internal buffer.  */
 169 void __printf_buffer_write (struct __printf_buffer *buf, const char *s,
 170                             size_t count) attribute_hidden;
 171
 172 /* Write S to BUF.  S must not overlap with the internal buffer.  */
 173 void __printf_buffer_puts_1 (struct __printf_buffer *buf, const char *s)
 174   attribute_hidden;
 175
 176 static inline void
 177 __printf_buffer_puts (struct __printf_buffer *buf, const char *s)
 178 {
 179   if (__builtin_constant_p (__builtin_strlen (s)))
 180     __printf_buffer_write (buf, s, __builtin_strlen (s));
 181   else
 182     __printf_buffer_puts_1 (buf, s);
 183 }
 184
 185 /* Returns the number of bytes written through the buffer, or -1 if
 186    there was an error (that is, __printf_buffer_has_failed (BUF) is true).
 187
 188    The number of written bytes includes pending bytes in the buffer
 189    (between BUF->write_base and BUF->write_ptr).
 190
 191    If the number is larger than INT_MAX, returns -1 and sets errno to
 192    EOVERFLOW.  This function does not flush the buffer.  If the caller
 193    needs the side effect of flushing, it has to do this
 194    separately.  */
 195 int __printf_buffer_done (struct __printf_buffer *buf) attribute_hidden;
 196
 197 /* Internally used to call the flush function.  This can be called
 198    explicitly for certain modes to flush the buffer prematuraly.  In
 199    such cases, it is often the case that the buffer mode is statically
 200    known, and the flush implementation can be called directly.  */
 201 bool __printf_buffer_flush (struct __printf_buffer *buf) attribute_hidden;
 202
 203 /* Wide version of struct __printf_buffer follows.  */
 204
 205 enum __wprintf_buffer_mode
 206   {
 207     __wprintf_buffer_mode_failed,
 208     __wprintf_buffer_mode_swprintf,
 209     __wprintf_buffer_mode_to_file,
 210   };
 211
 212 struct __wprintf_buffer
 213 {
 214   wchar_t *write_base;
 215   wchar_t *write_ptr;
 216   wchar_t *write_end;
 217   uint64_t written;
 218   enum __wprintf_buffer_mode mode;
 219 };
 220
 221 static inline void
 222 __wprintf_buffer_mark_failed (struct __wprintf_buffer *buf)
 223 {
 224   buf->mode = __wprintf_buffer_mode_failed;
 225 }
 226
 227 static inline bool __attribute_warn_unused_result__
 228 __wprintf_buffer_has_failed (struct __wprintf_buffer *buf)
 229 {
 230   return buf->mode == __wprintf_buffer_mode_failed;
 231 }
 232
 233 static inline void
 234 __wprintf_buffer_init (struct __wprintf_buffer *buf,
 235                        wchar_t *base, size_t len,
 236                        enum __wprintf_buffer_mode mode)
 237 {
 238   buf->write_base = base;
 239   buf->write_ptr = base;
 240   buf->write_end = base + len;
 241   buf->written = 0;
 242   buf->mode = mode;
 243 }
 244
 245 void __wprintf_buffer_putc_1 (struct __wprintf_buffer *buf, wchar_t ch)
 246   attribute_hidden;
 247
 248 static inline void
 249 __wprintf_buffer_putc (struct __wprintf_buffer *buf, wchar_t ch)
 250 {
 251   if (buf->write_ptr != buf->write_end)
 252       *buf->write_ptr++ = ch;
 253   else
 254     __wprintf_buffer_putc_1 (buf, ch);
 255 }
 256
 257 void __wprintf_buffer_pad_1 (struct __wprintf_buffer *buf,
 258                              wchar_t ch, size_t count) attribute_hidden;
 259
 260 static inline void
 261 __wprintf_buffer_pad (struct __wprintf_buffer *buf, char ch, ssize_t count)
 262 {
 263   if (count > 0)
 264     __wprintf_buffer_pad_1 (buf, ch, count);
 265 }
 266
 267 void __wprintf_buffer_write (struct __wprintf_buffer *buf, const wchar_t *s,
 268                              size_t count) attribute_hidden;
 269
 270 void __wprintf_buffer_puts (struct __wprintf_buffer *buf, const wchar_t *s)
 271   attribute_hidden;
 272
 273 int __wprintf_buffer_done (struct __wprintf_buffer *buf) attribute_hidden;
 274
 275 bool __wprintf_buffer_flush (struct __wprintf_buffer *buf) attribute_hidden;
 276
 277 /* Type-generic convenience macros.  They are useful if
 278    printf_buffer-char.h or printf_buffer-wchar_t.h is included as
 279    well.  */
 280
 281 #define Xprintf_buffer Xprintf (buffer)
 282 #define Xprintf_buffer_done Xprintf (buffer_done)
 283 #define Xprintf_buffer_flush Xprintf (buffer_flush)
 284 #define Xprintf_buffer_has_failed Xprintf (buffer_has_failed)
 285 #define Xprintf_buffer_mark_failed Xprintf (buffer_mark_failed)
 286 #define Xprintf_buffer_pad Xprintf (buffer_pad)
 287 #define Xprintf_buffer_putc Xprintf (buffer_putc)
 288 #define Xprintf_buffer_puts Xprintf (buffer_puts)
 289 #define Xprintf_buffer_write Xprintf (buffer_write)
 290
 291 /* Commonly used buffers.  */
 292
 293 struct __printf_buffer_snprintf
 294 {
 295   struct __printf_buffer base;
 296 #define PRINTF_BUFFER_SIZE_DISCARD 128
 297   char discard[PRINTF_BUFFER_SIZE_DISCARD]; /* Used in counting mode.  */
 298 };
 299
 300 /* Sets up [BUFFER, BUFFER + LENGTH) as the write target.  If LENGTH
 301    is positive, also writes a NUL byte to *BUFFER.  */
 302 void __printf_buffer_snprintf_init (struct __printf_buffer_snprintf *,
 303                                     char *buffer, size_t length)
 304   attribute_hidden;
 305
 306 /* Add the null terminator after everything has been written.  The
 307    return value is the one expected by printf (see __printf_buffer_done).  */
 308 int __printf_buffer_snprintf_done (struct __printf_buffer_snprintf *)
 309   attribute_hidden;
 310
 311 /* Flush function implementations follow.  They are called from
 312    __printf_buffer_flush.  Generic code should not call these flush
 313    functions directly.  Some modes have inline implementations.  */
 314
 315 void __printf_buffer_flush_snprintf (struct __printf_buffer_snprintf *)
 316   attribute_hidden;
 317 struct __printf_buffer_to_file;
 318 void __printf_buffer_flush_to_file (struct __printf_buffer_to_file *)
 319   attribute_hidden;
 320 struct __printf_buffer_asprintf;
 321 void __printf_buffer_flush_asprintf (struct __printf_buffer_asprintf *)
 322   attribute_hidden;
 323 struct __printf_buffer_dprintf;
 324 void __printf_buffer_flush_dprintf (struct __printf_buffer_dprintf *)
 325   attribute_hidden;
 326 struct __printf_buffer_fp;
 327 void __printf_buffer_flush_fp (struct __printf_buffer_fp *)
 328   attribute_hidden;
 329 struct __printf_buffer_fp_to_wide;
 330 void __printf_buffer_flush_fp_to_wide (struct __printf_buffer_fp_to_wide *)
 331   attribute_hidden;
 332 struct __printf_buffer_fphex_to_wide;
 333 void __printf_buffer_flush_fphex_to_wide (struct
 334                                           __printf_buffer_fphex_to_wide *)
 335   attribute_hidden;
 336 struct __printf_buffer_obstack;
 337 void __printf_buffer_flush_obstack (struct __printf_buffer_obstack *)
 338   attribute_hidden;
 339
 340 struct __wprintf_buffer_to_file;
 341 void __wprintf_buffer_flush_to_file (struct __wprintf_buffer_to_file *)
 342   attribute_hidden;
 343
 344 /* Buffer sizes.  These can be tuned as necessary.  There is a tension
 345    here between stack consumption, cache usage, and additional system
 346    calls or heap allocations (if the buffer is too small).
 347
 348    Also see PRINTF_BUFFER_SIZE_DISCARD above for snprintf.  */
 349
 350 /* Fallback buffer if the underlying FILE * stream does not provide
 351    buffer space.  */
 352 #define PRINTF_BUFFER_SIZE_TO_FILE_STAGE 128
 353
 354 /* Temporary buffer used during floating point digit translation.  */
 355 #define PRINTF_BUFFER_SIZE_DIGITS 64
 356
 357 /* Size of the initial on-stack buffer for asprintf.  It should be
 358    large enough to copy almost all asprintf usages with just a single
 359    (final, correctly sized) heap allocation.  */
 360 #define PRINTF_BUFFER_SIZE_ASPRINTF 200
 361
 362 /* This should cover most of the packet-oriented file descriptors,
 363    where boundaries between writes could be visible to readers.  But
 364    it is still small enough not to cause too many stack overflow issues.  */
 365 #define PRINTF_BUFFER_SIZE_DPRINTF 2048
 366
 367 #endif /* PRINTF_BUFFER_H */