doc: document error handling functions and conventions
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Nieder committed
Dec 3, 2014 at 19:01 UTC
1f23cfe0ef5b2634a7b911a8b6dc4eff7f78ba5d
1 file changed
+75
Documentation/technical/api-error-handling.txt
new
+75
@@ -0,0 +1,75 @@
1
+Error reporting in git
2
+======================
3
+
4
+`die`, `usage`, `error`, and `warning` report errors of various
5
+kinds.
6
+
7
+- `die` is for fatal application errors. It prints a message to
8
+ the user and exits with status 128.
9
+
10
+- `usage` is for errors in command line usage. After printing its
11
+ message, it exits with status 129. (See also `usage_with_options`
12
+ in the link:api-parse-options.html[parse-options API].)
13
+
14
+- `error` is for non-fatal library errors. It prints a message
15
+ to the user and returns -1 for convenience in signaling the error
16
+ to the caller.
17
+
18
+- `warning` is for reporting situations that probably should not
19
+ occur but which the user (and Git) can continue to work around
20
+ without running into too many problems. Like `error`, it
21
+ returns -1 after reporting the situation to the caller.
22
+
23
+Customizable error handlers
24
+---------------------------
25
+
26
+The default behavior of `die` and `error` is to write a message to
27
+stderr and then exit or return as appropriate. This behavior can be
28
+overridden using `set_die_routine` and `set_error_routine`. For
29
+example, "git daemon" uses set_die_routine to write the reason `die`
30
+was called to syslog before exiting.
31
+
32
+Library errors
33
+--------------
34
+
35
+Functions return a negative integer on error. Details beyond that
36
+vary from function to function:
37
+
38
+- Some functions return -1 for all errors. Others return a more
39
+ specific value depending on how the caller might want to react
40
+ to the error.
41
+
42
+- Some functions report the error to stderr with `error`,
43
+ while others leave that for the caller to do.
44
+
45
+- errno is not meaningful on return from most functions (except
46
+ for thin wrappers for system calls).
47
+
48
+Check the function's API documentation to be sure.
49
+
50
+Caller-handled errors
51
+---------------------
52
+
53
+An increasing number of functions take a parameter 'struct strbuf *err'.
54
+On error, such functions append a message about what went wrong to the
55
+'err' strbuf. The message is meant to be complete enough to be passed
56
+to `die` or `error` as-is. For example:
57
+
58
+ if (ref_transaction_commit(transaction, &err))
59
+ die("%s", err.buf);
60
+
61
+The 'err' parameter will be untouched if no error occured, so multiple
62
+function calls can be chained:
63
+
64
+ t = ref_transaction_begin(&err);
65
+ if (!t ||
66
+ ref_transaction_update(t, "HEAD", ..., &err) ||
67
+ ret_transaction_commit(t, &err))
68
+ die("%s", err.buf);
69
+
70
+The 'err' parameter must be a pointer to a valid strbuf. To silence
71
+a message, pass a strbuf that is explicitly ignored:
72
+
73
+ if (thing_that_can_fail_in_an_ignorable_way(..., &err))
74
+ /* This failure is okay. */
75
+ strbuf_reset(&err);