## 7.14 Signal handling <signal.h>

1. The header `<signal.h>` declares a type and two functions and defines several macros, for handling various *signals* (conditions that may be reported during program execution).

2. The type defined is

`sig_atomic_t`

which is the (possibly volatile-qualified) integer type of an object that can be accessed as an atomic entity, even in the presence of asynchronous interrupts.

3. The macros defined are

```
SIG_DFL
SIG_ERR
SIG_IGN
```

which expand to constant expressions with distinct values that have type compatible with the second argument to, and the return value of, the **signal** function, and whose values compare unequal to the address of any declarable function; and the following, which expand to positive integer constant expressions with type **int** and distinct values that are the signal numbers, each corresponding to the specified condition:

**SIGABRT** abnormal termination, such as is initiated by the **abort** function

**SIGFPE** an erroneous arithmetic operation, such as zero divide or an operation resulting in overflow

**SIGILL** detection of an invalid function image, such as an invalid instruction

**SIGINT** receipt of an interactive attention signal

**SIGSEGV** an invalid access to storage

**SIGTERM** a termination request sent to the program

4. An implementation need not generate any of these signals, except as a result of explicit calls to the **raise** function. Additional signals and pointers to undeclarable functions, with macro definitions beginning, respectively, with the letters **SIG** and an uppercase letter or with **SIG_** and an uppercase letter,<fnref n="277" /> may also be specified by the implementation. The complete set of signals, their semantics, and their default handling is implementation-defined; all signal numbers shall be positive.

### 7.14.1 Specify signal handling

#### 7.14.1.1 The signal function

**Synopsis**

```
1. #include <signal.h>
    void (*signal)(int sig, void (*func)(int))(int);
```

**Description**

2. The **signal** function chooses one of three ways in which receipt of the signal number **sig** is to be subsequently handled. If the value of **func** is **SIG_DFL**, default handling for that signal will occur. If the value of **func** is **SIG_IGN**, the signal will be ignored. Otherwise, **func** shall point to a function or shall be the result of a conversion of a function literal to a function pointer. The function or lambda value is then to be called when that signal occurs. An invocation of such a function or function literal because of a signal, or (recursively) of any further functions or lambdas called by that invocation (other than functions in the standard library),<fnref n="278" />) is called a *signal handler*.

<footnote n="277">²⁷⁷) See "future library directions" (7.31.7). The names of the signal numbers reflect the following terms (respectively): abort, floating-point exception, illegal instruction, interrupt, segmentation violation, and termination.</footnote>

<footnote n="278">²⁷⁸) This includes functions called indirectly via standard library functions (e.g., a **SIGABRT** handler called via the **abort** function).</footnote>
3 When a signal occurs and `func` points to a function,<fnref n="279" />) it is implementation-defined whether the equivalent of `signal(sig, SIG_DFL)`; is executed or the implementation prevents some implementation-defined set of signals (at least including `sig`) from occurring until the current signal handling has completed; in the case of `SIGILL`, the implementation may alternatively define that no action is taken. Then the equivalent of `(*func)(sig)`; is executed. If and when the function returns, if the value of `sig` is `SIGFPE`, `SIGILL`, `SIGSEGV`, or any other implementation-defined value corresponding to a computational exception, the behavior is undefined; otherwise the program will resume execution at the point it was interrupted.

4 If the signal occurs as the result of calling the `abort` or `raise` function, the signal handler shall not call the `raise` function.

5 If the signal occurs other than as the result of calling the `abort` or `raise` function, the behavior is undefined if the signal handler refers to any object with static or thread storage duration that is not a lock-free atomic object other than by assigning a value to an object declared as `volatile sig_atomic_t`, or the signal handler calls any function in the standard library other than

- the `abort` function,

- the `_Exit` function,

- the `quick_exit` function,

- the functions in `<stdatomic.h>` (except where explicitly stated otherwise) when the atomic arguments are lock-free,

- the `atomic_is_lock_free` function with any atomic argument, or

