Page History

...

Function	Successful Return	Error Return
`aligned_alloc()`	Pointer to space	`NULL`
`asctime_s()`	`0`	Nonzero
`at_quick_exit()`	`0`	Nonzero
`atexit()`	`0`	Nonzero
`bsearch()`	Pointer to matching element	`NULL`
`bsearch_s()`	Pointer to matching element	`NULL`
`btowc()`	Converted wide character	`WEOF`
`c16rtomb()`	Number of bytes	`(size_t)(-1)`
`c32rtomb()`	Number of bytes	`(size_t)(-1)`
`calloc()`	Pointer to space	`NULL`
`clock()`	Processor time	`(clock_t)(-1)`
`cnd_broadcast()`	`thrd_success`	`thrd_error`
`cnd_init()`	`thrd_success`	`thrd_nomem or thrd_error`
`cnd_signal()`	`thrd_success`	`thrd_error`
`cnd_timedwait()`	`thrd_success`	`thrd_timedout or thrd_error`
`cnd_wait()`	`thrd_success`	`thrd_error`
`ctime_s()`	`0`	Nonzero
`fclose()`	`0`	`EOF` (negative)
`fflush()`	`0`	`EOF` (negative)
`fgetc()`	Character read	`EOF`¹
`fgetpos()`	`0`	Nonzero, `errno > 0`
`fgets()`	Pointer to string	`NULL`
`fgetwc()`	Wide character read	`WEOF`¹
`fopen()`	Pointer to stream	`NULL`
`fopen_s()`	`0`	Nonzero
`fprintf()`	Number of characters (nonnegative)	Negative
`fprintf_s()`	Number of characters (nonnegative)	Negative
`fputc()`	Character written	`EOF`²
`fputs()`	Nonnegative	`EOF` (negative)
`fputwc()`	Wide character written	`WEOF`
`fputws()`	Nonnegative	`EOF` (negative)
`fread()`	Elements read	Elements read
`freopen()`	Pointer to stream	`NULL`
`freopen_s()`	`0`	Nonzero
`fscanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`fscanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)
`fseek()`	`0`	Nonzero
`fsetpos()`	`0`	Nonzero, `errno > 0`
`ftell()`	File position	`−1L`, `errno > 0`
`fwprintf()`	Number of wide characters (nonnegative)	Negative
`fwprintf_s()`	Number of wide characters (nonnegative)	Negative
`fwrite()`	Elements written	Elements written
`fwscanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`fwscanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)
`getc()`	Character read	`EOF`¹
`getchar()`	Character read	`EOF`¹
`getenv()`	Pointer to string	`NULL`
`getenv_s()`	Pointer to string	`NULL`
`gets_s()`	Pointer to string	`NULL`
`getwc()`	Wide character read	`WEOF`
`getwchar()`	Wide character read	`WEOF`
`gmtime()`	Pointer to broken-down time	`NULL`
`gmtime_s()`	Pointer to broken-down time	`NULL`
`localtime()`	Pointer to broken-down time	`NULL`
`localtime_s()`	Pointer to broken-down time	`NULL`
`malloc()`	Pointer to space	`NULL`
`mblen(), s != NULL`	Number of bytes	`−1`
`mbrlen(), s != NULL`	Number of bytes or status	`(size_t)(-1)`
`mbrtoc16()`	Number of bytes or status	`(size_t)(-1), errno == EILSEQ`
`mbrtoc32()`	Number of bytes or status	`(size_t)(-1), errno == EILSEQ`
`mbrtowc(), s != NULL`	Number of bytes or status	`(size_t)(-1), errno == EILSEQ`
`mbsrtowcs()`	Number of non-null elements	`(size_t)(-1), errno == EILSEQ`
`mbsrtowcs_s()`	`0`	Nonzero
`mbstowcs()`	Number of non-null elements	`(size_t)(-1)`
`mbstowcs_s()`	`0`	Nonzero
`mbtowc(), s != NULL`	Number of bytes	`−1`
`memchr()`	Pointer to located character	`NULL`
`mktime()`	Calendar time	`(time_t)(-1)`
`mtx_init()`	`thrd_success`	`thrd_error`
`mtx_lock()`	`thrd_success`	`thrd_error`
`mtx_timedlock()`	`thrd_success`	`thrd_timedout or thrd_error`
`mtx_trylock()`	`thrd_success`	`thrd_busy or thrd_error`
`mtx_unlock()`	`thrd_success`	`thrd_error`
`printf_s()`	Number of characters (nonnegative)	Negative
`putc()`	Character written	`EOF`²
`putwc()`	Wide character written	`WEOF`
`raise()`	`0`	Nonzero
`realloc()`	Pointer to space	`NULL`
`remove()`	`0`	Nonzero
`rename()`	`0`	Nonzero
`setlocale()`	Pointer to string	`NULL`
`setvbuf()`	`0`	Nonzero
`scanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`scanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)
`signal()`	Pointer to previous function	`SIG_ERR, errno > 0`
`snprintf()`	Number of characters that would be written (nonnegative)	Negative
`snprintf_s()`	Number of characters that would be written (nonnegative)	Negative
`sprintf()`	Number of non-null characters written	Negative
`sprintf_s()`	Number of non-null characters written	Negative
`sscanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`sscanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)
`strchr()`	Pointer to located character	`NULL`
`strerror_s()`	`0`	Nonzero
`strftime()`	Number of non-null characters	`0`
`strpbrk()`	Pointer to located character	`NULL`
`strrchr()`	Pointer to located character	`NULL`
`strstr()`	Pointer to located string	`NULL`
`strtod()`	Converted value	`0, errno == ERANGE`
`strtof()`	Converted value	`0, errno == ERANGE`
`strtoimax()`	Converted value	`INTMAX_MAX or INTMAX_MIN, errno == ERANGE`
`strtok()`	Pointer to first character of a token	`NULL`
`strtok_s()`	Pointer to first character of a token	`NULL`
`strtol()`	Converted value	`LONG_MAX or LONG_MIN, errno == ERANGE`
`strtold()`	Converted value	`0, errno == ERANGE`
`strtoll()`	Converted value	`LLONG_MAX or LLONG_MIN, errno == ERANGE`
`strtoumax()`	Converted value	`UINTMAX_MAX, errno == ERANGE`
`strtoul()`	Converted value	`ULONG_MAX, errno == ERANGE`
`strtoull()`	Converted value	`ULLONG_MAX, errno == ERANGE`
`strxfrm()`	Length of transformed string	`>= n`
`swprintf()`	Number of non-null wide characters	Negative
`swprintf_s()`	Number of non-null wide characters	Negative
`swscanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`swscanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)
`thrd_create()`	`thrd_success`	`thrd_nomem or thrd_error`
`thrd_detach()`	`thrd_success`	`thrd_error`
`thrd_join()`	`thrd_success`	`thrd_error`
`thrd_sleep()`	`0`	`negative`
`time()`	Calendar time	`(time_t)(-1)`
`timespec_get()`	Base	`0`
`tmpfile()`	Pointer to stream	`NULL`
`tmpfile_s()`	`0`	Nonzero
`tmpnam()`	Non-null pointer	`NULL`
`tmpnam_s()`	`0`	Nonzero
`tss_create()`	`thrd_success`	`thrd_error`
`tss_get()`	Value of thread-specific storage	`0`
`tss_set()`	`thrd_success`	`thrd_error`
`ungetc()`	Character pushed back	`EOF (see below)`
`ungetwc()`	Character pushed back	`WEOF`
`vfprintf()`	Number of characters (nonnegative)	Negative
`vfprintf_s()`	Number of characters (nonnegative)	Negative
`vfscanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`vfscanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)
`vfwprintf()`	Number of wide characters (nonnegative)	Negative
`vfwprintf_s()`	Number of wide characters (nonnegative)	Negative
`vfwscanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`vfwscanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)
`vprintf_s()`	Number of characters (nonnegative)	Negative
`vscanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`vscanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)
`vsnprintf()`	Number of characters that would be written (nonnegative)	Negative
`vsnprintf_s()`	Number of characters that would be written (nonnegative)	Negative
`vsprintf()`	Number of non-null characters (nonnegative)	Negative
`vsprintf_s()`	Number of non-null characters (nonnegative)	Negative
`vsscanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`vsscanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)
`vswprintf()`	Number of non-null wide characters	Negative
`vswprintf_s()`	Number of non-null wide characters	Negative
`vswscanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`vswscanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)
`vwprintf_s()`	Number of wide characters (nonnegative)	Negative
`vwscanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`vwscanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)
`wcrtomb()`	Number of bytes stored	`(size_t)(-1)`
`wcschr()`	Pointer to located wide character	`NULL`
`wcsftime()`	Number of non-null wide characters	`0`
`wcspbrk()`	Pointer to located wide character	`NULL`
`wcsrchr()`	Pointer to located wide character	`NULL`
`wcsrtombs()`	Number of non-null bytes	`(size_t)(-1), errno == EILSEQ`
`wcsrtombs_s()`	`0`	Nonzero
`wcsstr()`	Pointer to located wide string	`NULL`
`wcstod()`	Converted value	`0, errno == ERANGE`
`wcstof()`	Converted value	`0, errno == ERANGE`
`wcstoimax()`	Converted value	`INTMAX_MAX or INTMAX_MIN, errno == ERANGE`
`wcstok()`	Pointer to first wide character of a token	`NULL`
`wcstok_s()`	Pointer to first wide character of a token	`NULL`
`wcstol()`	Converted value	`LONG_MAX or LONG_MIN, errno == ERANGE`
`wcstold()`	Converted value	`0, errno == ERANGE`
`wcstoll()`	Converted value	`LLONG_MAX or LLONG_MIN, errno == ERANGE`
`wcstombs()`	Number of non-null bytes	`(size_t)(-1)`
`wcstombs_s()`	`0`	Nonzero
`wcstoumax()`	Converted value	`UINTMAX_MAX, errno == ERANGE`
`wcstoul()`	Converted value	`ULONG_MAX, errno == ERANGE`
`wcstoull()`	Converted value	`ULLONG_MAX, errno == ERANGE`
`wcsxfrm()`	Length of transformed wide string	`>= n`
`wctob()`	Converted character	`EOF`
`wctomb(), s != NULL`	Number of bytes stored	`−1`
`wctomb_s(), s != NULL`	Number of bytes stored	`−1`
`wctrans()`	Valid argument to `towctrans`	`0`
`wctype()`	Valid argument to `iswctype`	`0`
`wmemchr()`	Pointer to located wide character	`NULL`
`wprintf_s()`	Number of wide characters (nonnegative)	Negative
`wscanf()`	Number of conversions (nonnegative)	`EOF` (negative)
`wscanf_s()`	Number of conversions (nonnegative)	`EOF` (negative)

