Page History

When developing new code, declare functions that return errno with a return type of errno_t.  Many existing functions that return an errno error code are declared as returning a value of type int. It is semantically unclear by looking at inspecting the function declaration or prototype if these functions return an error status or a value ( or, worse, some combination of the two).. (See ERR02-C. Avoid in-band error indicators.)

C11 Annex K  introduced TR 24731-1 introduces the new type errno_t that is defined to be type int in <errnoerrno.h>h and elsewhere. Many of the functions defined in TR 24731-1 C11 Annex K return values of this type. As a matter of programming style, The errno_t type should be used as the type of something an object that deals may contain only with the values that might be found in errno. For example, a function that returns the value of errno should be declared as having the return type errno_t.

This recommendation depends on TR 24731-1 and advocates using errno_t in new code where appropriate.

Non-Compliant Code Example

C11 Annex K being implemented. The following code can be added to remove this dependency:

#ifndef __STDC_LIB_EXT1__
  typedef int errno_t;
#endif

This noncompliant code example shows This non-compliant code example illustrates a function called opener() that returns errno error codes.   However, the function is declared as returning an int.   Consequently, the meaning of the return value is not as clear as it could bereadily apparent.

#include <errno.h>
#include <stdio.h>
 
enum { NO_FILE_POS_VALUES = 3 };

int opener(
  FILE * file,
 int size_t *width,
 int size_t *height,
 int size_t *data_offset
) {
  intsize_t file_w;
  intsize_t file_h;
  intsize_t file_o;
  fpos_t offset;

  if (file == NULL) { return EINVAL; }
  errno = 0;
  if (fgetpos(file, &offset) != 0) { return errno; }
  if (fscanf(file, "%i%zu %i%zu %i%zu", &file_w, &file_h, &file_o)
        != NO_FILE_POS_VALUES) {
    return EIO-1;
  }

  errno = 0;
  if (fsetpos(file, &offset) != 0) { return errno; }

  if (width != NULL) { *width = file_w; }
  if (height != NULL) { *height = file_h; }
  if (data_offset != NULL) { *data_offset = file_o; }

  return 0;
}

This noncompliant code example nevertheless complies with ERR30-C. Take care when reading errno.

Compliant Solution (POSIX)

In this compliant solution, the opener() function returns a value of type errno_t, providing a clear indication that this function returns an error code.:

#define __STDC_WANT_LIB_EXT1__ 1
 
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
    
enum { NO_FILE_POS_VALUES = 3 };

errno_t opener(
  FILE * file,
 int size_t *width,
 int size_t *height,
  intsize_t *data_offset
) {
  intsize_t file_w;
  intsize_t file_h;
  intsize_t file_o;
  int rc;
  fpos_t offset;

  if (fileNULL == NULLfile) { return EINVAL; }
  errno = 0;
  if (fgetpos(file, &offset) != 0 ) { return errno; }
  if (fscanf(file, "%i%zu %i%zu %i%zu", &file_w, &file_h, &file_o)
        != NO_FILE_POS_VALUES) {
    return EIO;
  }

  errno = 0;
  if (fsetpos(file, &offset) != 0 ) { return errno; }

  if (width != NULL) { *width = file_w; }
  if (height != NULL) { *height = file_h; }
  if (data_offset != NULL) { *data_offset = file_o; }

  return 0;
}

NOTE: This compliant solution is categorized as a POSIX solution because it returns EINVAL and EIO , which are not defined in C99, but they are available in most implementations and are defined in POSIXdefined by POSIX (IEEE Std 1003.1, 2013 Edition) but not by the C Standard.

Risk Assessment

Failing to test for error conditions can lead to vulnerabilities of varying severity. Declaring functions that return an errno with a return type of errno_t will not eliminate this problem , but may reduce errors caused by programmers' misunderstanding the purpose of a return value.

Automated Detection

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

References

...

Related Guidelines

...

Bibliography

...

Image Added Image Added Image Added TR 24731-1-2007|AA. C References#ISO/IEC TR 24731-1-2007]\] \[[ISO/IEC 9899-1999|AA. C References#ISO/IEC 9899-1999]\] Section 6.7.5.3, "Function declarators (including prototypes)" \[[MISRA 04|AA. C References#MISRA 04]\] Rule 20.5 \[[Open Group 04|AA. C References#Open Group 04]\]DCL08-A. Properly encode relationships in constant definitions      02. Declarations and Initialization (DCL)       DCL10-A. Maintain the contract between the writer and caller of variadic functions