[pdf-devel] Something is scaring me in the description of the library

[Cirilo Bernardo]

Under the section on Memory Management:

> -- Function: char* pdf_alloc (int SIZE)
>      Allocates heap memory.
>
>     *Parameters*
>
>          SIZE
>                The requested number of octects to allocate.
>
>                If there is not enough available memory to satisfy the
>                petition a fatal error is signaled killing the current
>                process. An error status is returned to the operating
>                system.

Why should a library terminate my process?  I would never use such a
library. I have spent many hours screaming at people who have given
me libraries like this - this is not Microsoft where we tell users to reboot
every time some minor problem occurs.  Knowing when and how to
handle exceptional circumstances is a large part of the art of
programming; sometimes this can be a very tedious job, but if you want
a reliable piece of software you have to do it.

The correct thing to do is somehow indicate via the return
value that something went wrong.  It is up to the calling process to
decide how to deal with this.  Where library functions call other functions
which return an invalid value, this effect must cascade up to the process
which originally called a library function.  The library functions must also
perform cleanup so that when the calling process is notified, it is as if
nothing happened - no mysteriously vanished memory or corrupted
data.  Even the PDF specification has similar instructions on dealing
with forward feature compatibility and corrupted data structures within
the PDF file.

- Cirilo