git2/sys/errors.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
0008 #ifndef INCLUDE_sys_git_errors_h__
0009 #define INCLUDE_sys_git_errors_h__
0010
0011 #include "git2/common.h"
0012
0013 GIT_BEGIN_DECL
0014
0015 /**
0016  * Clear the last library error that occurred for this thread.
0017  */
0018 GIT_EXTERN(void) git_error_clear(void);
0019
0020 /**
0021  * Set the error message string for this thread, using `printf`-style
0022  * formatting.
0023  *
0024  * This function is public so that custom ODB backends and the like can
0025  * relay an error message through libgit2.  Most regular users of libgit2
0026  * will never need to call this function -- actually, calling it in most
0027  * circumstances (for example, calling from within a callback function)
0028  * will just end up having the value overwritten by libgit2 internals.
0029  *
0030  * This error message is stored in thread-local storage and only applies
0031  * to the particular thread that this libgit2 call is made from.
0032  *
0033  * @param error_class One of the `git_error_t` enum above describing the
0034  *                    general subsystem that is responsible for the error.
0035  * @param fmt The `printf`-style format string; subsequent arguments must
0036  *            be the arguments for the format string.
0037  */
0038 GIT_EXTERN(void) git_error_set(int error_class, const char *fmt, ...)
0039                  GIT_FORMAT_PRINTF(2, 3);
0040
0041 /**
0042  * Set the error message string for this thread.  This function is like
0043  * `git_error_set` but takes a static string instead of a `printf`-style
0044  * format.
0045  *
0046  * @param error_class One of the `git_error_t` enum above describing the
0047  *                    general subsystem that is responsible for the error.
0048  * @param string The error message to keep
0049  * @return 0 on success or -1 on failure
0050  */
0051 GIT_EXTERN(int) git_error_set_str(int error_class, const char *string);
0052
0053 /**
0054  * Set the error message to a special value for memory allocation failure.
0055  *
0056  * The normal `git_error_set_str()` function attempts to `strdup()` the
0057  * string that is passed in.  This is not a good idea when the error in
0058  * question is a memory allocation failure.  That circumstance has a
0059  * special setter function that sets the error string to a known and
0060  * statically allocated internal value.
0061  */
0062 GIT_EXTERN(void) git_error_set_oom(void);
0063
0064 GIT_END_DECL
0065
0066 #endif