include/git2/errors.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_git_errors_h__
   8 #define INCLUDE_git_errors_h__
   9
  10 #include "common.h"
  11
  12 /**
  13  * @file git2/errors.h
  14  * @brief Git error handling routines and variables
  15  * @ingroup Git
  16  * @{
  17  */
  18 GIT_BEGIN_DECL
  19
  20 /** Generic return codes */
  21 typedef enum {
  22         GIT_OK         =  0,            /**< No error */
  23
  24         GIT_ERROR      = -1,            /**< Generic error */
  25         GIT_ENOTFOUND  = -3,            /**< Requested object could not be found */
  26         GIT_EEXISTS    = -4,            /**< Object exists preventing operation */
  27         GIT_EAMBIGUOUS = -5,            /**< More than one object matches */
  28         GIT_EBUFS      = -6,            /**< Output buffer too short to hold data */
  29
  30         /**
  31          * GIT_EUSER is a special error that is never generated by libgit2
  32          * code.  You can return it from a callback (e.g to stop an iteration)
  33          * to know that it was generated by the callback and not by libgit2.
  34          */
  35         GIT_EUSER      = -7,
  36
  37         GIT_EBAREREPO       =  -8,      /**< Operation not allowed on bare repository */
  38         GIT_EUNBORNBRANCH   =  -9,      /**< HEAD refers to branch with no commits */
  39         GIT_EUNMERGED       = -10,      /**< Merge in progress prevented operation */
  40         GIT_ENONFASTFORWARD = -11,      /**< Reference was not fast-forwardable */
  41         GIT_EINVALIDSPEC    = -12,      /**< Name/ref spec was not in a valid format */
  42         GIT_ECONFLICT       = -13,      /**< Checkout conflicts prevented operation */
  43         GIT_ELOCKED         = -14,      /**< Lock file prevented operation */
  44         GIT_EMODIFIED       = -15,      /**< Reference value does not match expected */
  45         GIT_EAUTH           = -16,      /**< Authentication error */
  46         GIT_ECERTIFICATE    = -17,      /**< Server certificate is invalid */
  47         GIT_EAPPLIED        = -18,      /**< Patch/merge has already been applied */
  48         GIT_EPEEL           = -19,      /**< The requested peel operation is not possible */
  49         GIT_EEOF            = -20,      /**< Unexpected EOF */
  50         GIT_EINVALID        = -21,      /**< Invalid operation or input */
  51         GIT_EUNCOMMITTED    = -22,      /**< Uncommitted changes in index prevented operation */
  52         GIT_EDIRECTORY      = -23,      /**< The operation is not valid for a directory */
  53         GIT_EMERGECONFLICT  = -24,      /**< A merge conflict exists and cannot continue */
  54
  55         GIT_PASSTHROUGH     = -30,      /**< A user-configured callback refused to act */
  56         GIT_ITEROVER        = -31,      /**< Signals end of iteration with iterator */
  57         GIT_RETRY           = -32,      /**< Internal only */
  58         GIT_EMISMATCH       = -33,      /**< Hashsum mismatch in object */
  59         GIT_EINDEXDIRTY     = -34,      /**< Unsaved changes in the index would be overwritten */
  60         GIT_EAPPLYFAIL      = -35,      /**< Patch application failed */
  61 } git_error_code;
  62
  63 /**
  64  * Structure to store extra details of the last error that occurred.
  65  *
  66  * This is kept on a per-thread basis if GIT_THREADS was defined when the
  67  * library was build, otherwise one is kept globally for the library
  68  */
  69 typedef struct {
  70         char *message;
  71         int klass;
  72 } git_error;
  73
  74 /** Error classes */
  75 typedef enum {
  76         GIT_ERROR_NONE = 0,
  77         GIT_ERROR_NOMEMORY,
  78         GIT_ERROR_OS,
  79         GIT_ERROR_INVALID,
  80         GIT_ERROR_REFERENCE,
  81         GIT_ERROR_ZLIB,
  82         GIT_ERROR_REPOSITORY,
  83         GIT_ERROR_CONFIG,
  84         GIT_ERROR_REGEX,
  85         GIT_ERROR_ODB,
  86         GIT_ERROR_INDEX,
  87         GIT_ERROR_OBJECT,
  88         GIT_ERROR_NET,
  89         GIT_ERROR_TAG,
  90         GIT_ERROR_TREE,
  91         GIT_ERROR_INDEXER,
  92         GIT_ERROR_SSL,
  93         GIT_ERROR_SUBMODULE,
  94         GIT_ERROR_THREAD,
  95         GIT_ERROR_STASH,
  96         GIT_ERROR_CHECKOUT,
  97         GIT_ERROR_FETCHHEAD,
  98         GIT_ERROR_MERGE,
  99         GIT_ERROR_SSH,
 100         GIT_ERROR_FILTER,
 101         GIT_ERROR_REVERT,
 102         GIT_ERROR_CALLBACK,
 103         GIT_ERROR_CHERRYPICK,
 104         GIT_ERROR_DESCRIBE,
 105         GIT_ERROR_REBASE,
 106         GIT_ERROR_FILESYSTEM,
 107         GIT_ERROR_PATCH,
 108         GIT_ERROR_WORKTREE,
 109         GIT_ERROR_SHA1,
 110         GIT_ERROR_HTTP,
 111         GIT_ERROR_INTERNAL
 112 } git_error_t;
 113
 114 /**
 115  * Return the last `git_error` object that was generated for the
 116  * current thread.
 117  *
 118  * The default behaviour of this function is to return NULL if no previous error has occurred.
 119  * However, libgit2's error strings are not cleared aggressively, so a prior
 120  * (unrelated) error may be returned. This can be avoided by only calling
 121  * this function if the prior call to a libgit2 API returned an error.
 122  *
 123  * @return A git_error object.
 124  */
 125 GIT_EXTERN(const git_error *) git_error_last(void);
 126
 127 /**
 128  * Clear the last library error that occurred for this thread.
 129  */
 130 GIT_EXTERN(void) git_error_clear(void);
 131
 132 /**
 133  * Set the error message string for this thread.
 134  *
 135  * This function is public so that custom ODB backends and the like can
 136  * relay an error message through libgit2.  Most regular users of libgit2
 137  * will never need to call this function -- actually, calling it in most
 138  * circumstances (for example, calling from within a callback function)
 139  * will just end up having the value overwritten by libgit2 internals.
 140  *
 141  * This error message is stored in thread-local storage and only applies
 142  * to the particular thread that this libgit2 call is made from.
 143  *
 144  * @param error_class One of the `git_error_t` enum above describing the
 145  *                    general subsystem that is responsible for the error.
 146  * @param string The formatted error message to keep
 147  * @return 0 on success or -1 on failure
 148  */
 149 GIT_EXTERN(int) git_error_set_str(int error_class, const char *string);
 150
 151 /**
 152  * Set the error message to a special value for memory allocation failure.
 153  *
 154  * The normal `git_error_set_str()` function attempts to `strdup()` the
 155  * string that is passed in.  This is not a good idea when the error in
 156  * question is a memory allocation failure.  That circumstance has a
 157  * special setter function that sets the error string to a known and
 158  * statically allocated internal value.
 159  */
 160 GIT_EXTERN(void) git_error_set_oom(void);
 161
 162 /** @} */
 163 GIT_END_DECL
 164 #endif