- the `signal` function with the first argument equal to the signal number corresponding to the signal that caused the invocation of the handler. Furthermore, if such a call to the `signal` function results in a `SIG_ERR` return, the value of `errno` is indeterminate.<fnref n="280" />)

6 At program startup, the equivalent of

`signal(sig, SIG_IGNORE);`

may be executed for some signals selected in an implementation-defined manner; the equivalent of

`signal(sig, SIG_DFL);`

is executed for all other signals defined by the implementation.

7 Use of this function in a multi-threaded program results in undefined behavior. The implementation shall behave as if no library function calls the `signal` function.

### Returns

8 If the request can be honored, the `signal` function returns the value of `func` for the most recent successful call to `signal` for the specified signal `sig`. Otherwise, a value of `SIG_ERR` is returned and a positive value is stored in `errno`.

**Forward references:** the `abort` function (7.22.4.1), the `exit` function (7.22.4.4), the `_Exit` function (7.22.4.5), the `quick_exit` function (7.22.4.7).

## 7.14.2 Send signal

### 7.14.2.1 The `raise` function

#### Synopsis

1

```c
#include <signal.h>
int raise(int sig);
```

<footnote n="279">²⁷⁹) Or, equivalently, it is the result of a conversion of a function literal to a function pointer.</footnote>

<footnote n="280">²⁸⁰) If any signal is generated by an asynchronous signal handler, the behavior is undefined.</footnote>
## 7.16 Variable arguments <stdarg.h>

1. The header `<stdarg.h>` declares a type and defines four macros, for advancing through a list of arguments whose number and types are not known to the called function when it is translated.

2. A function may be called with a variable number of arguments of varying types. As described in 6.9.1, its parameter list contains one or more parameters. The rightmost parameter plays a special role in the access mechanism, and will be designated `parmN` in this description.

3. The type declared is

`va_list`

which is a complete object type suitable for holding information needed by the macros `va_start`, `va_arg`, `va_end`, and `va_copy`. If access to the varying arguments is desired, the called function shall declare an object (generally referred to as `ap` in this subclause) having type `va_list`. The object `ap` may be passed as an argument to another function; if that function call, if the called function or lambda invokes the `va_arg` macro with parameter `ap`, the value of `ap` in the calling function or lambda is indeterminate and shall be passed to the `va_end` macro prior to any further reference to `ap`.<fnref n="281" />)

4. **NOTE** Because the ... parameter syntax is not valid for lambda expressions, these macros can never be applied directly to process a variable list of arguments to the call of a lambda. In contrast to that, the type `va_list` itself can be a parameter type of a lambda expression to process the argument list of a function.

### 7.16.1 Variable argument list access macros

1. The `va_start` and `va_arg` macros described in this subclause shall be implemented as macros, not functions. It is unspecified whether `va_copy` and `va_end` are macros or identifiers declared with external linkage. If a macro definition is suppressed in order to access an actual function, or a program defines an external identifier with the same name, the behavior is undefined. Each invocation of the `va_start` and `va_copy` macros shall be matched by a corresponding invocation of the `va_end` macro in the same function or lambda expression.

#### 7.16.1.1 The `va_arg` macro

**Synopsis**

```
1
    #include <stdarg.h>
    type va_arg(va_list ap, type);
```

**Description**

2. The `va_arg` macro expands to an expression that has the specified type and the value of the next argument in the call. The parameter `ap` shall have been initialized by the `va_start` or `va_copy` macro (without an intervening invocation of the `va_end` macro for the same `ap`). Each invocation of the `va_arg` macro modifies `ap` so that the values of successive arguments are returned in turn. The parameter `type` shall be a type name specified such that the type of a pointer to an object that has the specified type can be obtained simply by postfixing a `*` to `type`. If there is no actual next argument, or if `type` is not compatible with the type of the actual next argument (as promoted according to the default argument promotions), the behavior is undefined, except for the following cases:

- one type is a signed integer type, the other type is the corresponding unsigned integer type, and the value is representable in both types;

- one type is pointer to `void` and the other is a pointer to a character type.

**Returns**

