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 * Some APIs may occasionally do something slightly unusual with a buffer, 36 * such as setting `ptr` to a value that was passed in by the user. In 37 * those cases, the behavior will be clearly documented by the API. 38 */ 39 typedef struct { 40 /** 41 * The buffer contents. 42 * 43 * `ptr` points to the start of the allocated memory. If it is NULL, 44 * then the `git_buf` is considered empty and libgit2 will feel free 45 * to overwrite it with new data. 46 */ 47 char *ptr; 48 49 /** 50 * `asize` holds the known total amount of allocated memory if the `ptr` 51 * was allocated by libgit2. It may be larger than `size`. If `ptr` 52 * was not allocated by libgit2 and should not be resized and/or freed, 53 * then `asize` will be set to zero. 54 */ 55 size_t asize; 56 57 /** 58 * `size` holds the size (in bytes) of the data that is actually used. 59 */ 60 size_t size; 61 } git_buf; 62 63 /** 64 * Static initializer for git_buf from static buffer 65 */ 66 #define GIT_BUF_INIT_CONST(STR,LEN) { (char *)(STR), 0, (size_t)(LEN) } 67 68 /** 69 * Free the memory referred to by the git_buf. 70 * 71 * Note that this does not free the `git_buf` itself, just the memory 72 * pointed to by `buffer->ptr`. This will not free the memory if it looks 73 * like it was not allocated internally, but it will clear the buffer back 74 * to the empty state. 75 * 76 * @param buffer The buffer to deallocate 77 */ 78 GIT_EXTERN(void) git_buf_dispose(git_buf *buffer); 79 80 /** 81 * Resize the buffer allocation to make more space. 82 * 83 * This will attempt to grow the buffer to accommodate the target size. 84 * 85 * If the buffer refers to memory that was not allocated by libgit2 (i.e. 86 * the `asize` field is zero), then `ptr` will be replaced with a newly 87 * allocated block of data. Be careful so that memory allocated by the 88 * caller is not lost. As a special variant, if you pass `target_size` as 89 * 0 and the memory is not allocated by libgit2, this will allocate a new 90 * buffer of size `size` and copy the external data into it. 91 * 92 * Currently, this will never shrink a buffer, only expand it. 93 * 94 * If the allocation fails, this will return an error and the buffer will be 95 * marked as invalid for future operations, invaliding the contents. 96 * 97 * @param buffer The buffer to be resized; may or may not be allocated yet 98 * @param target_size The desired available size 99 * @return 0 on success, -1 on allocation failure 100 */ 101 GIT_EXTERN(int) git_buf_grow(git_buf *buffer, size_t target_size); 102 103 /** 104 * Set buffer to a copy of some raw data. 105 * 106 * @param buffer The buffer to set 107 * @param data The data to copy into the buffer 108 * @param datalen The length of the data to copy into the buffer 109 * @return 0 on success, -1 on allocation failure 110 */ 111 GIT_EXTERN(int) git_buf_set( 112 git_buf *buffer, const void *data, size_t datalen); 113 114 /** 115 * Check quickly if buffer looks like it contains binary data 116 * 117 * @param buf Buffer to check 118 * @return 1 if buffer looks like non-text data 119 */ 120 GIT_EXTERN(int) git_buf_is_binary(const git_buf *buf); 121 122 /** 123 * Check quickly if buffer contains a NUL byte 124 * 125 * @param buf Buffer to check 126 * @return 1 if buffer contains a NUL byte 127 */ 128 GIT_EXTERN(int) git_buf_contains_nul(const git_buf *buf); 129 130 GIT_END_DECL 131 132 /** @} */ 133 134 #endif 135