Musings on the proper use of g_error and GError

[Philip Kovacs <kovacsp3 comcast net>]

The glib documentation on error reporting is very specific on 
differentiating
between runtime recoverable errors and programming errors:

http://developer.gnome.org/doc/API/2.0/glib/glib-Error-Reporting.html

Of interest to me is the rather strong statement that:

"... the |g_error()| 
<http://developer.gnome.org/doc/API/2.0/glib/glib-Message-Logging.html#g-error> 
function should /only/ be used for programming errors,
 it should not be used to print any error reportable via GError 
<http://developer.gnome.org/doc/API/2.0/glib/glib-Error-Reporting.html#GError>."

Looking at the glib code itself, e.g. in gmem.c:  in the g_malloc() 
function,
if the memory was not allocated as expected, glib does this:

g_error ("%s: failed to allocate %lu bytes", G_STRLOC, n_bytes);

Clearly this is not a "programming" error, it is a runtime error, so it 
leaves
me questioning the clarity of documentation.  Does the statement mean
that if you are using GError in the api and you get a runtime error, you
should favor setting a GError over using g_error, BUT, if you are not
using GError in the api, then it is ok to issue a g_error?

Also in that same paragraph of the documentation:

"These two kinds of errors are fundamentally different: runtime errors 
should be handled
or reported to the user, programming errors should be eliminated by 
fixing the bug in the
program. This is why most functions in GLib and GTK+ do not use the 
GError 
<http://developer.gnome.org/doc/API/2.0/glib/glib-Error-Reporting.html#GError> 
facility."

Can someone clarify the conclusion:

"This is why most functions in GLib and GTK+ do not use the GError 
<http://developer.gnome.org/doc/API/2.0/glib/glib-Error-Reporting.html#GError> 
facility."
That conclusion does not seem to follow naturally from the precending 
statement.

Phil