Dealing with errors in the GNU PDF Library
The most effective debugging tool is still careful thought, coupled with judiciously placed print statements (Brian Kernighan)
The GNU PDF project takes testing very seriously. Despite this, while programming functionalities that rely on uderlying modules, a returning value reporting if something went wrong in a call has a very high value. So, in this post I am going to explain how to output typical errors in the stderr stream when we are calling almost any functionality in the pdf.h interface.
The key data type here is pdf_status_t. As you can see in the reference manual, almost any function returns a pdf_status_t. For instance, supose that we are creating a new token reader (or tokeniser) for a given stream; the header is
pdf_status_t pdf_token_reader_new (pdf_stm_t stm, pdf_token_reader_t *reader)
The return value can be compared typically with a PDF status value like PDF_OK or PDF_ERROR this way
-
if (pdf_token_reader_new (stream, &reader) != PDF_OK)
in order to treat error flows. But sometimes we want to know what kind of error happened, instead of knowing if some did occur. To achieve this, we need a function that outputs the corresponding error message to stderr:
void pdf_perror (const pdf_status_t status, const char *str)
Calling it, we get a description of the status contents for a given pdf_status_t data type. So, in our example, this code
-
pdf_status_t token_stat;
-
pdf_token_reader_t reader;
-
-
token_stat = pdf_token_reader_new (stream, &reader);
-
-
if (token_stat != PDF_OK)
-
{
-
printf("ERROR creating tokeniser\n");
-
pdf_perror(token_stat, NULL);
-
}
easily helps us to know what happened if something went wrong. Note that the pdf_perror function gets a desired string to concatenate to the error message as the second parameter.
IMPORTANT UPDATE: Please read Aleksander’s comments here, containing very useful and updated information about new error reporting / printing procedures.
This entry is filed under C library, GNU PDF, Programming. And tagged with error output, gnupdf, programming. You can follow any responses to this entry through RSS 2.0. You can leave a response, or trackback from your own site.
Hola Aleksander!
Thanks for your comments, I was totally caught in the middle of the transition between pdf_status_t and pdf_error_t
As pdf_status_t has been my salvation in my first steps in GNU PDF I needed to explain it here, but of course I like much more the GLib’s way. The mailing list message had gone unnoticed for me, so my apologies!
I’m updating the post to point it to your comment.
Cheers!
Of course I mean this link, not the Printing-procedures one:
http://gnupdf.org/manuals/gnupdf-manual/gnupdf.html#Error-Reporting-procedures
Hoola Albert,
Actually… this is no longer 100% true…
Even if we keep on using pdf_status_t, there’s an on-going progress to change the API so that methods do not return a pdf_status_t; instead we’ll use a new data type pdf_error_t which is used as glib’s GError.
Check http://gnupdf.org/manuals/gnupdf-manual/gnupdf.html#Error-Printing-procedures
For example, if a method was defined like this:
pdf_status_t do_something (int a, int b);
The new pdf_error_t-based API will look as:
pdf_bool_t do_something (int a, int b, pdf_error_t **error);
The idea here is that method ‘do_something’ may or may not fail, and some users of the method may only be interested in that, so that’s why a pdf_bool_t is returned (PDF_TRUE if method went ok, PDF_FALSE otherwise). Then, if more fine-grained result of the operation is wanted, the caller can pass a reference to a pdf_error_t, which will get filled when the method fails. The pdf_error_t includes the pdf_status_t internally, you can get it with pdf_error_get_status(); as well as some human-readable-printf-able text explaining the error with more detail, and more things like in which module the error was originally created (imagine that you get an error in a pdf-fsys API but which was generated when operating internally with the text module).
This was announced in the mailing list not long ago:
http://lists.gnu.org/archive/html/pdf-devel/2011-02/msg00003.html
And some modules have already been ported (list, hash), while others are still not fully ported (text module, in another branch) or no ported at all (time, fsys..). I’m taking the challenge of doing this, along with some general API/code polishing in the base module.
Cheers!