include/git2/buffer.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_buf_h__
0008 #define INCLUDE_git_buf_h__
0009
0010 #include "common.h"
0011
0012 /**
0013  * @file git2/buffer.h
0014  * @brief Buffer export structure
0015  *
0016  * @ingroup Git
0017  * @{
0018  */
0019 GIT_BEGIN_DECL
0020
0021 /**
0022  * A data buffer for exporting data from libgit2
0023  *
0024  * Sometimes libgit2 wants to return an allocated data buffer to the
0025  * caller and have the caller take responsibility for freeing that memory.
0026  * To make ownership clear in these cases, libgit2 uses  `git_buf` to
0027  * return this data.  Callers should use `git_buf_dispose()` to release
0028  * the memory when they are done.
0029  *
0030  * A `git_buf` contains a pointer to a NUL-terminated C string, and
0031  * the length of the string (not including the NUL terminator).
0032  */
0033 typedef struct {
0034     /**
0035      * The buffer contents.  `ptr` points to the start of the buffer
0036      * being returned.  The buffer's length (in bytes) is specified
0037      * by the `size` member of the structure, and contains a NUL
0038      * terminator at position `(size + 1)`.
0039      */
0040     char *ptr;
0041
0042     /**
0043      * This field is reserved and unused.
0044      */
0045     size_t reserved;
0046
0047     /**
0048      * The length (in bytes) of the buffer pointed to by `ptr`,
0049      * not including a NUL terminator.
0050      */
0051     size_t size;
0052 } git_buf;
0053
0054 /**
0055  * Use to initialize a `git_buf` before passing it to a function that
0056  * will populate it.
0057  */
0058 #define GIT_BUF_INIT { NULL, 0, 0 }
0059
0060 /**
0061  * Free the memory referred to by the git_buf.
0062  *
0063  * Note that this does not free the `git_buf` itself, just the memory
0064  * pointed to by `buffer->ptr`.
0065  *
0066  * @param buffer The buffer to deallocate
0067  */
0068 GIT_EXTERN(void) git_buf_dispose(git_buf *buffer);
0069
0070 GIT_END_DECL
0071
0072 /** @} */
0073
0074 #endif