C Library Extension 1

[added with TR24731]

ISO/IEC TR24731 is a non-normative Technical Report titled Extensions to the C Library, Part 1: Bounds-checking interfaces. It adds a number of functions that check arguments for unexpected null pointers, short buffers, and other common errors. The functions are based on additions made by Microsoft to Visual C++ 2005 (V8). The additions all occur within existing headers.

__STDC_LIB_EXT1__ · __STDC_WANT_LIB_EXT1__

errno.h: errno_t

stddef.h: rsize_t

stdint.h: RSIZE_MAX

stdio.h: L_tmpnam_s · TMP_MAX_S · errno_t · gets_s · fopen_s · fprintf_s · freopen_s · fscanf_s · printf_s · rsize_t · scanf_s · snprintf_s · sprintf_s · sscanf_s · tmpfile_s · tmpnam_s · vfprintf_s · vfscanf_s · vprintf_s · vscanf_s · vsnprintf_s · vsprintf_s · vsscanf_s

stdlib.h: abort_handler_s · bsearch_s · constraint_handler_t · errno_t · getenv_s · ignore_handler_s · mbstowcs_s · qsort_s · rsize_t · set_constraint_handler_s · wcstombs_s · wctomb_s

string.h: errno_t · memcpy_s · memmove_s · rsize_t · strcat_s · strcpy_s · strerror_s · strerrorlen_s · strncat_s · strncpy_s · strnlen_s · strtok_s

time.h: asctime_s · ctime_s · errno_t · gmtime_s · localtime_s · rsize_t

wchar.h: errno_t · fwprintf_s · fwscanf_s · mbsrtowcs_s · rsize_t · snwprintf_s · swprintf_s · swscanf_s · vfwprintf_s · vfwscanf_s · vsnwprintf_s · vswprintf_s · vswscanf_s · vwprintf_s · vwscanf_s · wcrtomb_s · wcscat_s · wcscpy_s · wcsncat_s · wcsncpy_s · wcsnlen_s · wcsrtombs_s · wcstok_s · wmemcpy_s · wmemmove_s · wprintf_s · wscanf_s

Overview

The macro __STDC_LIB_EXT1__ is defined as 200509L to indicate the presence of C Library Extension 1. If you define the macro __STDC_WANT_LIB_EXT1__ as zero before you include any of the headers that contain C Library Extension 1 additions, then none of these additions will be visible to the program. Otherwise, in this implementation, the library defines this macro as 1 and includes all the additions.

C Library Extension 1 introduces the concept of a runtime constraint violation, which is a condition detected and reported at runtime. Examples include calling a function with an unexpected null pointer argument or with a buffer length argument that is too small or too large. The description of each library function describes any runtime constraints added with TR24731 that it enforces. (Note that some existing library functions have such added runtime constraints.)

A library function reports a runtime constraint violation by calling a constraint handler, of type constraint_handler_t, with three arguments:

const char *mesg -- a null-terminated error message
void *p -- a pointer, either null or to an implementation-defined object
errno_t errcode -- an error code suitable for assigning to errno

In this implementation, the library always calls the constraint handler with p a null pointer. If the constraint handler returns, the library returns to the function that reported the runtime constraint violation. The default constraint handler writes mesg to the standard error stream and returns.

You can alter the constraint handler that gets called by calling set_constraint_handler_s. For convenience, the library supplies two functions that you can use as constraint handlers:

abort_handler_s, which writes mesg to the standard error stream and aborts
ignore_handler_s, which simply returns

You can also supply your own constraint handler.

Two useful synonyms for other types are:

typedef int errno_t, for representing error codes
typedef size_t rsize_t, for representing object sizes that should never be greater than the value of the macro RSIZE_MAX

An implementation typically defines RSIZE_MAX as the size in bytes of the largest object that you can declare or allocate dynamically. Note that:

if RSIZE_MAX <= (size_t)(-1) / 2 and sizeof (int) <= sizeof (size_t) then a negative int value converted to rsize_t will cause a runtime constraint violation instead of being treated as a ridiculously large unsigned value
if RSIZE_MAX == SIZE_MAX no runtime constraint violation can occur for any value of type rsize_t

See also the Table of Contents and the Index.