3. The first invocation of the `va_arg` macro after that of the `va_start` macro returns the value of the argument after that specified by `parmN`. Successive invocations return the values of the remaining arguments in succession.

<footnote n="281">²⁸¹) It is permitted to create a pointer to a `va_list` and pass that pointer to another function or lambda, in which case the original calling function or lambda can make further use of the original list after the other function returns.</footnote>
### 7.16.1.2 The `va_copy` macro

#### Synopsis

1
```c
#include <stdlib.h>
void va_copy va_list dest, va_list src);
```

#### Description

2
The `va_copy` macro initializes `dest` as a copy of `src`, as if the `va_start` macro had been applied to `dest` followed by the same sequence of uses of the `va_arg` macro as had previously been used to reach the present state of `src`. Neither the `va_copy` nor `va_start` macro shall be invoked to reinitialize `dest` without an intervening invocation of the `va_end` macro for the same `dest`.

#### Returns

3
The `va_copy` macro returns no value.

### 7.16.1.3 The `va_end` macro

#### Synopsis

1
```c
#include <stdlib.h>
void va_end va_list ap);
```

#### Description

2
The `va_end` macro facilitates a normal return from the function whose variable argument list was referred to by the expansion of the `va_start` macro, or the function or lambda expression containing the expansion of the `va_copy` macro, that initialized the `va_list ap`. The `va_end` macro may modify `ap` so that it is no longer usable (without being reinitialized by the `va_start` or `va_copy` macro). If there is no corresponding invocation of the `va_start` or `va_copy` macro, or if the `va_end` macro is not invoked before the return, the behavior is undefined.

#### Returns

3
The `va_end` macro returns no value.

### 7.16.1.4 The `va_start` macro

#### Synopsis

1
```c
#include <stdlib.h>
void va_start va_list ap, parmN);
```

#### Description

2
The `va_start` macro shall be invoked before any access to the unnamed arguments.

3
The `va_start` macro initializes `ap` for subsequent use by the `va_arg` and `va_end` macros. Neither the `va_start` nor `va_copy` macro shall be invoked to reinitialize `ap` without an intervening invocation of the `va_end` macro for the same `ap`.

4
The parameter `parmN` is the identifier of the rightmost parameter in the variable parameter list in the function definition (the one just before the `; ...`). If the parameter `parmN` is declared with the `register` storage class, with a function or array type, or with a type that is not compatible with the type that results after application of the default argument promotions, the behavior is undefined.

#### Returns

5
The `va_start` macro returns no value.

6
EXAMPLE 1 The function `f1` gathers into an array a list of arguments that are pointers to strings (but not more than `MAXARGS` arguments), then passes the array as a single argument to function `f2`. The number of pointers is specified by the first argument to `f1`.
## Returns

4. The `realloc` function returns a pointer to the new object (which may have the same value as a pointer to the old object), or a null pointer if the new object has not been allocated.

## 7.22.4 Communication with the environment

### 7.22.4.1 The abort function

#### Synopsis

1.
```c
#include <stdlib.h>
__Noreturn void abort(void);
```

#### Description

2. The `abort` function causes abnormal program termination to occur, unless the signal `SIGABRT` is being caught and the signal handler does not return. Whether open streams with unwritten buffered data are flushed, open streams are closed, or temporary files are removed is implementation-defined. An implementation-defined form of the status *unsuccessful termination* is returned to the host environment by means of the function call `raise(SIGABRT)`.

## Returns

3. The `abort` function does not return to its caller.

### 7.22.4.2 The atexit function

#### Synopsis

1.
```c
#include <stdlib.h>
int atexit(void (*func)(void));
```

#### Description

2. The `atexit` function registers the function `or function literal` pointed to by `func`, to be called without arguments at normal program termination.<fnref n="326" />⁾ It is unspecified whether a call to the `atexit` function that does not happen before the `exit` function is called will succeed.

#### Environmental limits

3. The implementation shall support the registration of at least 32 `functions`/`function pointers`.

## Returns

4. The `atexit` function returns zero if the registration succeeds, nonzero if it fails.

