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         /* GIT_EUSER is a special error that is never generated by libgit2
  31          * code.  You can return it from a callback (e.g to stop an iteration)
  32          * to know that it was generated by the callback and not by libgit2.
  33          */
  34         GIT_EUSER      = -7,
  35
  36         GIT_EBAREREPO       =  -8,      /*< Operation not allowed on bare repository */
  37         GIT_EUNBORNBRANCH   =  -9,      /*< HEAD refers to branch with no commits */
  38         GIT_EUNMERGED       = -10,      /*< Merge in progress prevented operation */
  39         GIT_ENONFASTFORWARD = -11,      /*< Reference was not fast-forwardable */
  40         GIT_EINVALIDSPEC    = -12,      /*< Name/ref spec was not in a valid format */
  41         GIT_EMERGECONFLICT  = -13,      /*< Merge conflicts prevented operation */
  42         GIT_ELOCKED         = -14,      /*< Lock file prevented operation */
  43         GIT_EMODIFIED       = -15,      /*< Reference value does not match expected */
  44         GIT_ENOACCESS       = -16,      /*< Access denied attempting operation */
  45
  46         GIT_PASSTHROUGH     = -30,      /*< Internal only */
  47         GIT_ITEROVER        = -31,      /*< Signals end of iteration with iterator */
  48 } git_error_code;
  49
  50 /**
  51  * Structure to store extra details of the last error that occurred.
  52  *
  53  * This is kept on a per-thread basis if GIT_THREADS was defined when the
  54  * library was build, otherwise one is kept globally for the library
  55  */
  56 typedef struct {
  57         char *message;
  58         int klass;
  59 } git_error;
  60
  61 /** Error classes */
  62 typedef enum {
  63         GITERR_NONE = 0,
  64         GITERR_NOMEMORY,
  65         GITERR_OS,
  66         GITERR_INVALID,
  67         GITERR_REFERENCE,
  68         GITERR_ZLIB,
  69         GITERR_REPOSITORY,
  70         GITERR_CONFIG,
  71         GITERR_REGEX,
  72         GITERR_ODB,
  73         GITERR_INDEX,
  74         GITERR_OBJECT,
  75         GITERR_NET,
  76         GITERR_TAG,
  77         GITERR_TREE,
  78         GITERR_INDEXER,
  79         GITERR_SSL,
  80         GITERR_SUBMODULE,
  81         GITERR_THREAD,
  82         GITERR_STASH,
  83         GITERR_CHECKOUT,
  84         GITERR_FETCHHEAD,
  85         GITERR_MERGE,
  86         GITERR_SSH,
  87         GITERR_FILTER,
  88         GITERR_REVERT,
  89         GITERR_CALLBACK,
  90         GITERR_CHERRYPICK,
  91 } git_error_t;
  92
  93 /**
  94  * Return the last `git_error` object that was generated for the
  95  * current thread or NULL if no error has occurred.
  96  *
  97  * @return A git_error object.
  98  */
  99 GIT_EXTERN(const git_error *) giterr_last(void);
 100
 101 /**
 102  * Clear the last library error that occurred for this thread.
 103  */
 104 GIT_EXTERN(void) giterr_clear(void);
 105
 106 /**
 107  * Get the last error data and clear it.
 108  *
 109  * This copies the last error into the given `git_error` struct
 110  * and returns 0 if the copy was successful, leaving the error
 111  * cleared as if `giterr_clear` had been called.
 112  *
 113  * If there was no existing error in the library, -1 will be returned
 114  * and the contents of `cpy` will be left unmodified.
 115  */
 116 GIT_EXTERN(int) giterr_detach(git_error *cpy);
 117
 118 /**
 119  * Set the error message string for this thread.
 120  *
 121  * This function is public so that custom ODB backends and the like can
 122  * relay an error message through libgit2.  Most regular users of libgit2
 123  * will never need to call this function -- actually, calling it in most
 124  * circumstances (for example, calling from within a callback function)
 125  * will just end up having the value overwritten by libgit2 internals.
 126  *
 127  * This error message is stored in thread-local storage and only applies
 128  * to the particular thread that this libgit2 call is made from.
 129  *
 130  * NOTE: Passing the `error_class` as GITERR_OS has a special behavior: we
 131  * attempt to append the system default error message for the last OS error
 132  * that occurred and then clear the last error.  The specific implementation
 133  * of looking up and clearing this last OS error will vary by platform.
 134  *
 135  * @param error_class One of the `git_error_t` enum above describing the
 136  *                    general subsystem that is responsible for the error.
 137  * @param string The formatted error message to keep
 138  */
 139 GIT_EXTERN(void) giterr_set_str(int error_class, const char *string);
 140
 141 /**
 142  * Set the error message to a special value for memory allocation failure.
 143  *
 144  * The normal `giterr_set_str()` function attempts to `strdup()` the string
 145  * that is passed in.  This is not a good idea when the error in question
 146  * is a memory allocation failure.  That circumstance has a special setter
 147  * function that sets the error string to a known and statically allocated
 148  * internal value.
 149  */
 150 GIT_EXTERN(void) giterr_set_oom(void);
 151
 152 /** @} */
 153 GIT_END_DECL
 154 #endif