include/git2/buffer.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_git_buf_h__
   8 #define INCLUDE_git_buf_h__
   9
  10 #include "common.h"
  11
  12 /**
  13  * @file git2/buffer.h
  14  * @brief Buffer export structure
  15  *
  16  * @ingroup Git
  17  * @{
  18  */
  19 GIT_BEGIN_DECL
  20
  21 /**
  22  * A data buffer for exporting data from libgit2
  23  *
  24  * Sometimes libgit2 wants to return an allocated data buffer to the
  25  * caller and have the caller take responsibility for freeing that memory.
  26  * This can be awkward if the caller does not have easy access to the same
  27  * allocation functions that libgit2 is using.  In those cases, libgit2
  28  * will fill in a `git_buf` and the caller can use `git_buf_dispose()` to
  29  * release it when they are done.
  30  *
  31  * A `git_buf` may also be used for the caller to pass in a reference to
  32  * a block of memory they hold.  In this case, libgit2 will not resize or
  33  * free the memory, but will read from it as needed.
  34  *
  35  * A `git_buf` is a public structure with three fields:
  36  *
  37  * - `ptr` points to the start of the allocated memory.  If it is NULL,
  38  *   then the `git_buf` is considered empty and libgit2 will feel free
  39  *   to overwrite it with new data.
  40  *
  41  * - `size` holds the size (in bytes) of the data that is actually used.
  42  *
  43  * - `asize` holds the known total amount of allocated memory if the `ptr`
  44  *    was allocated by libgit2.  It may be larger than `size`.  If `ptr`
  45  *    was not allocated by libgit2 and should not be resized and/or freed,
  46  *    then `asize` will be set to zero.
  47  *
  48  * Some APIs may occasionally do something slightly unusual with a buffer,
  49  * such as setting `ptr` to a value that was passed in by the user.  In
  50  * those cases, the behavior will be clearly documented by the API.
  51  */
  52 typedef struct {
  53         char   *ptr;
  54         size_t asize, size;
  55 } git_buf;
  56
  57 /**
  58  * Static initializer for git_buf from static buffer
  59  */
  60 #define GIT_BUF_INIT_CONST(STR,LEN) { (char *)(STR), 0, (size_t)(LEN) }
  61
  62 /**
  63  * Free the memory referred to by the git_buf.
  64  *
  65  * Note that this does not free the `git_buf` itself, just the memory
  66  * pointed to by `buffer->ptr`.  This will not free the memory if it looks
  67  * like it was not allocated internally, but it will clear the buffer back
  68  * to the empty state.
  69  *
  70  * @param buffer The buffer to deallocate
  71  */
  72 GIT_EXTERN(void) git_buf_dispose(git_buf *buffer);
  73
  74 /**
  75  * Resize the buffer allocation to make more space.
  76  *
  77  * This will attempt to grow the buffer to accommodate the target size.
  78  *
  79  * If the buffer refers to memory that was not allocated by libgit2 (i.e.
  80  * the `asize` field is zero), then `ptr` will be replaced with a newly
  81  * allocated block of data.  Be careful so that memory allocated by the
  82  * caller is not lost.  As a special variant, if you pass `target_size` as
  83  * 0 and the memory is not allocated by libgit2, this will allocate a new
  84  * buffer of size `size` and copy the external data into it.
  85  *
  86  * Currently, this will never shrink a buffer, only expand it.
  87  *
  88  * If the allocation fails, this will return an error and the buffer will be
  89  * marked as invalid for future operations, invaliding the contents.
  90  *
  91  * @param buffer The buffer to be resized; may or may not be allocated yet
  92  * @param target_size The desired available size
  93  * @return 0 on success, -1 on allocation failure
  94  */
  95 GIT_EXTERN(int) git_buf_grow(git_buf *buffer, size_t target_size);
  96
  97 /**
  98  * Set buffer to a copy of some raw data.
  99  *
 100  * @param buffer The buffer to set
 101  * @param data The data to copy into the buffer
 102  * @param datalen The length of the data to copy into the buffer
 103  * @return 0 on success, -1 on allocation failure
 104  */
 105 GIT_EXTERN(int) git_buf_set(
 106         git_buf *buffer, const void *data, size_t datalen);
 107
 108 /**
 109 * Check quickly if buffer looks like it contains binary data
 110 *
 111 * @param buf Buffer to check
 112 * @return 1 if buffer looks like non-text data
 113 */
 114 GIT_EXTERN(int) git_buf_is_binary(const git_buf *buf);
 115
 116 /**
 117 * Check quickly if buffer contains a NUL byte
 118 *
 119 * @param buf Buffer to check
 120 * @return 1 if buffer contains a NUL byte
 121 */
 122 GIT_EXTERN(int) git_buf_contains_nul(const git_buf *buf);
 123
 124 GIT_END_DECL
 125
 126 /** @} */
 127
 128 #endif