mirror of
https://git.proxmox.com/git/libgit2
synced 2025-05-03 16:06:02 +00:00
0cf77103b2
This begins the process of exposing git_filter objects to the public API. This includes: * new public type and API for `git_buffer` through which an allocated buffer can be passed to the user * new API `git_blob_filtered_content` * make the git_filter type and GIT_FILTER_TO_... constants public
87 lines
2.8 KiB
C
87 lines
2.8 KiB
C
/*
|
|
* 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
|