**Forward references:** the `at_quick_exit` function (7.22.4.3), the `exit` function (7.22.4.4).

### 7.22.4.3 The at_quick_exit function

#### Synopsis

1.
```c
#include <stdlib.h>
int at_quick_exit(void (*func)(void));
```

#### Description

2. The `atquick_exit` function registers the function `or function literal` pointed to by `func`, to be called without arguments should `quick_exit` be called.<fnref n="327" />⁾ It is unspecified whether a call to the `atquick_exit` function that does not happen before the `quick_exit` function is called will succeed.

<footnote n="326">³²⁶⁾ The `atexit` function registrations are distinct from the `atquick_exit` registrations, so applications might need to call both registration functions with the same argument.</footnote>

<footnote n="327">³²⁷⁾ The `atquick_exit` function registrations are distinct from the `atexit` registrations, so applications might need to call both registration functions with the same argument.</footnote>
### Environmental limits

3. The implementation shall support the registration of at least 32 `functions`/`function pointers`.

### Returns

4. The `at__quick_exit` function returns zero if the registration succeeds, nonzero if it fails.

**Forward references:** the `quick_exit` function (7.22.4.7).

### 7.22.4.4 The `exit` function

#### Synopsis

```c
#include <stdlib.h>
__Noreturn void exit(int status);
```

#### Description

2. The `exit` function causes normal program termination to occur. No `functions`/`function pointers` registered by the `at__quick_exit` function are called. If a program calls the `exit` function more than once, or calls the `quick_exit` function in addition to the `exit` function, the behavior is undefined.

3. First, all `functions`/`function pointers` registered by the `atexit` function are called, in the reverse order of their registration,<fnref n="328" />) except that a function `pointer` is called after any previously registered `functions`/`function pointers` that had already been called at the time it was registered. If, during the call to any such function or `function literal`, a call to the `longjmp` function is made that would terminate the call to the registered function or `function literal`, the behavior is undefined.

4. Next, all open streams with unwritten buffered data are flushed, all open streams are closed, and all files created by the `tmpfile` function are removed.

5. Finally, control is returned to the host environment. If the value of `status` is zero or `EXIT_SUCCESS`, an implementation-defined form of the status `successful termination` is returned. If the value of `status` is `EXIT_FAILURE`, an implementation-defined form of the status `unsuccessful termination` is returned. Otherwise the status returned is implementation-defined.

#### Returns

6. The `exit` function cannot return to its caller.

### 7.22.4.5 The `_Exit` function

#### Synopsis

```c
#include <stdlib.h>
__Noreturn void _Exit(int status);
```

#### Description

2. The `_Exit` function causes normal program termination to occur and control to be returned to the host environment. No `functions`/`function pointers` registered by the `atexit` function, the `at__quick_exit` function, or signal handlers registered by the `signal` function are called. The status returned to the host environment is determined in the same way as for the `exit` function (7.22.4.4). Whether open streams with unwritten buffered data are flushed, open streams are closed, or temporary files are removed is implementation-defined.

#### Returns

3. The `_Exit` function cannot return to its caller.

### 7.22.4.6 The `getenv` function

#### Synopsis

```c
#include <stdlib.h>
```

<footnote n="328">³²⁸) Each function is called as many times as it was registered, and in the correct order with respect to other registered `functions`/`function pointers`.</footnote>
```c
char *getenv(const char *name);
```

### Description

2. The `getenv` function searches an *environment list*, provided by the host environment, for a string that matches the string pointed to by `name`. The set of environment names and the method for altering the environment list are implementation-defined. The `getenv` function need not avoid data races with other threads of execution that modify the environment list.<fnref n="329" />)

3. The implementation shall behave as if no library function calls the `getenv` function.

### Returns

4. The `getenv` function returns a pointer to a string associated with the matched list member. The string pointed to shall not be modified by the program, but may be overwritten by a subsequent call to the `getenv` function. If the specified `name` cannot be found, a null pointer is returned.

## 7.22.4.7 The quick_exit function

### Synopsis

```c
#include <stdlib.h>
_Noreturn void quick_exit(int status);
```

