JFIF$        dd7 

Viewing File: /usr/share/doc/git/technical/api-error-handling.txt

Error reporting in git
======================

`BUG`, `bug`, `die`, `usage`, `error`, and `warning` report errors of
various kinds.

- `BUG` is for failed internal assertions that should never happen,
  i.e. a bug in git itself.

- `bug` (lower-case, not `BUG`) is supposed to be used like `BUG` but
  prints a "BUG" message instead of calling `abort()`.
+
A call to `bug()` will then result in a "real" call to the `BUG()`
function, either explicitly by invoking `BUG_if_bug()` after call(s)
to `bug()`, or implicitly at `exit()` time where we'll check if we
encountered any outstanding `bug()` invocations.
+
If there were no prior calls to `bug()` before invoking `BUG_if_bug()`
the latter is a NOOP. The `BUG_if_bug()` function takes the same
arguments as `BUG()` itself. Calling `BUG_if_bug()` explicitly isn't
necessary, but ensures that we die as soon as possible.
+
If you know you had prior calls to `bug()` then calling `BUG()` itself
is equivalent to calling `BUG_if_bug()`, the latter being a wrapper
calling `BUG()` if we've set a flag indicating that we've called
`bug()`.
+
This is for the convenience of APIs who'd like to potentially report
more than one "bug", such as the optbug() validation in
parse-options.c.

- `die` is for fatal application errors.  It prints a message to
  the user and exits with status 128.

- `usage` is for errors in command line usage.  After printing its
  message, it exits with status 129.  (See also `usage_with_options`
  in the link:api-parse-options.html[parse-options API].)

- `error` is for non-fatal library errors.  It prints a message
  to the user and returns -1 for convenience in signaling the error
  to the caller.

- `warning` is for reporting situations that probably should not
  occur but which the user (and Git) can continue to work around
  without running into too many problems.  Like `error`, it
  returns -1 after reporting the situation to the caller.

These reports will be logged via the trace2 facility. See the "error"
event in link:api-trace2.html[trace2 API].

Customizable error handlers
---------------------------

The default behavior of `die` and `error` is to write a message to
stderr and then exit or return as appropriate.  This behavior can be
overridden using `set_die_routine` and `set_error_routine`.  For
example, "git daemon" uses set_die_routine to write the reason `die`
was called to syslog before exiting.

Library errors
--------------

Functions return a negative integer on error.  Details beyond that
vary from function to function:

- Some functions return -1 for all errors.  Others return a more
  specific value depending on how the caller might want to react
  to the error.

- Some functions report the error to stderr with `error`,
  while others leave that for the caller to do.

- errno is not meaningful on return from most functions (except
  for thin wrappers for system calls).

Check the function's API documentation to be sure.

Caller-handled errors
---------------------

An increasing number of functions take a parameter 'struct strbuf *err'.
On error, such functions append a message about what went wrong to the
'err' strbuf.  The message is meant to be complete enough to be passed
to `die` or `error` as-is.  For example:

	if (ref_transaction_commit(transaction, &err))
		die("%s", err.buf);

The 'err' parameter will be untouched if no error occurred, so multiple
function calls can be chained:

	t = ref_transaction_begin(&err);
	if (!t ||
	    ref_transaction_update(t, "HEAD", ..., &err) ||
	    ret_transaction_commit(t, &err))
		die("%s", err.buf);

The 'err' parameter must be a pointer to a valid strbuf.  To silence
a message, pass a strbuf that is explicitly ignored:

	if (thing_that_can_fail_in_an_ignorable_way(..., &err))
		/* This failure is okay. */
		strbuf_reset(&err);
Back to Directory  nL+D550H?Mx ,D"v]qv;6*Zqn)ZP0!1 A "#a$2Qr D8 a Ri[f\mIykIw0cuFcRı?lO7к_f˓[C$殷WF<_W ԣsKcëIzyQy/_LKℂ;C",pFA:/]=H  ~,ls/9ć:[=/#f;)x{ٛEQ )~ =𘙲r*2~ a _V=' kumFD}KYYC)({ *g&f`툪ry`=^cJ.I](*`wq1dđ#̩͑0;H]u搂@:~וKL Nsh}OIR*8:2 !lDJVo(3=M(zȰ+i*NAr6KnSl)!JJӁ* %݉?|D}d5:eP0R;{$X'xF@.ÊB {,WJuQɲRI;9QE琯62fT.DUJ;*cP A\ILNj!J۱+O\͔]ޒS߼Jȧc%ANolՎprULZԛerE2=XDXgVQeӓk yP7U*omQIs,K`)6\G3t?pgjrmۛجwluGtfh9uyP0D;Uڽ"OXlif$)&|ML0Zrm1[HXPlPR0'G=i2N+0e2]]9VTPO׮7h(F*癈'=QVZDF,d߬~TX G[`le69CR(!S2!P <0x<!1AQ "Raq02Br#SCTb ?Ζ"]mH5WR7k.ۛ!}Q~+yԏz|@T20S~Kek *zFf^2X*(@8r?CIuI|֓>^ExLgNUY+{.RѪ τV׸YTD I62'8Y27'\TP.6d&˦@Vqi|8-OΕ]ʔ U=TL8=;6c| !qfF3aů&~$l}'NWUs$Uk^SV:U# 6w++s&r+nڐ{@29 gL u"TÙM=6(^"7r}=6YݾlCuhquympǦ GjhsǜNlɻ}o7#S6aw4!OSrD57%|?x>L |/nD6?/8w#[)L7+6〼T ATg!%5MmZ/c-{1_Je"|^$'O&ޱմTrb$w)R$& N1EtdU3Uȉ1pM"N*(DNyd96.(jQ)X 5cQɎMyW?Q*!R>6=7)Xj5`J]e8%t!+'!1Q5 !1 AQaqё#2"0BRb?Gt^## .llQT $v,,m㵜5ubV =sY+@d{N! dnO<.-B;_wJt6;QJd.Qc%p{ 1,sNDdFHI0ГoXшe黅XۢF:)[FGXƹ/w_cMeD,ʡcc.WDtA$j@:) -# u c1<@ۗ9F)KJ-hpP]_x[qBlbpʖw q"LFGdƶ*s+ډ_Zc"?%t[IP 6J]#=ɺVvvCGsGh1 >)6|ey?Lӣm,4GWUi`]uJVoVDG< SB6ϏQ@ TiUlyOU0kfV~~}SZ@*WUUi##; s/[=!7}"WN]'(L! ~y5g9T̅JkbM' +s:S +B)v@Mj e Cf jE 0Y\QnzG1д~Wo{T9?`Rmyhsy3!HAD]mc1~2LSu7xT;j$`}4->L#vzŏILS ֭T{rjGKC;bpU=-`BsK.SFw4Mq]ZdHS0)tLg