diff options
Diffstat (limited to 'include/git2/buffer.h')
-rw-r--r-- | include/git2/buffer.h | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/include/git2/buffer.h b/include/git2/buffer.h new file mode 100644 index 000000000..454a1faa5 --- /dev/null +++ b/include/git2/buffer.h @@ -0,0 +1,86 @@ +/* + * Copyright (C) the libgit2 contributors. All rights reserved. + * + * This file is part of libgit2, distributed under the GNU GPL v2 with + * a Linking Exception. For full terms see the included COPYING file. + */ +#ifndef INCLUDE_git_buffer_h__ +#define INCLUDE_git_buffer_h__ + +#include "common.h" + +/** + * @file git2/buffer.h + * @brief Buffer export structure + * + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * A data buffer for exporting data from libgit2 + * + * There are a number of places where libgit2 wants to return an allocated + * data buffer to the caller and have the caller take ownership of that + * allocated memory. This can be awkward if the caller does not have easy + * access to the same allocation functions that libgit2 is using. In those + * cases, libgit2 will instead fill in a `git_buffer` and the caller can + * use `git_buffer_free()` to release it when they are done. + * + * * `ptr` refers to the start of the allocated memory. + * * `size` contains the size of the data in `ptr` that is actually used. + * * `available` refers to the known total amount of allocated memory in + * cases where it is larger than the `size` actually in use. + * + * In a few cases, for uniformity and simplicity, an API may populate a + * `git_buffer` with data that should *not* be freed (i.e. the lifetime of + * the data buffer is actually tied to another libgit2 object). These + * cases will be clearly documented in the APIs that use the `git_buffer`. + * In those cases, the `available` field will be set to zero even though + * the `ptr` and `size` will be valid. + */ +typedef struct git_buffer { + char *ptr; + size_t size; + size_t available; +} git_buffer; + +/** + * Use to initialize buffer structure when git_buffer is on stack + */ +#define GIT_BUFFER_INIT { NULL, 0, 0 } + +/** + * Free the memory referred to by the git_buffer. + * + * Note that this does not free the `git_buffer` itself, just the memory + * pointed to by `buffer->ptr`. If that memory was not allocated by + * libgit2 itself, be careful with using this function because it could + * cause problems. + * + * @param buffer The buffer with allocated memory + */ +GIT_EXTERN(void) git_buffer_free(git_buffer *buffer); + +/** + * Resize the buffer allocation to make more space. + * + * This will update `buffer->available` with the new size (which will be + * at least `want_size` and may be larger). This may or may not change + * `buffer->ptr` depending on whether there is an existing allocation and + * whether that allocation can be increased in place. + * + * Currently, this will never shrink the buffer, only expand it. + * + * @param buffer The buffer to be resized; may or may not be allocated yet + * @param want_size The desired available size + * @return 0 on success, negative error code on allocation failure + */ +GIT_EXTERN(int) git_buffer_resize(git_buffer *buffer, size_t want_size); + +GIT_END_DECL + +/** @} */ + +#endif |