Merge pull request #2077 from libgit2/cmn/buf-out

Buff up returning strings

5 files changed, 36 insertions, 69 deletions

diff --git a/include/git2/branch.h b/include/git2/branch.h
index 44d6fd9c3..851de290a 100644
--- a/include/git2/branch.h
+++ b/include/git2/branch.h
@@ -200,25 +200,20 @@ GIT_EXTERN(int) git_branch_set_upstream(git_reference *branch, const char *upstr
  * Return the name of the reference supporting the remote tracking branch,
  * given the name of a local branch reference.
  *
- * @param tracking_branch_name_out The user-allocated buffer which will be
- *     filled with the name of the reference. Pass NULL if you just want to
- *     get the needed size of the name of the reference as the output value.
- *
- * @param buffer_size Size of the `out` buffer in bytes.
+ * @param out Pointer to the user-allocated git_buf which will be
+ * filled with the name of the reference.
  *
  * @param repo the repository where the branches live
  *
- * @param canonical_branch_name name of the local branch.
+ * @param refname reference name of the local branch.
  *
- * @return number of characters in the reference name
- *     including the trailing NUL byte; GIT_ENOTFOUND when no remote tracking
- *     reference exists, otherwise an error code.
+ * @return 0, GIT_ENOTFOUND when no remote tracking reference exists,
+ *     otherwise an error code.
  */
 GIT_EXTERN(int) git_branch_upstream_name(
-	char *tracking_branch_name_out,
-	size_t buffer_size,
+	git_buf *out,
 	git_repository *repo,
-	const char *canonical_branch_name);
+	const char *refname);
 
 /**
  * Determine if the current local branch is pointed at by HEAD.
@@ -234,25 +229,19 @@ GIT_EXTERN(int) git_branch_is_head(
 /**
  * Return the name of remote that the remote tracking branch belongs to.
  *
- * @param remote_name_out The user-allocated buffer which will be
- *     filled with the name of the remote. Pass NULL if you just want to
- *     get the needed size of the name of the remote as the output value.
- *
- * @param buffer_size Size of the `out` buffer in bytes.
+ * @param out Pointer to the user-allocated git_buf which will be filled iwth the name of the remote.
  *
  * @param repo The repository where the branch lives.
  *
  * @param canonical_branch_name name of the remote tracking branch.
  *
- * @return Number of characters in the reference name
- *     including the trailing NUL byte; GIT_ENOTFOUND
+ * @return 0, GIT_ENOTFOUND
  *     when no remote matching remote was found,
  *     GIT_EAMBIGUOUS when the branch maps to several remotes,
  *     otherwise an error code.
  */
 GIT_EXTERN(int) git_branch_remote_name(
-	char *remote_name_out,
-	size_t buffer_size,
+	git_buf *out,
 	git_repository *repo,
 	const char *canonical_branch_name);
 
diff --git a/include/git2/config.h b/include/git2/config.h
index f650f1b41..663b4f6ba 100644
--- a/include/git2/config.h
+++ b/include/git2/config.h
@@ -9,6 +9,7 @@
 
 #include "common.h"
 #include "types.h"
+#include "buffer.h"
 
 /**
  * @file git2/config.h
@@ -90,11 +91,10 @@ typedef struct {
  * This method will not guess the path to the xdg compatible
  * config file (.config/git/config).
  *
- * @param out Buffer to store the path in
- * @param length size of the buffer in bytes
- * @return 0 if a global configuration file has been found. Its path will be stored in `buffer`.
+ * @param out Pointer to a user-allocated git_buf in which to store the path
+ * @return 0 if a global configuration file has been found. Its path will be stored in `out`.
  */
-GIT_EXTERN(int) git_config_find_global(char *out, size_t length);
+GIT_EXTERN(int) git_config_find_global(git_buf *out);
 
 /**
  * Locate the path to the global xdg compatible configuration file
@@ -107,25 +107,23 @@ GIT_EXTERN(int) git_config_find_global(char *out, size_t length);
  * may be used on any `git_config` call to load the
  * xdg compatible configuration file.
  *
- * @param out Buffer to store the path in
- * @param length size of the buffer in bytes
+ * @param out Pointer to a user-allocated git_buf in which to store the path
  * @return 0 if a xdg compatible configuration file has been
- *	found. Its path will be stored in `buffer`.
+ *	found. Its path will be stored in `out`.
  */
-GIT_EXTERN(int) git_config_find_xdg(char *out, size_t length);
+GIT_EXTERN(int) git_config_find_xdg(git_buf *out);
 
 /**
  * Locate the path to the system configuration file
  *
  * If /etc/gitconfig doesn't exist, it will look for
  * %PROGRAMFILES%\Git\etc\gitconfig.
-
- * @param out Buffer to store the path in
- * @param length size of the buffer in bytes
+ *
+ * @param out Pointer to a user-allocated git_buf in which to store the path
  * @return 0 if a system configuration file has been
- *	found. Its path will be stored in `buffer`.
+ *	found. Its path will be stored in `out`.
  */
