src/include/gnunet_buffer_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2020 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * Common buffer management functions.
  23  *
  24  * @author Florian Dold
  25  */
  26
  27 #ifndef GNUNET_BUFFER_LIB_H
  28 #define GNUNET_BUFFER_LIB_H
  29
  30 /**
  31  * Dynamically growing buffer.  Can be used to construct
  32  * strings and other objects with dynamic size.
  33  *
  34  * This structure should, in most cases, be stack-allocated and
  35  * zero-initialized, like:
  36  *
  37  *   struct GNUNET_Buffer my_buffer = { 0 };
  38  */
  39 struct GNUNET_Buffer
  40 {
  41   /**
  42    * Capacity of the buffer.
  43    */
  44   size_t capacity;
  45
  46   /**
  47    * Current write position.
  48    */
  49   size_t position;
  50
  51   /**
  52    * Backing memory.
  53    */
  54   char *mem;
  55
  56   /**
  57    * Log a warning if the buffer is grown over its initially allocated capacity.
  58    */
  59   int warn_grow;
  60 };
  61
  62
  63 /**
  64  * Initialize a buffer with the given capacity.
  65  *
  66  * When a buffer is allocated with this function, a warning is logged
  67  * when the buffer exceeds the initial capacity.
  68  *
  69  * @param buf the buffer to initialize
  70  * @param capacity the capacity (in bytes) to allocate for @a buf
  71  */
  72 void
  73 GNUNET_buffer_prealloc (struct GNUNET_Buffer *buf, size_t capacity);
  74
  75
  76 /**
  77  * Make sure that at least @a n bytes remaining in the buffer.
  78  *
  79  * @param buf buffer to potentially grow
  80  * @param n number of bytes that should be available to write
  81  */
  82 void
  83 GNUNET_buffer_ensure_remaining (struct GNUNET_Buffer *buf, size_t n);
  84
  85
  86 /**
  87  * Write bytes to the buffer.
  88  *
  89  * Grows the buffer if necessary.
  90  *
  91  * @param buf buffer to write to
  92  * @param data data to read from
  93  * @param len number of bytes to copy from @a data to @a buf
  94  *
  95  */
  96 void
  97 GNUNET_buffer_write (struct GNUNET_Buffer *buf, const char *data, size_t len);
  98
  99
 100 /**
 101  * Write a 0-terminated string to a buffer, excluding the 0-terminator.
 102  *
 103  * Grows the buffer if necessary.
 104  *
 105  * @param buf the buffer to write to
 106  * @param str the string to write to @a buf
 107  */
 108 void
 109 GNUNET_buffer_write_str (struct GNUNET_Buffer *buf, const char *str);
 110
 111
 112 /**
 113  * Write a path component to a buffer, ensuring that
 114  * there is exactly one slash between the previous contents
 115  * of the buffer and the new string.
 116  *
 117  * @param buf buffer to write to
 118  * @param str string containing the new path component
 119  */
 120 void
 121 GNUNET_buffer_write_path (struct GNUNET_Buffer *buf, const char *str);
 122
 123
 124 /**
 125  * Write a 0-terminated formatted string to a buffer, excluding the
 126  * 0-terminator.
 127  *
 128  * Grows the buffer if necessary.
 129  *
 130  * @param buf the buffer to write to
 131  * @param fmt format string
 132  * @param ... format arguments
 133  */
 134 void
 135 GNUNET_buffer_write_fstr (struct GNUNET_Buffer *buf, const char *fmt, ...);
 136
 137
 138 /**
 139  * Write a 0-terminated formatted string to a buffer, excluding the
 140  * 0-terminator.
 141  *
 142  * Grows the buffer if necessary.
 143  *
 144  * @param buf the buffer to write to
 145  * @param fmt format string
 146  * @param args format argument list
 147  */
 148 void
 149 GNUNET_buffer_write_vfstr (struct GNUNET_Buffer *buf, const char *fmt, va_list
 150                           args);
 151
 152
 153 /**
 154  * Clear the buffer and return the string it contained.
 155  * The caller is responsible to eventually #GNUNET_free
 156  * the returned string.
 157  *
 158  * The returned string is always 0-terminated.
 159  *
 160  * @param buf the buffer to reap the string from
 161  * @returns the buffer contained in the string
 162  */
 163 char *
 164 GNUNET_buffer_reap_str (struct GNUNET_Buffer *buf);
 165
 166
 167 /**
 168  * Free the backing memory of the given buffer.
 169  * Does not free the memory of the buffer control structure,
 170  * which is typically stack-allocated.
 171  */
 172 void
 173 GNUNET_buffer_clear (struct GNUNET_Buffer *buf);
 174
 175
 176 #endif