summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorEdward Thomson <ethomson@edwardthomson.com>2019-01-10 22:48:03 +0000
committerEdward Thomson <ethomson@edwardthomson.com>2019-01-22 22:30:37 +0000
commita27a4de6f8003961d38958893c6c637395c7cc04 (patch)
tree9156b0eae8ff19b7e2e0bb8eb76d38ce35baac5c
parent00c66dfd3b531c63e6e5ec99fe94a7ceedc89173 (diff)
downloadlibgit2-ethomson/giterr.tar.gz
errors: update docs for giterr changesethomson/giterr
-rw-r--r--docs/conventions.md4
-rw-r--r--docs/error-handling.md32
-rw-r--r--docs/threading.md2
3 files changed, 19 insertions, 19 deletions
diff --git a/docs/conventions.md b/docs/conventions.md
index c8a39dd2b..a017db11c 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -136,11 +136,11 @@ Check
[`include/git2/errors.h`](https://github.com/libgit2/libgit2/blob/development/include/git2/errors.h)
for the return codes already defined.
-In your implementation, use `giterr_set()` to provide extended error
+In your implementation, use `git_error_set()` to provide extended error
information to callers.
If a `libgit2` function internally invokes another function that reports an
-error, but the error is not propagated up, use `giterr_clear()` to prevent
+error, but the error is not propagated up, use `git_error_clear()` to prevent
callers from getting the wrong error message later on.
diff --git a/docs/error-handling.md b/docs/error-handling.md
index 0dba01cd9..8df9a4074 100644
--- a/docs/error-handling.md
+++ b/docs/error-handling.md
@@ -9,7 +9,7 @@ and a generic error code (-1) for all critical or non-specific failures
(e.g. running out of memory or system corruption).
When a negative value is returned, an error message is also set. The
-message can be accessed via the `giterr_last` function which will return a
+message can be accessed via the `git_error_last` function which will return a
pointer to a `git_error` structure containing the error message text and
the class of error (i.e. what part of the library generated the error).
@@ -51,7 +51,7 @@ look at the error message that was generated.
int error = git_repository_open(&repo, "path/to/repo");
if (error < 0) {
- fprintf(stderr, "Could not open repository: %s\n", giterr_last()->message);
+ fprintf(stderr, "Could not open repository: %s\n", git_error_last()->message);
exit(1);
}
@@ -75,7 +75,7 @@ at the specific error values to decide what to do.
fprintf(stderr, "Could not find repository at path '%s'\n", path);
else
fprintf(stderr, "Unable to open repository: %s\n",
- giterr_last()->message);
+ git_error_last()->message);
exit(1);
}
@@ -86,7 +86,7 @@ at the specific error values to decide what to do.
Some of the higher-level language bindings may use a range of information
from libgit2 to convert error return codes into exceptions, including the
specific error return codes and even the class of error and the error
-message returned by `giterr_last`, but the full range of that logic is
+message returned by `git_error_last`, but the full range of that logic is
beyond the scope of this document.
Example internal implementation
@@ -102,7 +102,7 @@ int git_repository_open(git_repository **repository, const char *path)
{
/* perform some logic to open the repository */
if (p_exists(path) < 0) {
- giterr_set(GITERR_REPOSITORY, "The path '%s' doesn't exist", path);
+ git_error_set(GIT_ERROR_REPOSITORY, "The path '%s' doesn't exist", path);
return GIT_ENOTFOUND;
}
@@ -113,7 +113,7 @@ int git_repository_open(git_repository **repository, const char *path)
The public error API
--------------------
-- `const git_error *giterr_last(void)`: The main function used to look up
+- `const git_error *git_error_last(void)`: The main function used to look up
the last error. This may return NULL if no error has occurred.
Otherwise this should return a `git_error` object indicating the class
of error and the error message that was generated by the library.
@@ -133,7 +133,7 @@ The public error API
bugs, but in the meantime, please code defensively and check for NULL
when calling this function.
-- `void giterr_clear(void)`: This function clears the last error. The
+- `void git_error_clear(void)`: This function clears the last error. The
library will call this when an error is generated by low level function
and the higher level function handles the error.
@@ -141,14 +141,14 @@ The public error API
function's error message is not cleared by higher level code that
handles the error and returns zero. Please report these as bugs, but in
the meantime, a zero return value from a libgit2 API does not guarantee
- that `giterr_last()` will return NULL.
+ that `git_error_last()` will return NULL.
-- `void giterr_set_str(int error_class, const char *message)`: This
+- `void git_error_set(int error_class, const char *message)`: This
function can be used when writing a custom backend module to set the
libgit2 error message. See the documentation on this function for its
use. Normal usage of libgit2 will probably never need to call this API.
-- `void giterr_set_oom(void)`: This is a standard function for reporting
+- `void git_error_set_oom(void)`: This is a standard function for reporting
an out-of-memory error. It is written in a manner that it doesn't have
to allocate any extra memory in order to record the error, so this is
the best way to report that scenario.
@@ -182,18 +182,18 @@ There are some known bugs in the library where some functions may return a
negative value but not set an error message and some other functions may
return zero (no error) and yet leave an error message set. Please report
these cases as issues and they will be fixed. In the meanwhile, please
-code defensively, checking that the return value of `giterr_last` is not
-NULL before using it, and not relying on `giterr_last` to return NULL when
+code defensively, checking that the return value of `git_error_last` is not
+NULL before using it, and not relying on `git_error_last` to return NULL when
a function returns 0 for success.
The internal error API
----------------------
-- `void giterr_set(int error_class, const char *fmt, ...)`: This is the
+- `void git_error_set(int error_class, const char *fmt, ...)`: This is the
main internal function for setting an error. It works like `printf` to
- format the error message. See the notes of `giterr_set_str` for a
+ format the error message. See the notes of `git_error_set_str` for a
general description of how error messages are stored (and also about
- special handling for `error_class` of `GITERR_OS`).
+ special handling for `error_class` of `GIT_ERROR_OS`).
Writing error messages
----------------------
@@ -248,7 +248,7 @@ General guidelines for error reporting
...
if (git_commit_lookup(parent, repo, parent_id) < 0) {
- giterr_set(GITERR_COMMIT, "Overwrite lookup error message");
+ git_error_set(GIT_ERROR_COMMIT, "Overwrite lookup error message");
return -1; /* mask error code */
}
diff --git a/docs/threading.md b/docs/threading.md
index 430bca858..7dd37444f 100644
--- a/docs/threading.md
+++ b/docs/threading.md
@@ -22,7 +22,7 @@ snapshots.
Error messages
--------------
-The error message is thread-local. The `giterr_last()` call must
+The error message is thread-local. The `git_error_last()` call must
happen on the same thread as the error in order to get the
message. Often this will be the case regardless, but if you use
something like the [GCD](http://en.wikipedia.org/wiki/Grand_Central_Dispatch)