src/common/dynamic-buffer.h

   1 /*
   2  * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * This program is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License, version 2.1 only,
   6  * as published by the Free Software Foundation.
   7  *
   8  * This program is distributed in the hope that it will be useful, but WITHOUT
   9  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
  11  * for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this program; if not, write to the Free Software Foundation,
  15  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  16  */
  17
  18 #ifndef LTTNG_DYNAMIC_BUFFER_H
  19 #define LTTNG_DYNAMIC_BUFFER_H
  20
  21 #include <stddef.h>
  22 #include <stdint.h>
  23 #include <common/macros.h>
  24
  25 struct lttng_dynamic_buffer {
  26         char *data;
  27         /* size is the buffer's currently used capacity. */
  28         size_t size;
  29         /*
  30          * capacity shall not be accessed by users directly, it is meant for
  31          * internal use only.
  32          */
  33         size_t _capacity;
  34 };
  35
  36 /*
  37  * Initialize a dynamic buffer. This performs no allocation and is meant
  38  * to be used instead of memset or explicit initialization of the buffer.
  39  */
  40 LTTNG_HIDDEN
  41 void lttng_dynamic_buffer_init(struct lttng_dynamic_buffer *buffer);
  42
  43 /*
  44  * Append the content of a raw memory buffer to the end of a dynamic buffer
  45  * (after its current "size"). The dynamic buffer's size is increased by
  46  * "len", and its capacity is adjusted automatically.
  47  */
  48 LTTNG_HIDDEN
  49 int lttng_dynamic_buffer_append(struct lttng_dynamic_buffer *buffer,
  50                 const void *buf, size_t len);
  51
  52 /*
  53  * Performs the same action as lttng_dynamic_buffer_append(), but using another
  54  * dynamic buffer as the source buffer. The source buffer's size is used in lieu
  55  * of "len".
  56  */
  57 LTTNG_HIDDEN
  58 int lttng_dynamic_buffer_append_buffer(struct lttng_dynamic_buffer *dst_buffer,
  59                 struct lttng_dynamic_buffer *src_buffer);
  60
  61 /*
  62  * Set the buffer's size to new_size. The capacity of the buffer will
  63  * be expanded (if necessary) to accomodate new_size. Areas acquired by
  64  * a size increase will be zeroed.
  65  *
  66  * Be careful to expand the buffer's size _before_ calling out external
  67  * APIs (e.g. read(3)) which may populate the buffer as setting the size
  68  * after will zero-out the result of the operation.
  69  *
  70  * Shrinking a buffer does not zero the old content. If the buffer may contain
  71  * sensititve information, it must be cleared manually _before_ changing the
  72  * size.
  73  *
  74  * NOTE: It is striclty _invalid_ to access memory after _size_, regardless
  75  *       of prior calls to set_capacity().
  76  */
  77 LTTNG_HIDDEN
  78 int lttng_dynamic_buffer_set_size(struct lttng_dynamic_buffer *buffer,
  79                 size_t new_size);
  80
  81 /*
  82  * Set the buffer's capacity to accomodate the new_capacity, allocating memory
  83  * as necessary. The buffer's content is preserved. Setting a buffer's capacity
  84  * is meant as a _hint_ to the underlying buffer and is only optimization; no
  85  * guarantee is offered that subsequent calls to append or set_size will succeed.
  86  *
  87  * If the current size > new_capacity, the operation will fail.
  88  */
  89 LTTNG_HIDDEN
  90 int lttng_dynamic_buffer_set_capacity(struct lttng_dynamic_buffer *buffer,
  91                 size_t new_capacity);
  92
  93 /* Release any memory used by the dynamic buffer. */
  94 LTTNG_HIDDEN
  95 void lttng_dynamic_buffer_reset(struct lttng_dynamic_buffer *buffer);
  96
  97 /* Get the space left in the buffer before a new resize is needed. */
  98 LTTNG_HIDDEN
  99 size_t lttng_dynamic_buffer_get_capacity_left(
 100                 struct lttng_dynamic_buffer *buffer);
 101
 102 #endif /* LTTNG_DYNAMIC_BUFFER_H */