Page History

Many functions will either return The majority of the standard library functions, including I/O functions and memory allocation functions, return either a valid value or a value of the correct return type that indicates an error (for example, -1 −1 or a null pointer). Assuming that all calls to such functions will succeed and failing to check the return value for an indication of an error is a dangerous practice that may lead to unexpected or undefined behavior when an error occurs. Therefore, it It is essential that programs detect and appropriately handle all errors in accordance with an error handling policy as discussed in ERR00-C. Adopt and implement a consistent and comprehensive error-handling policy. Anchornce_setlocalence_setlocale

Noncompliant Code Example (setlocale())

In the noncompliant example below, the function utf8_to_ucs() attempts to convert a sequence of UTF-8 characters to UCS. It first invokes setlocale() to set the global locale to "en_US.UTF-8" but it fails to check for failure. setlocale() will fail by returning a null pointer, for example when the locale is not installed (the function may fail for other reasons as well, such as the lack of resources). Depending on the sequence of characters pointed to by utf8 the subsequent call to mbstowcs() may fail or result in the function storing an unexpected sequence of wide characters in the supplied buffer ucs.

size_t utf8_to_ucs(wchar_t *ucs, size_t n, const char *utf8) {
  setlocale(LC_CTYPE, "en_US.UTF-8");
  return mbstowcs(ucs, utf8, n);
}

...

The successful completion or failure of each of the standard library functions listed in the following table shall be determined either by comparing the function’s return value with the value listed in the column labeled “Error Return” or by calling one of the library functions mentioned in the footnotes.

Standard Library Functions

Note: According to FIO35-C. Use feof() and ferror() to detect end-of-file and file errors when sizeof(int) == sizeof(char), callers should verify end-of-file and file errors for the functions in this table as follows:

¹ By calling ferror() and feof()
² By calling ferror()

The ungetc() function does not set the error indicator even when it fails, so it is not possible to check for errors reliably unless it is known that the argument is not equal to EOF.

The C Standard 7.31.3.10 paragraph 3 [ISO/IEC 9899:2024] states that

 )ne wide character of pushback is guaranteed...

so this should not be an issue if, at most, one character is ever pushed back before reading again. (See FIO13-C. Never push back anything other than one read character.)

Noncompliant Code Example (setlocale())

In this noncompliant code example, the function utf8_to_wcs() attempts to convert a sequence of UTF-8 characters to wide characters. It first invokes setlocale() to set the global locale to the implementation-defined en_US.UTF-8 but does not check for failure. The setlocale() function will fail by returning a null pointer, for example, when the locale is not installed. The function may fail for other reasons as well, such as the lack of resources.  Depending on the sequence of characters pointed to by utf8, the subsequent call to mbstowcs() may fail or result in the function storing an unexpected sequence of wide characters in the supplied buffer wcs.

#include <locale.h>
#include <stdlib.h>
 
int utf8_to_wcs(wchar_t *wcs, size_t n, const char *utf8,
                size_t *size) {
  if (NULL == size) {
    return -1;
  }
  setlocale(LC_CTYPE, "en_US.UTF-8");
  *size = mbstowcs(wcs, utf8, n);
  return 0;
}

Compliant Solution (setlocale())

This compliant solution checks the value returned by setlocale() and avoids calling mbstowcs() if the function fails. The function also takes care to restore the locale to its initial setting before returning control to the caller.

#include <locale.h>
#include <stdlib.h>
 
int utf8_to_wcs(wchar_t *wcs, size_t n, const char *utf8,
                size_t *size) {
  if (NULL == size) {
    return -1;
  }
  const char *save = setlocale(LC_CTYPE, "en_US.UTF-8");
  if (NULL == save) {
    return -1;
  }

  *size = mbstowcs(wcs, utf8, n);
  if (NULL == setlocale(LC_CTYPE, save)) {
    return -1;
  }
  return 0;
}

Noncompliant Code Example (calloc())

In this noncompliant code example, temp_num, tmp2, and num_of_records are derived from a tainted source. Consequently, an attacker can easily cause calloc() to fail by providing a large value for num_of_records. 

#include <stdlib.h>
#include <string.h>
 
enum { SIG_DESC_SIZE = 32 };

typedef struct {
  char sig_desc[SIG_DESC_SIZE];
} signal_info;
 
void func(size_t num_of_records, size_t temp_num,
          const char *tmp2, size_t tmp2_size_bytes) {
  signal_info *start = (signal_info *)calloc(num_of_records,
                                          sizeof(signal_info));

  if (tmp2 == NULL) {
    /* Handle error */
  } else if (temp_num > num_of_records || temp_num == 0) {
    /* Handle error */
  } else if (tmp2_size_bytes < SIG_DESC_SIZE) {
    /* Handle error */
  }

  signal_info *point = start + temp_num - 1;
  memcpy(point->sig_desc, tmp2, SIG_DESC_SIZE);
  point->sig_desc[SIG_DESC_SIZE - 1] = '\0';
  /* ... */
  free(start);
}

When calloc() fails, it returns a null pointer that is assigned to start. If start is null, an attacker can provide a value for temp_num that, when scaled by sizeof(signal_info), references a writable address to which control is eventually transferred. The contents of the string referenced by tmp2 can then be used to overwrite the address, resulting in an arbitrary code execution vulnerability.

Compliant Solution (calloc())

To correct this error, ensure the pointer returned by calloc() is not null:

#include <stdlib.h>
#include <string.h>

enum { SIG_DESC_SIZE = 32 };

typedef struct {
  char sig_desc[SIG_DESC_SIZE];
} signal_info;
 
void func(size_t num_of_records, size_t temp_num,
          const char *tmp2, size_t tmp2_size_bytes) {
  signal_info *start = (signal_info *)calloc(num_of_records,
                                           sizeof(signal_info));
  if (start == NULL) {
    /* Handle allocation error */
  } else if (tmp2 == NULL) {
    /* Handle error */
  } else if (temp_num > num_of_records || temp_num == 0) {
    /* Handle error */
  } else if (tmp2_size_bytes < SIG_DESC_SIZE) {
    /* Handle error */
  }

  signal_info *point = start + temp_num - 1; 
  memcpy(point->sig_desc, tmp2, SIG_DESC_SIZE);
  point->sig_desc[SIG_DESC_SIZE - 1] = '\0';
  /* ... */
  free(start);
}

Noncompliant Code Example (realloc())

This noncompliant code example calls realloc() to resize the memory referred to by p. However, if realloc() fails, it returns a null pointer and the connection between the original block of memory and p is lost, resulting in a memory leak.

#include <stdlib.h>
 
void *p;
void func(size_t new_size) {
  if (new_size == 0) {
    /* Handle error */
  }
  p = realloc(p, new_size);
  if (p == NULL) {
   /* Handle error */
  }
}

This code example complies with MEM04-C. Do not perform zero-length allocations.

Compliant Solution (realloc())

In this compliant solution, the result of realloc() is assigned to the temporary pointer q and validated before it is assigned to the original pointer p:

#include <stdlib.h>
 
void *p;
void func(size_t new_size) {
  void *q;

  if (new_size == 0) {
    /* Handle error */
  }
 
  q = realloc(p, new_size);
  if (q == NULL) {
   /* Handle error */
  } else {
    p = q;
  }
}

Noncompliant Code Example (fseek())

In this noncompliant code example, the fseek() function is used to set the file position to a location offset in the file referred to by file prior to reading a sequence of bytes from the file. However, if an I/O error occurs during the seek operation, the subsequent read will fill the buffer with the wrong contents.

#include <stdio.h>
 
size_t read_at(FILE *file, long offset,
               void *buf, size_t nbytes) {
  fseek(file, offset, SEEK_SET);
  return fread(buf, 1, nbytes, file);
}

Compliant Solution (fseek())

According to the C Standard, the fseek() function returns a nonzero value to indicate that an error occurred. This compliant solution tests for this condition before reading from a file to eliminate the chance of operating on the wrong portion of the file if fseek() fails:

#include <stdio.h>
 
size_t read_at(FILE *file, long offset,
               void *buf, size_t nbytes) {
  if (fseek(file, offset, SEEK_SET) != 0) {
    /* Indicate error to caller */
    return 0;
  }
  return fread(buf, 1, nbytes, file);
}

Noncompliant Code Example (snprintf())

In this noncompliant code example, snprintf() is assumed to succeed. However, if the call fails (for example, because of insufficient memory, as described in GNU libc bug 441945), the subsequent call to log_message() has undefined behavior because the character buffer is uninitialized and need not be null-terminated.

#include <stdio.h>
 
extern void log_message(const char *);

void f(int i, int width, int prec) {
  char buf[40];
  snprintf(buf, sizeof(buf), "i = %*.*i", width, prec, i);
  log_message(buf);
  /* ... */
}

Compliant Solution (snprintf())

This compliant solution does not assume that snprintf() will succeed regardless of its arguments. It tests the return value of snprintf() before subsequently using the formatted buffer. This compliant solution also treats the case where the static buffer is not large enough for snprintf() to append the terminating null character as an error.

#include <stdio.h>
#include <string.h>
 
extern void log_message(const char *);

void f(int i, int width, int prec) {
  char buf[40];
  int n;
  n = snprintf(buf, sizeof(buf), "i = %*.*i", width, prec, i);
  if (n < 0 || n >= sizeof(buf)) {
    /* Handle snprintf() error */
    strcpy(buf, "unknown error");
  }
  log_message(buf);
}

Compliant Solution (snprintf(null))

If unknown, the length of the formatted string can be discovered by invoking snprintf() with a null buffer pointer to determine the size required for the output, then dynamically allocating a buffer of sufficient size, and finally calling snprintf() again to format the output into the dynamically allocated buffer. Even with this approach, the success of all calls still needs to be tested, and any errors must be appropriately handled. A possible optimization is to first attempt to format the string into a reasonably small buffer allocated on the stack and, only when the buffer turns out to be too small, dynamically allocate one of a sufficient size:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
 
extern void log_message(const char *); 
 
void f(int i, int width, int prec) {
  char buffer[20];
  char *buf = buffer;
  int n  = sizeof(buffer);
  const char fmt[] = "i = %*.*i";

  n = snprintf(buf, n, fmt, width, prec, i);
  if (n < 0) {
    /* Handle snprintf() error */
    strcpy(buffer, "unknown error");
    goto write_log;
  }

  if (n < sizeof(buffer)) {
    goto write_log;
  }

  buf = (char *)malloc(n + 1);
  if (NULL == buf) {
    /* Handle malloc() error */
    strcpy(buffer, "unknown error");
    goto write_log;
  }

  n = snprintf(buf, n, fmt, width, prec, i);
  if (n < 0) {
    /* Handle snprintf() error */
    strcpy(buffer, "unknown error");
  }

write_log:
  log_message(buf);

  if (buf != buffer) {
    free(buf);
  }
}

This solution uses the goto statement, as suggested in MEM12-C. Consider using a goto chain when leaving a function on error when using and releasing resources.

Exceptions

ERR33-C-EX1: It is acceptable to ignore the return value of a function if:

• that function cannot fail.
• its return value is inconsequential; that is, it does not indicate an error.
• it is one of a handful of functions whose return values are not traditionally checked.

These functions are listed in the following table:

Functions for which Return Values Need Not Be Checked

The return value of a call to fprintf() or one of its variants (vfprintf(), wfprintf(), vwfprintf()) or one of the file output functions fputc(), fputwc(), fputs(), fputws() may be ignored if the output is being directed to stdout or stderr . Otherwise, the return value must be checked.

If a function's return value is to be ignored, it is recommended that the function's return value should be explicitly cast to void to signify the programmer's intent:

int main() {
  (void) fprintf(stdout, "Hello, world\n"); // fprintf() return value safely ignored
}

Risk Assessment

Failing to detect error conditions can lead to unpredictable results, including abnormal program termination and denial-of-service attacks or, in some situations, could even allow an attacker to run arbitrary code.

Automated Detection

Related Vulnerabilities

