vitalnix user management suite 3.2.0


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.

  1. functions returning success or error (a "boolean" value)
  2. functions returning success or an error code
  3. functions returning an integral value or an error code
  4. 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.