From 69c2e0349794fb09717336c83553f27775ea6052 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 27 Sep 2021 09:18:59 +0200 Subject: Merge pull request #2865 from direvus/doc/2864-error-handling DOC: Add content for Development/Error handling page. --- docs/source/development/errorhandling.rst | 58 +++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) 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