Skip to content
Projects
Groups
Snippets
Help
This project
Loading...
Sign in / Register
Toggle navigation
G
git2
Overview
Overview
Details
Activity
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
0
Issues
0
List
Board
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Charts
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
lvzhengyang
git2
Commits
a27a4de6
Commit
a27a4de6
authored
Jan 10, 2019
by
Edward Thomson
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
errors: update docs for giterr changes
parent
00c66dfd
Show whitespace changes
Inline
Side-by-side
Showing
3 changed files
with
19 additions
and
19 deletions
+19
-19
docs/conventions.md
+2
-2
docs/error-handling.md
+16
-16
docs/threading.md
+1
-1
No files found.
docs/conventions.md
View file @
a27a4de6
...
...
@@ -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
`git
er
r_set()`
to provide extended error
In your implementation, use
`git
_erro
r_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
`git
er
r_clear()`
to prevent
error, but the error is not propagated up, use
`git
_erro
r_clear()`
to prevent
callers from getting the wrong error message later on.
...
...
docs/error-handling.md
View file @
a27a4de6
...
...
@@ -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
`git
er
r_last`
function which will return a
message can be accessed via the
`git
_erro
r_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
"
,
git
er
r_last
()
->
message
);
fprintf
(
stderr
,
"Could not open repository: %s
\n
"
,
git
_erro
r_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
"
,
git
er
r_last
()
->
message
);
git
_erro
r_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
`git
er
r_last`
, but the full range of that logic is
message returned by
`git
_erro
r_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
)
{
git
err_set
(
GITER
R_REPOSITORY
,
"The path '%s' doesn't exist"
,
path
);
git
_error_set
(
GIT_ERRO
R_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 *git
er
r_last(void)`
: The main function used to look up
-
`const git_error *git
_erro
r_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 git
er
r_clear(void)`
: This function clears the last error. The
-
`void git
_erro
r_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
`git
er
r_last()`
will return NULL.
that
`git
_erro
r_last()`
will return NULL.
-
`void git
err_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 git
er
r_set_oom(void)`
: This is a standard function for reporting
-
`void git
_erro
r_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
`git
er
r_last`
is not
NULL before using it, and not relying on
`git
er
r_last`
to return NULL when
code defensively, checking that the return value of
`git
_erro
r_last`
is not
NULL before using it, and not relying on
`git
_erro
r_last`
to return NULL when
a function returns 0 for success.
The internal error API
----------------------
-
`void git
er
r_set(int error_class, const char *fmt, ...)`
: This is the
-
`void git
_erro
r_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
`git
er
r_set_str`
for a
format the error message. See the notes of
`git
_erro
r_set_str`
for a
general description of how error messages are stored (and also about
special handling for
`error_class`
of
`GIT
ER
R_OS`
).
special handling for
`error_class`
of
`GIT
_ERRO
R_OS`
).
Writing error messages
----------------------
...
...
@@ -248,7 +248,7 @@ General guidelines for error reporting
...
if (git_commit_lookup(parent, repo, parent_id) < 0) {
git
err_set(GITER
R_COMMIT, "Overwrite lookup error message");
git
_error_set(GIT_ERRO
R_COMMIT, "Overwrite lookup error message");
return -1; /* mask error code */
}
...
...
docs/threading.md
View file @
a27a4de6
...
...
@@ -22,7 +22,7 @@ snapshots.
Error messages
--------------
The error message is thread-local. The
`git
er
r_last()`
call must
The error message is thread-local. The
`git
_erro
r_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
)
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment