[Home]

Issue of the Standard # S0663

Brief

The relationship between the return value and the set error is unclear in the description of gdk_pixbuf_loader_close

Detailed Description

The complete description of gdk_pixbuf_loader_close:
Informs a pixbuf loader that no further writes with gdk_pixbuf_loader_write() will occur, so that it can free its internal loading structures. Also, tries to parse any data that hasn't yet been parsed; if the remaining data is partial or corrupt, an error will be returned. If FALSE is returned, error will be set to an error from the GDK_PIXBUF_ERROR or G_FILE_ERROR domains. If you're just cancelling a load rather than expecting it to be finished, passing NULL for error to ignore it is reasonable.

loader : A pixbuf loader.
error : return location for a GError, or NULL to ignore errors
Returns : TRUE if all image data written so far was successfully passed out via the update_area signal

Most of the glib functions (and the functions that use glib functions) that return some value and specify errors as GError objects follow the convention that the return value indicates whether some error has occured. For example, if a function returns gboolean and may set an error, the error is expected to be set if and only if FALSE is returned. gdk_pixbuf_loader_write is one of this kind of functions.

However it is possible for gdk_pixbuf_loader_close to return TRUE and set an error at the same time. This is the case, for instance, when all the data passed to the loader are valid but not enough to form the image.

The documentation uses the following expressions:
"error will be returned"
"FALSE is returned"
"error will be set"
that may lead to confusion. This makes the fact that the return value and the set error are not tied to each even less obvious.

Problem location(s) in the standard

Gdk-pixbuf 2.6.2 API Reference, GdkPixbufLoader

Possible consequences

The convention described above is used in some parts of GdkPixbuf library itself. The value returned by gdk_pixbuf_loader_close() (rather then the error it may set) is sometimes used there to determine whether the data passed to the loader are complete. This causes problems in the implementation of the library.

For example, gdk_pixbuf_new_from_file() may return an image created from incomplete data. The error will be set though by gdk_pixbuf_loader_close().

[Home]