### Description

2. The `quick_exit` function causes normal program termination to occur. No *functions function pointers* registered by the `atexit` function or signal handlers registered by the `signal` function are called. If a program calls the `quick_exit` function more than once, or calls the `exit` function in addition to the `quick_exit` function, the behavior is undefined. If a signal is raised while the `quick_exit` function is executing, the behavior is undefined.

3. The `quick_exit` function first calls all *functions function pointers* registered by the `at, quick_exit` function, in the reverse order of their registration,<fnref n="330" />) except that a function *pointer* is called after any previously registered *functions function pointers* that had already been called at the time it was registered. If, during the call to any such function *or function literal*, a call to the `longjmp` function is made that would terminate the call to the registered function *pointer*, the behavior is undefined.

4. Then control is returned to the host environment by means of the function call `_Exit(status)`.

### Returns

5. The `quick_exit` function cannot return to its caller.

## 7.22.4.8 The system function

### Synopsis

```c
#include <stdlib.h>
int system(const char *string);
```

### Description

2. If `string` is a null pointer, the `system` function determines whether the host environment has a *command processor*. If `string` is not a null pointer, the `system` function passes the string pointed to by `string` to that command processor to be executed in a manner which the implementation shall document; this might then cause the program calling `system` to behave in a non-conforming manner or to terminate.

### Returns

3. If the argument is a null pointer, the `system` function returns nonzero only if a command processor is available. If the argument is not a null pointer, and the `system` function does return, it returns an

<footnote n="329">³²⁹) Many implementations provide non-standard functions that modify the environment list.</footnote>

<footnote n="330">³³⁰) Each function *pointer* is called as many times as it was registered, and in the correct order with respect to other registered *functions function pointers*.</footnote>
implementation-defined value.

### 7.22.5 Searching and sorting utilities

1. These utilities make use of a comparison function `or function literal` to search or sort arrays of unspecified type. Where an argument declared as `size_t nmemb` specifies the length of the array for a function, `nmemb` can have the value zero on a call to that function; the comparison function `or function literal` is not called, a search finds no matching element, and sorting performs no rearrangement. Pointer arguments on such a call shall still have valid values, as described in 7.1.4.

2. The implementation shall ensure that the second argument of the comparison function `or function literal` (when called from `bsearch`), or both arguments (when called from `qsort`), are pointers to elements of the array.<fnref n="331" /> The first argument when called from `bsearch` shall equal `key`.

3. The comparison function `or function literal` shall not alter the contents of the array. The implementation may reorder elements of the array between calls to the comparison function `or function literal`, but shall not alter the contents of any individual element.

4. When the same objects (consisting of `size` bytes, irrespective of their current positions in the array) are passed more than once to the comparison function `or function literal`, the results shall be consistent with one another. That is, for `qsort` they shall define a total ordering on the array, and for `bsearch` the same object shall always compare the same way with the key.

5. A sequence point occurs immediately before and immediately after each call to the comparison function `or function literal`, and also between any call to the comparison function `or function literal` and any movement of the objects passed as arguments to that call.

#### 7.22.5.1 The bsearch function

**Synopsis**

```c
#include <stdlib.h>
void *bsearch(const void *key, const void *base,
    size_t nmemb, size_t size,
    int (*compar)(const void *, const void *));
```

**Description**

2. The `bsearch` function searches an array of `nmemb` objects, the initial element of which is pointed to by `base`, for an element that matches the object pointed to by `key`. The size of each element of the array is specified by `size`.

3. The comparison function `or function literal` pointed to by `compar` is called with two arguments that point to the `key` object and to an array element, in that order. The function `compar` shall return an integer less than, equal to, or greater than zero if the `key` object is considered, respectively, to be less than, to match, or to be greater than the array element. The array shall consist of: all the elements that compare less than, all the elements that compare equal to, and all the elements that compare greater than the `key` object, in that order.<fnref n="332" />

**Returns**

4. The `bsearch` function returns a pointer to a matching element of the array, or a null pointer if no match is found. If two elements compare as equal, which element is matched is unspecified.

