technical/api-error-handling.txt

   1 Error reporting in git
   2 ======================
   3
   4 `BUG`, `bug`, `die`, `usage`, `error`, and `warning` report errors of
   5 various kinds.
   6
   7 - `BUG` is for failed internal assertions that should never happen,
   8   i.e. a bug in git itself.
   9
  10 - `bug` (lower-case, not `BUG`) is supposed to be used like `BUG` but
  11   prints a "BUG" message instead of calling `abort()`.
  12 +
  13 A call to `bug()` will then result in a "real" call to the `BUG()`
  14 function, either explicitly by invoking `BUG_if_bug()` after call(s)
  15 to `bug()`, or implicitly at `exit()` time where we'll check if we
  16 encountered any outstanding `bug()` invocations.
  17 +
  18 If there were no prior calls to `bug()` before invoking `BUG_if_bug()`
  19 the latter is a NOOP. The `BUG_if_bug()` function takes the same
  20 arguments as `BUG()` itself. Calling `BUG_if_bug()` explicitly isn't
  21 necessary, but ensures that we die as soon as possible.
  22 +
  23 If you know you had prior calls to `bug()` then calling `BUG()` itself
  24 is equivalent to calling `BUG_if_bug()`, the latter being a wrapper
  25 calling `BUG()` if we've set a flag indicating that we've called
  26 `bug()`.
  27 +
  28 This is for the convenience of APIs who'd like to potentially report
  29 more than one "bug", such as the optbug() validation in
  30 parse-options.c.
  31
  32 - `die` is for fatal application errors.  It prints a message to
  33   the user and exits with status 128.
  34
  35 - `usage` is for errors in command line usage.  After printing its
  36   message, it exits with status 129.  (See also `usage_with_options`
  37   in the link:api-parse-options.html[parse-options API].)
  38
  39 - `error` is for non-fatal library errors.  It prints a message
  40   to the user and returns -1 for convenience in signaling the error
  41   to the caller.
  42
  43 - `warning` is for reporting situations that probably should not
  44   occur but which the user (and Git) can continue to work around
  45   without running into too many problems.  Like `error`, it
  46   returns -1 after reporting the situation to the caller.
  47
  48 These reports will be logged via the trace2 facility. See the "error"
  49 event in link:api-trace2.html[trace2 API].
  50
  51 Customizable error handlers
  52 ---------------------------
  53
  54 The default behavior of `die` and `error` is to write a message to
  55 stderr and then exit or return as appropriate.  This behavior can be
  56 overridden using `set_die_routine` and `set_error_routine`.  For
  57 example, "git daemon" uses set_die_routine to write the reason `die`
  58 was called to syslog before exiting.
  59
  60 Library errors
  61 --------------
  62
  63 Functions return a negative integer on error.  Details beyond that
  64 vary from function to function:
  65
  66 - Some functions return -1 for all errors.  Others return a more
  67   specific value depending on how the caller might want to react
  68   to the error.
  69
  70 - Some functions report the error to stderr with `error`,
  71   while others leave that for the caller to do.
  72
  73 - errno is not meaningful on return from most functions (except
  74   for thin wrappers for system calls).
  75
  76 Check the function's API documentation to be sure.
  77
  78 Caller-handled errors
  79 ---------------------
  80
  81 An increasing number of functions take a parameter 'struct strbuf *err'.
  82 On error, such functions append a message about what went wrong to the
  83 'err' strbuf.  The message is meant to be complete enough to be passed
  84 to `die` or `error` as-is.  For example:
  85
  86         if (ref_transaction_commit(transaction, &err))
  87                 die("%s", err.buf);
  88
  89 The 'err' parameter will be untouched if no error occurred, so multiple
  90 function calls can be chained:
  91
  92         t = ref_transaction_begin(&err);
  93         if (!t ||
  94             ref_transaction_update(t, "HEAD", ..., &err) ||
  95             ret_transaction_commit(t, &err))
  96                 die("%s", err.buf);
  97
  98 The 'err' parameter must be a pointer to a valid strbuf.  To silence
  99 a message, pass a strbuf that is explicitly ignored:
 100
 101         if (thing_that_can_fail_in_an_ignorable_way(..., &err))
 102                 /* This failure is okay. */
 103                 strbuf_reset(&err);