From a27a4de6f8003961d38958893c6c637395c7cc04 Mon Sep 17 00:00:00 2001 From: Edward Thomson Date: Thu, 10 Jan 2019 22:48:03 +0000 Subject: errors: update docs for giterr changes --- docs/conventions.md | 4 ++-- docs/error-handling.md | 32 ++++++++++++++++---------------- docs/threading.md | 2 +- 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) -- cgit v1.2.1