The vulnerability in Adobe Flash [VU#159523] arises because Flash neglects to check the return value from calloc(). Even when calloc() returns a null pointer, Flash writes to an offset from the return value. Dereferencing a null pointer usually results in a program crash, but dereferencing an offset from a null pointer allows an exploit to succeed without crashing the program.

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

Related Guidelines

Key here (explains table format and definitions)

CERT-CWE Mapping Notes

Key here for mapping notes

CWE-252/CWE-253/CWE-391 and ERR33-C/POS34-C

Independent( ERR33-C, POS54-C, FLP32-C, ERR34-C) Intersection( CWE-252, CWE-253) = Ø CWE-391 = Union( CWE-252, CWE-253) CWE-391 = Union( ERR33-C, POS34-C, list) where list =

• Ignoring return values of functions outside the C or POSIX standard libraries

Bibliography

...

Image Added Image Added Image Added

...

Compliant Solution Example (setlocale())

A compliant solution checks the value returned by setlocale() and avoids calling mbstowcs() if the function fails. The function also takes care to restore the locale to its initial setting before returning control to the caller.

size_t utf8_to_ucs(wchar_t *ucs, size_t n, const char *utf8) {
  const char *save;
  save = setlocale(LC_CTYPE, "en_US.UTF-8");
  if (NULL == save) {
    /* Propagate error to caller */
    return (size_t)-1;
  }

  n = mbstowcs(ucs, utf8, n);
  if (NULL == setlocale(LC_CTYPE, save))
    n = -1;

  return n;
}

...

Noncompliant Code Example (signal())

In the noncompliant example below the function signal() is invoked to install a handler for the SIGINT signal. signal() returns a pointer to the previously installed handler on success and the value SIG_ERR on failure. However, since the caller fails to check for errors, when signal() fails the function may proceed with the lengthy computation without the ability to interrupt it.

volatile sig_atomic_t interrupted;

void handle_interrupt(int signo) {
  interrupted = 1;
}

int f() {
  int result = 0;

  signal(SIGINT, handle_interrupt);

  while (0 == result && 0 == interrupted) {
    /* Perform a lengthy computation */
  }

  /* Indicate success or failure */
  return interrupted ? -1 : result;
}

...

Compliant Solution (signal())

A compliant solution checks the value returned by the signal() function and avoids performing the lengthy computation when signal() fails. The calling function also takes care to restore the disposition for the SIGINT signal to its initial setting before returning control to the caller.

volatile sig_atomic_t interrupted;

void handle_interrupt(int signo) {
  interrupted = 1;
}

int f() {
  int result = 0;
  void (*saved_handler)(int);
  saved_handler = signal(SIGINT, handle_interrupt);

  if (SIG_ERR == saved_handler) {
    /* Indicate failure */
    return -1;
  }

  while (0 == result && 0 == interrupted) {
    /* Perform a lengthy computation */
  }

  if (SIG_ERR == signal(SIGINT, saved_handler))
    return -1;

  /* Indicate success or failure */
  return interrupted ? -1 : result;
}

...

Noncompliant Code Example (malloc())

In this noncompliant code example, input_string is copied into dynamically allocated memory referenced by str. However, the result of malloc() is not checked before str is referenced. Consequently, if malloc() fails, the program has undefined behavior (see undefined behavior 103 in Annex J). In practice, this typically leads to an abnormal termination of the process, thusproviding an opportunity for a denial-of-service attack. In some cases it may be the source of other vulnerabilities as well (see the #Related Vulnerabilities section).

See also MEM32-C. Detect and handle memory allocation errors.

void f(char *input_string) {
  size_t size = strlen(input_string) + 1;
  char *str = (char *)malloc(size);
  strcpy(str, input_string);
  /* ... */
}

...

Compliant Solution (malloc())

The malloc() function as well as the other memory allocation functions, returns either a null pointer or a pointer to the allocated space. Always test the returned pointer to ensure it is not NULL before referencing the pointer. Handle the error condition appropriately when the returned pointer is NULL. When recovery from the allocation failure isn't possible, propagate the failure to the caller.

int f(char *input_string) {
  size_t size = strlen(input_string) + 1;
  char *str = (char *)malloc(size);
  if (str == NULL) {
    /* Handle allocation failure and return error status */
    return -1;
  }
  strcpy(str, input_string);
  /* ... */
  free(str);
  return 0;
}

Risk Assessment

Failing to detect error conditions can lead to unpredictable results, including abnormal program termination and denial-of-service attacks or, in some situations, could even allow an attacker to run arbitrary code.

Related Coding Practices

Other Languages

This rule appears in the C++ Secure Coding Standard as ERR10-CPP. Check for error conditions.

References

\[[CWE|AA. References#CWE]\] [CWE-252|http://cwe.mitre.org/data/definitions/252.html]: Unchecked Return Value
\[[CWE|AA. References#CWE]\] [CWE-253|http://cwe.mitre.org/data/definitions/253.html]: Incorrect Check of Function Return Value
\[[CWE|AA. References#CWE]\] [CWE-390|http://cwe.mitre.org/data/definitions/390.html]: Detection of Error Condition Without Action
\[[CWE|AA. References#CWE]\] [CWE-391|http://cwe.mitre.org/data/definitions/391.html]: Unchecked Error Condition
\[[Henricson 97|AA. References#Henricson 97]\] Recommendation 12.1 Check for all errors reported from functions

Image Removed      12. Error Handling (ERR)      13. Application Programming Interfaces (API)