1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
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
|
