Return values are discussed method by method, but some general practices are worth mentioning. For methods that return an integer, Libmarpa usually reserves -1 for special purposes, such as indicating loop termination in an iterator. In Libmarpa, methods usually indicate failure by returning -2. Any result greater than -2 usually indicates success.
If a method returns an pointer value,
NULL usually indicates failure.
Any other result usually indicates success.
On failure, a Libmarpa method always sets the error code. On success, a Libmarpa method may take one of three actions:
Which of the three actions the method takes on success should be regarded as unspecified, unless stated in the description of the method in this document. If a method sets an informational error code on success, that will always be stated in its description, and the description will specify, for each informational error code, the specific error code value, the circumstances under which it is set, and what return values will accompany it.
Informational error codes are set because some applications may find them convenient. Typically, informational error codes are redundant information, which may be ignored.
A method can have many reasons for failing, and many of the reasons for failure are common to large number of methods. Full descriptions of the error codes that are returned by the external methods are given in their own section. See External error codes.