Make giterr_set_str public

There has been discussion for a while about making some set of
the `giterr_set` type functions part of the public API for code
that is implementing new backends to libgit2.  This makes the
`giterr_set_str()` and `giterr_set_oom()` functions public.

1 files changed, 34 insertions, 0 deletions

diff --git a/include/git2/errors.h b/include/git2/errors.h
index e5f435926..f6d9bf2e3 100644
--- a/include/git2/errors.h
+++ b/include/git2/errors.h
@@ -71,6 +71,40 @@ GIT_EXTERN(const git_error *) giterr_last(void);
  */
 GIT_EXTERN(void) giterr_clear(void);
 
+/**
+ * Set the error message string for this thread.
+ *
+ * This function is public so that custom ODB backends and the like can
+ * relay an error message through libgit2.  Most regular users of libgit2
+ * will never need to call this function -- actually, calling it in most
+ * circumstances (for example, calling from within a callback function)
+ * will just end up having the value overwritten by libgit2 internals.
+ *
+ * This error message is stored in thread-local storage and only applies
+ * to the particular thread that this libgit2 call is made from.
+ *
+ * NOTE: Passing the `error_class` as GITERR_OS has a special behavior: we
+ * attempt to append the system default error message for the last OS error
+ * that occurred and then clear the last error.  The specific implementation
+ * of looking up and clearing this last OS error will vary by platform.
+ *
+ * @param error_class One of the `git_error_t` enum above describing the
+ *                    general subsystem that is responsible for the error.
+ * @param message The formatted error message to keep
+ */
+GIT_EXTERN(void) giterr_set_str(int error_class, const char *string);
+
+/**
+ * Set the error message to a special value for memory allocation failure.
+ *
+ * The normal `giterr_set_str()` function attempts to `strdup()` the string
+ * that is passed in.  This is not a good idea when the error in question
+ * is a memory allocation failure.  That circumstance has a special setter
+ * function that sets the error string to a known and statically allocated
+ * internal value.
+ */
+GIT_EXTERN(void) giterr_set_oom(void);
+
 /** @} */
 GIT_END_DECL
 #endif