-GIT_EXTERN(int) git_config_find_system(char *out, size_t length);
+GIT_EXTERN(int) git_config_find_system(git_buf *out);
 
 /**
  * Open the global, XDG and system configuration files
diff --git a/include/git2/message.h b/include/git2/message.h
index 395c88690..bcdb72f6a 100644
--- a/include/git2/message.h
+++ b/include/git2/message.h
@@ -8,6 +8,7 @@
 #define INCLUDE_git_message_h__
 
 #include "common.h"
+#include "buffer.h"
 
 /**
  * @file git2/message.h
@@ -23,25 +24,17 @@ GIT_BEGIN_DECL
  *
  * Optionally, can remove lines starting with a "#".
  *
- * @param out The user-allocated buffer which will be filled with the
- *     cleaned up message. Pass NULL if you just want to get the needed
- *     size of the prettified message as the output value.
- *
- * @param out_size Size of the `out` buffer in bytes.
+ * @param out The user-allocated git_buf which will be filled with the
+ *     cleaned up message.
  *
  * @param message The message to be prettified.
  *
  * @param strip_comments Non-zero to remove lines starting with "#", 0 to
  *     leave them in.
  *
- * @return -1 on error, else number of characters in prettified message
- *     including the trailing NUL byte
+ * @return 0 or an error code.
  */
-GIT_EXTERN(int) git_message_prettify(
-	char *out,
-	size_t out_size,
-	const char *message,
-	int strip_comments);
+GIT_EXTERN(int) git_message_prettify(git_buf *out, const char *message, int strip_comments);
 
 /** @} */
 GIT_END_DECL
diff --git a/include/git2/refspec.h b/include/git2/refspec.h
index d96b83ce2..9acdc72d5 100644
--- a/include/git2/refspec.h
+++ b/include/git2/refspec.h
@@ -10,6 +10,7 @@
 #include "common.h"
 #include "types.h"
 #include "net.h"
+#include "buffer.h"
 
 /**
  * @file git2/refspec.h
@@ -82,23 +83,21 @@ GIT_EXTERN(int) git_refspec_dst_matches(const git_refspec *refspec, const char *
  * Transform a reference to its target following the refspec's rules
  *
  * @param out where to store the target name
- * @param outlen the size of the `out` buffer
  * @param spec the refspec
  * @param name the name of the reference to transform
  * @return 0, GIT_EBUFS or another error
  */
-GIT_EXTERN(int) git_refspec_transform(char *out, size_t outlen, const git_refspec *spec, const char *name);
+GIT_EXTERN(int) git_refspec_transform(git_buf *out, const git_refspec *spec, const char *name);
 
 /**
  * Transform a target reference to its source reference following the refspec's rules
  *
  * @param out where to store the source reference name
- * @param outlen the size of the `out` buffer
  * @param spec the refspec
  * @param name the name of the reference to transform
  * @return 0, GIT_EBUFS or another error
  */
-GIT_EXTERN(int) git_refspec_rtransform(char *out, size_t outlen, const git_refspec *spec, const char *name);
+GIT_EXTERN(int) git_refspec_rtransform(git_buf *out, const git_refspec *spec, const char *name);
 
 GIT_END_DECL
 
diff --git a/include/git2/repository.h b/include/git2/repository.h
index 9f71d2959..a0453da5c 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -10,6 +10,7 @@
 #include "common.h"
 #include "types.h"
 #include "oid.h"
+#include "buffer.h"
 
 /**
  * @file git2/repository.h
@@ -58,10 +59,8 @@ GIT_EXTERN(int) git_repository_wrap_odb(git_repository **out, git_odb *odb);
  * The method will automatically detect if the repository is bare
  * (if there is a repository).
  *
- * @param path_out The user allocated buffer which will
- * contain the found path.
- *
- * @param path_size repository_path size
+ * @param out A pointer to a user-allocated git_buf which will contain
+ * the found path.
  *
  * @param start_path The base path where the lookup starts.
  *
@@ -77,8 +76,7 @@ GIT_EXTERN(int) git_repository_wrap_odb(git_repository **out, git_odb *odb);
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_repository_discover(
-		char *path_out,
-		size_t path_size,
+		git_buf *out,
 		const char *start_path,
 		int across_fs,
 		const char *ceiling_dirs);
@@ -464,21 +462,11 @@ GIT_EXTERN(int) git_repository_index(git_index **out, git_repository *repo);
  * Use this function to get the contents of this file. Don't forget to
  * remove the file after you create the commit.
  *
- * If the repository message exists and there are no errors reading it, this
- * returns the bytes needed to store the message in memory (i.e. message
- * file size plus one terminating NUL byte).  That value is returned even if
- * `out` is NULL or `len` is shorter than the necessary size.
- *
- * The `out` buffer will *always* be NUL terminated, even if truncation
- * occurs.
- *
- * @param out Buffer to write data into or NULL to just read required size
- * @param len Length of `out` buffer in bytes
+ * @param out git_buf to write data into
  * @param repo Repository to read prepared message from
- * @return GIT_ENOTFOUND if no message exists, other value < 0 for other
- *         errors, or total bytes in message (may be > `len`) on success
+ * @return 0, GIT_ENOTFOUND if no message exists or an error code
  */
-GIT_EXTERN(int) git_repository_message(char *out, size_t len, git_repository *repo);
+GIT_EXTERN(int) git_repository_message(git_buf *out, git_repository *repo);
 
 /**
  * Remove git's prepared message.