"Fossies" - the Fresh Open Source Software Archive

Member "technical/api-error-handling.txt" (15 Dec 2018, 2591 Bytes) of package /linux/misc/git-htmldocs-2.20.1.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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 occurred, 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);