summaryrefslogtreecommitdiff
path: root/Documentation/technical/api-error-handling.txt
blob: ceeedd485c9650de33c10f5465189f4f1a69fc82 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
Error reporting in git
======================
 
`die`, `usage`, `error`, and `warning` report errors of various
kinds.
 
- `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.
 
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);