((char *)p - (char *)base) % size == 0
(char *)p >= (char *)base
(char *)p < (char *)base + nmemb * size

<footnote n="331">³³¹)That is, if the value passed is `p`, then the following expressions are always nonzero:</footnote>

<footnote n="332">³³²)In practice, the entire array is sorted according to the comparison function.</footnote>
### 7.22.5.2 The `qsort` function

#### Synopsis

```c
#include <stdlib.h>
void qsort(void *base, size_t nmemb, size_t size,
          int (*compar)(const void *, const void *));
```

#### Description

2. The `qsort` function sorts an array of `nmemb` objects, the initial element of which is pointed to by `base`. The size of each object is specified by `size`.

3. The contents of the array are sorted into ascending order according to a comparison function or function literal pointed to by `compar`, which is called with two arguments that point to the objects being compared. The function A function call shall return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.

4. If two elements compare as equal, their order in the resulting sorted array is unspecified.

#### Returns

5. The `qsort` function returns no value.

## 7.22.6 Integer arithmetic functions

### 7.22.6.1 The `abs`, `labs` and `dlabs` functions

#### Synopsis

```c
#include <stdlib.h>
int abs(int j);
long int labs(long int j);
long long int llabs(long long int j);
```

#### Description

2. The `abs`, `labs`, and `llabs` functions compute the absolute value of an integer `j`. If the result cannot be represented, the behavior is undefined.<fnref n="333" />)

#### Returns

3. The `abs`, `labs`, and `llabs`, functions return the absolute value.

### 7.22.6.2 The `div`, `ldiv`, and `lldiv` functions

#### Synopsis

```c
#include <stdlib.h>
div_t div(int numer, int denom);
ldiv_t ldiv(long int numer, long int denom);
lldiv_t lldiv(long long int numer, long long int denom);
```

#### Description

2. The `div`, `ldiv`, and `lldiv`, functions compute `numer/denom` and `numer%denom` in a single operation.

#### Returns

3. The `div`, `ldiv`, and `lldiv` functions return a structure of type `div_t`, `ldiv_t`, and `lldiv_t`, respectively, comprising both the quotient and the remainder. The structures shall contain (in either order) the members `quot` (the quotient) and `rem` (the remainder), each of which has the same type as the arguments `numer` and `denom`. If either part of the result cannot be represented, the behavior is undefined.

<footnote n="333">³³³) The absolute value of the most negative number cannot be represented in two's complement.</footnote>
(6.5.1.1) generic-selection:
Generic ( assignment-expression , generic-assoc-list )

(6.5.1.1) generic-assoc-list:
generic-association
generic-assoc-list , generic-association

(6.5.1.1) generic-association:
type-name : assignment-expression
default : assignment-expression

(6.5.2) postfix-expression:
primary-expression
postfix-expression [ expression ]
postfix-expression ( argument-expression-list<sub>opt</sub> )
postfix-expression . identifier
postfix-expression -> identifier
postfix-expression ++
postfix-expression -
( type-name ) { initializer-list }
( type-name ) { initializer-list , }

(6.5.2) argument-expression-list:
assignment-expression
argument-expression-list , assignment-expression

(6.5.2.6) lambda-expression:
~~ capture-clause parameter-clause<sub>opt</sub> attribute-specifier-sequence<sub>opt</sub> function-body

(6.5.2.6) capture-clause:
[ capture-list<sub>opt</sub> ]

(6.5.2.6) capture-list:
~~ capture-list-element
~~ capture-list , capture-list-element

(6.5.2.6) capture-list-element:
value-capture
identifier-capture

(6.5.2.6) value-capture:
~~ capture = assignment-expression

(6.5.2.6) identifier-capture:
& capture

(6.5.2.6) capture:
~~ identifier

(6.5.2.6) parameter-clause:
( parameter-list<sub>opt</sub> )

(6.5.3) unary-expression:
postfix-expression
++ unary-expression
- unary-expression
unary-operator cast-expression
sizeof unary-expression
sizeof ( type-name )
Alignof ( type-name )