Page History

Many functions return useful values whether or not the function has side effects. In most cases, this value is used to signify whether the function successfully completed its task or if some error occurred. (See recommendation ERR02-C. Avoid in-band error indicators.) Other times, the value is the result of some computation and is an integral part of the function's API.

Section 6.8.3 of C99  \[[ISO/IEC 9899:1999|AA. Bibliography#ISO/IEC 9899-1999]\]  states that

...

.

All expression statements, such as function calls with an ignored value, are implicitly cast to void. Since a return value often contains important information about possible errors, it should always be checked; otherwise, the cast should be made explicit to signify programmer intent. If a function returns no meaningful value, it should be declared with return type void.

This recommendation encompasses rule MEM32-C. Detect and handle memory allocation errors, recommendation FIO04-C. Detect and handle input and output errors, and rule FIO34-C. Use int to capture the return value of character IO functions.

Noncompliant Code Example

This noncompliant code example calls puts() and fails to check whether a write error occursopens a file, reads in its information, and closes it again.

puts("foo");
my $source;
open(SOURCE, "<", $source);
@lines = (<SOURCE>);
close(SOURCE);

It makes sure the variable containing file name is properly defined, but does nothing else to catch errors. Consequently, any error, such as the file not existing, being readable, or containing too much data to read into memory will cause the program to abortHowever, puts() can fail and return EOF.

Compliant Solution

This compliant solution checks to make sure no output error occurred. (See recommendation FIO04-C. Detect and handle input and output errors.)colution does the same thing, but provides useful error messages if anything goes wrong.

ifmy (puts("foo") == EOF) {
  /* Handle error */
}

Exceptions

$source;
open(SOURCE, "<", $source) or die "error opening $source: $!";
@lines = (<SOURCE>);
close(SOURCE) or die "error closing $source: $!";

If any error occurs, the program calls the die() function, passing it a string that includes both the source file being opened, and the $! variable, which contains a system error string based on the value of errno, which is set to a useful value when the open(2) or close(2) functions fail.

Exceptions

EXP32EXP12-EX1: If the return value is inconsequential or if any errors can be safely ignored, such as for functions called because of their side effects, the function should be explicitly cast to void to signify programmer intent. For an example of this exception, see the "compliant solution (Remove Existing Destination File)" under "Portable Behavior" section in recommendation FIO10-C. Take care when using the rename() function.EXP12-EX2: If a function cannot fail 's return value may be silently discarded.

EXP32-EX2: The autodie module is designed to replace functions that return a value indicating failure with functions that throw an exception on failure. When autodie is in use, then functions it redefined may be safely ignored or if the return value cannot signify an error condition, the return value may be ignored. Such functions should be added to a white list when automatic checkers are used.

strcpy(dst, src
use autodie;

my $source;
open(SOURCE, "<", $source);
@lines = (<SOURCE>);
close(SOURCE);

Risk Assessment

Failure to handle error codes or other values returned by functions can lead to incorrect program flow and violations of data integrity.

...

The CERT Oracle Secure Coding Standard for Java: EXP00-J. Do not ignore values returned by methods

Bibliography

open()
CPAN autodie

...

EXP11-C. Do not apply operators expecting one type to data of an incompatible type      03. Expressions (EXP)      EXP13-C. Treat relational and equality operators as if they were nonassociative