...

Compliant Solution (`setlocale()`)

A compliant 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.

Code Block

bgColor	#ccccFF
lang	c

#include <locale.h>
#include <stdlib.h>
 
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 = (size_t)-1;
  }

  return n;
}

...

Noncompliant Code Example (`signal()`)

...

Code Block

bgColor	#FFcccc
lang	c

#include <signal.h>
 
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 This 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.

Code Block

bgColor	#ccccFF
lang	c

#include <signal.h>
 
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 == (int)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()`)

...

Code Block

bgColor	#ccccff
lang	c

#include <stdlib.h>
#include <string.h>
 
typedef struct {
  char sig_desc[32];
} signal_info;
 
void func(size_t num_of_records, size_t temp_num,
          const char *tmp2) {
  signal_info *point;
  signal_info *start = (signal_info *)malloc(num_of_records *
                                           sizeof(signal_info));
  if (start == NULL) {
    /* Handle allocation error */
  }
  point = start + temp_num - 1; 
  memcpy(point->sig_desc, tmp2, strlen(tmp2));
  /* ... */ 

}

Noncompliant Code Example (

...

`realloc()`)

In this 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 109 in Annex J of the C Standard.) In practice, an abnormal termination of the process typically occurs, providing 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.)

Code Block

bgColor	#FFcccc
lang	c

#include <stdlib.h>
#include <string.h>
 
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 is not possible, propagate the failure to the caller.

Code Block

bgColor	#ccccff
lang	c

#include <stdlib.h>
#include <string.h>
 
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;
}

Noncompliant Code Example (`realloc()`)

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

Code Block

bgColor	#FFcccc
lang	c

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

When using realloc(), it is important to account for 0-byte allocations. (See 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:validated before it is assigned to the original pointer p. This solution is also compliant with MEM04-C. Do not perform zero-length allocations.

Code Block

bgColor	#ccccff
lang	c

#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;
  }
}

...

According to the C Standard, the fseek() function returns a nonzero value to indicate that an error occurred. Testing for this condition before proceeding to read from the file eliminates the chance of operating on the wrong portion of the file if fseek() failed fails. Always test the returned value to make sure an error did not occur before operating on the file. If an error does occur, handle it appropriately.

...

When the length of the formatted string is unbounded, it is best to invoke the function twice, once with a NULL buffer to determine the size of output, then dynamically allocate a buffer of sufficient size, and finally call 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 still 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, allocate one of a sufficient size dynamically. This approach is shown in the following compliant solution:.

Note that 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.

Implementation Details

POSIX

In addition to the C standard library functions mentioned earlier, the following functions defined in POSIX require error checking (list is not all-inclusive)error when using and releasing resources.

Code Block

bgColor	#ccccff
lang	c

#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);
  }
}

Implementation Details

POSIX

In addition to the C standard library functions mentioned earlier, the following functions defined in POSIX require error checking (list is not all-inclusive).

Function	Successful Return	Error Return	`errno`
`fmemopen()`	Pointer to a `FILE` object	`NULL`	`ENOMEM`
`open_memstream()`	Pointer to a `FILE` object	`NULL`	`ENOMEM`
`posix_memalign()`	`0`	Nonzero	Unchanged

...

Code Block

bgColor	#ccccff
lang	c

#include <stdio.h>
#include <string.h>
 
int main(int argc, char *argv[]) {
  FILE *out;
  FILE *in;
  size_t size;
  char *ptr;
 
  if (argc != 2) {
    /* Handle error */
  }
 
  in = fmemopen(argv[1], strlen(argv[1]), "r");

  if (in == NULL){
    /* Handle error */
  }
  /* Use in */
 
  out = open_memstream(&ptr, &size);

  if (out == NULL){
    /* Handle error */
  }
  /* Use out */
  return 0;
}

Exceptions

EXP12ERR33-EX1EX0: The exception from EXP12-C. Do not ignore values returned by functions still applies. 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 "Compliant Solution (Remove Existing Destination File)" under "Portable Behavior" in FIO10-C. Take care when using the rename() function.

ERR33-EX1: Ignore the return value of a function that cannot fail or whose return value cannot signify that an error condition need not be diagnosed. For example, strcpy() is one such function.

...

[DHS 2006]	Handle All Errors Safely
[Henricson 1997]	Recommendation 12.1, "Check for All Errors Reported from Functions"
[ISO/IEC 9899:2011]	Subclause 7.21.7.10, "The `ungetc` Function"

...

Space shortcuts

Page tree

Versions Compared

Old Version 33

New Version 34

Key

Compliant Solution (`setlocale()`)

Noncompliant Code Example (`signal()`)

Compliant Solution (`signal()`)

Noncompliant Code Example (`malloc()`)

Noncompliant Code Example (

`realloc()`)

Compliant Solution (`malloc()`)

Noncompliant Code Example (`realloc()`)

Compliant Solution (`realloc()`)

Implementation Details

POSIX

Implementation Details

POSIX

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 33

New Version 34

Key

Compliant Solution (setlocale())

Noncompliant Code Example (signal())

Compliant Solution (signal())

Noncompliant Code Example (malloc())

Noncompliant Code Example (

realloc())

Compliant Solution (malloc())

Noncompliant Code Example (realloc())

Compliant Solution (realloc())

Implementation Details

POSIX

Implementation Details

POSIX

Compliant Solution (`setlocale()`)

Noncompliant Code Example (`signal()`)

Compliant Solution (`signal()`)

Noncompliant Code Example (`malloc()`)

`realloc()`)

Compliant Solution (`malloc()`)

Noncompliant Code Example (`realloc()`)

Compliant Solution (`realloc()`)