Name
AEE - Alternate Error Encoding
Description
Functions from the Vitalnix API work a little different than the usual libc library calls when it comes to error reporting. The following document will describe the Alternate Error Encoding, which other manpages refer to.
Different classes of functions have different possible return values.
- functions returning success or error (a "boolean" value)
- functions returning success or an error code
- functions returning an integral value or an error code
- functions returning a pointer or an error code
Class A -- returning boolean
This class of functions returns non-zero for success and zero
for failure. An if()
construct can therefore be short:
if(!bool_function())
printf("Total failure\n");
This AEE draft does not specify if and how errno
is set in case of a false -- this is specific to a function.
Class B -- success or error code
negative, non-zero
In case of an error, the errno
-style error code
is returned as a negative number, e.g. -ENOMEM
. This differs from
the usual libc approach to set errno
and return -1
instead, but goes with how the Linux kernel does it.
Additional error codes may be returned as long as they are
negative. libvxmdfmt is an example, which has extra error codes in the
-1500
range (PWLFMT_E*
), outside the usual errno code
range.
Applications must not assume that errno
is set if
an error occurs. Library functions may diverge from this behavior to provide
additional error info, as e.g. libvxmdfmt which, if returning an error
code from its PWLFMT_E*
range, has the underlying system error
code (e.g. ENOENT
) in errno
(which can/should be
used).
zero
In case of Class B functions, this value is generally unused, but counts as an error. A precise test for error therefore looks like:
int ret;
if((ret = function()) <= 0)
fprintf(stderr, "function() returned %s (%d)\n", strerror(-ret), ret);
positive non-zero
Any positive non-zero value indicates success.
Class C -- integral value or error code
negative non-zero
For negative non-zero return values, the same rules as for Class B apply.
zero or positive non-zero
Zero or positive non-zero indicates the result of the function. For example, asking libvxdb how many groups there are can legitimately return zero:
long ret;
if((ret = vxdb_modctl(my_db, VXDB_COUNT_GROUPS)) >= 0)
printf("Number of groups: %ld\n", ret);
else
printf("vxdb_modctl() returned error %d: %s\n", ret, strerror(-ret));
Class D -- pointer or error code
Since any return value is used for the pointer, the only way
to notify of errors it to set errno
. Therefore, if a functions
returns an invalid pointer (most likely NULL
), errno
will be set.