From de062c141784f76d753e8c5aa891fa7e8a6fe7e6 Mon Sep 17 00:00:00 2001 From: Brendan Jurd Date: Fri, 24 Sep 2021 16:08:15 +1000 Subject: DOC: Add content for Development/Error handling page. This page was previously empty. This commits populates it with some very basic information and a code example of how to use proj_context_errno and proj_context_errno_string. Something: because something is better than nothing. It might be good to include some more fine detail about how PROJ manages the error state internally, but I don't yet have the expertise in PROJ internals to write that content myself. Also the code sample probably has a segfault bug or leaks memory, because C. --- docs/source/development/errorhandling.rst | 58 +++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) (limited to 'docs/source') diff --git a/docs/source/development/errorhandling.rst b/docs/source/development/errorhandling.rst index 58199e3f..021d2fb7 100644 --- a/docs/source/development/errorhandling.rst +++ b/docs/source/development/errorhandling.rst @@ -4,4 +4,62 @@ Error handling ================================================================================ +PROJ maintains an internal error state, which is local to a +:c:type:`PJ_CONTEXT` thread context. +See :doc:`quickstart` for more information about how to create and use a thread +context object. + +If you receive an abnormal return from a PROJ API function (e.g. a NULL +pointer) you may wish to discover more information about the error. + +In this case you can make a call to :c:func:`proj_context_errno`, passing in +your thread context. This will return an integer error code. + +If the error code is zero, the last PROJ operation was deemed successful and no +error has been detected. + +If the error code is non-zero, an error has been detected. You can pass your +thread context together with this error code to +:c:func:`proj_context_errno_string` to retrieve a string describing the error +condition. + +A basic example showing how a C program might catch and report errors follows: + +.. code-block:: c + :caption: errorhandling.c + :linenos: + + #include + #include + + int main (void) { + PJ_CONTEXT *c; + PJ *p; + int errno; + const char *errstr; + + c = proj_context_create(); + p = proj_create_crs_to_crs(c, "EPSG:4326", "EPSG:3857", NULL); + + if (p == 0) { + /* Something is wrong, let's try to get details ... */ + errno = proj_context_errno(c); + if (errno == 0) { + /* This should be impossible. */ + fprintf(stderr, "Failed to create transformation, reason unknown.\n"); + } else { + errstr = proj_context_errno_string(c, errno); + fprintf(stderr, "Failed to create transformation: %s.\n", errstr); + } + proj_context_destroy(c); + return 1; + } + + /* transformation object is valid, do work ... */ + + proj_destroy(p); + proj_context_destroy(c); + + return 0; + } -- cgit v1.2.3