Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

set_constraint_handler_s(3C)

Name

runtime_constraint_handler, abort_handler_s, ignore_handler_s, set_constraint_handler_s - Runtime-constraint handler functions for the bound checking interfaces

Synopsis

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
void abort_handler_s(const char *msg, void *ptr, errno_t error)
void ignore_handler_s(const char *msg, void *ptr, errno_t error)
constraint_handler_t set_constraint_handler_s(constraint_handler_t handler)

Description

The runtime-constraint handler APIs are part of the C11 bounds checking interfaces specified in the C11 standard, Annex K. They can be used by the application to manage the actions taken when a library function defined to check for runtime-constraints detects a runtime-constraint violation. When such a function detects a runtime-constraint violation, the currently registered runtime-constraint handler, set using the set_constraint_handler_s() function, will be called. See INCITS/ISO/IEC 9899:2011.

The standard allows for implementation specific features of the abort_handler() and the set_constraint_handler_s() functions. The abort_handler_s() function writes a message on the standard error as follows:

(void) fputs(msg, stderr);
(void) fputc('\n', stderr);

When the handler set by the set_constraint_handler_s() function is called, it is passed a number of arguments in a defined order. Of these, two of the arguments are implementation defined as follows:

The second argument is a pointer to an object defined as:

typedef struct __rcviolation_info {
 const char      *__function_name; /* function detected violation */
 int             __error_raw;    /* _RCVIOLATION_* or errno */
 int             __error;        /* canonical errno */
 long            __pad[8];
} __rcviolation_info_t;

The fourth argument is the default constraint handler used if no calls have been made to the set_constraint_handler_s() function. In this case, the ignore_handler_s() function is the default constraint handler used.

Return Values

abort_handler_s()

No return value

ignore_handler_s()

No return value

set_constraint_handler_s()

Returns a pointer to the previously registered handler

Examples

Example 1 Calling the Runtime-Constraint Handler

The following example calls the runtime-constraint handler, set by the set_constraint_handler_s() function when a NULL pointer is passed as an argument to tmpfile_s() function.

#include <stdio.h>
#include <stdlib.h>

static errno_t  err;

void
handler(const char *msg, void *ptr, errno_t err)
{
        printf("%s and the function exited with error number: %d\n", msg, err);
}

int
main(int argc, char *argv[])
{
        FILE            *fptr;

        set_constraint_handler_s(handler);
        if ((err = tmpfile_s(&fptr)) == 0)
                printf("tmpfile_s is ok\n");
        else
                printf("tmpfile_s is a failure  %d\n", err);
        err = tmpfile_s(NULL);
}

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Unsafe

None of these functions can be safely used in a multi-threaded program.

See Also

asctime_s(3C), bsearch_s(3C), ctime_s(3C), fopen_s(3C), fprintf_s(3C), freopen_s(3C), fscanf_s(3C), fwscanf_s(3C), fwprintf(3C), getenv_s(3C), gets_s(3C), gmtime_s(3C), localtime_s(3C), mbsrtowcs_s(3C), mbstowcs_s(3C), memcpy_s(3C), memmove_s(3C), memset_s(3C), printf_s(3C), qsort_s(3C), scanf_s(3C), snprintf_s(3C), sprintf_s(3C), sscanf_s(3C), strcat_s(3C), strcpy_s(3C), strerror_s(3C), strerrorlen_s(3C), strncat_s(3C)), strncpy_s(3C), strnlen_s(3C), strtok_s(3C), swscanf_s(3C), tmpfile_s(3C), tmpnam_s(3C), vfprintf_s(3C), vfscanf_s(3C), vfwprintf_s (3C) , vfwscanf_s(3C), vprintf_s(3C), vscanf_s(3C), vsnprintf_s(3C), vsscanf_s(3C), vswscanf_s(3C), vwscanf_s(3C), wcrtomb_s(3C), wcscat_s(3C), wcscpy_s(3C), wcsncat_s(3C), wcsncpy_s(3C), wcsnlen_s(3C), wcsrtombs_s(3C), wcstok_s(3C), wcstombs_s(3C), wctomb_s(3C), wmemcpy_s(3C), wmemmove_s(3C), wprintf(3C), wscanf_s(3C), libc(3LIB)