| 1 |
.. title:: clang-tidy - bugprone-signal-handler |
| 2 |
|
| 3 |
bugprone-signal-handler |
| 4 |
======================= |
| 5 |
|
| 6 |
Finds specific constructs in signal handler functions that can cause undefined |
| 7 |
behavior. The rules for what is allowed differ between C++ language versions. |
| 8 |
|
| 9 |
Checked signal handler rules for C: |
| 10 |
|
| 11 |
- Calls to non-asynchronous-safe functions are not allowed. |
| 12 |
|
| 13 |
Checked signal handler rules for up to and including C++14: |
| 14 |
|
| 15 |
- Calls to non-asynchronous-safe functions are not allowed. |
| 16 |
- C++-specific code constructs are not allowed in signal handlers. |
| 17 |
In other words, only the common subset of C and C++ is allowed to be used. |
| 18 |
- Calls to functions with non-C linkage are not allowed (including the signal |
| 19 |
handler itself). |
| 20 |
|
| 21 |
The check is disabled on C++17 and later. |
| 22 |
|
| 23 |
Asnychronous-safety is determined by comparing the function's name against a set |
| 24 |
of known functions. In addition, the function must come from a system header |
| 25 |
include and in a global namespace. The (possible) arguments passed to the |
| 26 |
function are not checked. Any function that cannot be determined to be |
| 27 |
asynchronous-safe is assumed to be non-asynchronous-safe by the check, |
| 28 |
including user functions for which only the declaration is visible. |
| 29 |
Calls to user-defined functions with visible definitions are checked |
| 30 |
recursively. |
| 31 |
|
| 32 |
This check implements the CERT C Coding Standard rule |
| 33 |
`SIG30-C. Call only asynchronous-safe functions within signal handlers |
| 34 |
<https://www.securecoding.cert.org/confluence/display/c/SIG30-C.+Call+only+asynchronous-safe+functions+within+signal+handlers>`_ |
| 35 |
and the rule |
| 36 |
`MSC54-CPP. A signal handler must be a plain old function |
| 37 |
<https://wiki.sei.cmu.edu/confluence/display/cplusplus/MSC54-CPP.+A+signal+handler+must+be+a+plain+old+function>`_. |
| 38 |
It has the alias names ``cert-sig30-c`` and ``cert-msc54-cpp``. |
| 39 |
|
| 40 |
Options |
| 41 |
------- |
| 42 |
|
| 43 |
.. option:: AsyncSafeFunctionSet |
| 44 |
|
| 45 |
Selects which set of functions is considered as asynchronous-safe |
| 46 |
(and therefore allowed in signal handlers). It can be set to the following values: |
| 47 |
|
| 48 |
``minimal`` |
| 49 |
Selects a minimal set that is defined in the CERT SIG30-C rule. |
| 50 |
and includes functions ``abort()``, ``_Exit()``, ``quick_exit()`` and |
| 51 |
``signal()``. |
| 52 |
``POSIX`` |
| 53 |
Selects a larger set of functions that is listed in POSIX.1-2017 (see `this |
| 54 |
link |
| 55 |
<https://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_04_03>`_ |
| 56 |
for more information). The following functions are included: |
| 57 |
``_Exit``, ``_exit``, ``abort``, ``accept``, ``access``, ``aio_error``, |
| 58 |
``aio_return``, ``aio_suspend``, ``alarm``, ``bind``, ``cfgetispeed``, |
| 59 |
``cfgetospeed``, ``cfsetispeed``, ``cfsetospeed``, ``chdir``, ``chmod``, |
| 60 |
``chown``, ``clock_gettime``, ``close``, ``connect``, ``creat``, ``dup``, |
| 61 |
``dup2``, ``execl``, ``execle``, ``execv``, ``execve``, ``faccessat``, |
| 62 |
``fchdir``, ``fchmod``, ``fchmodat``, ``fchown``, ``fchownat``, ``fcntl``, |
| 63 |
``fdatasync``, ``fexecve``, ``ffs``, ``fork``, ``fstat``, ``fstatat``, |
| 64 |
``fsync``, ``ftruncate``, ``futimens``, ``getegid``, ``geteuid``, |
| 65 |
``getgid``, ``getgroups``, ``getpeername``, ``getpgrp``, ``getpid``, |
| 66 |
``getppid``, ``getsockname``, ``getsockopt``, ``getuid``, ``htonl``, |
| 67 |
``htons``, ``kill``, ``link``, ``linkat``, ``listen``, ``longjmp``, |
| 68 |
``lseek``, ``lstat``, ``memccpy``, ``memchr``, ``memcmp``, ``memcpy``, |
| 69 |
``memmove``, ``memset``, ``mkdir``, ``mkdirat``, ``mkfifo``, ``mkfifoat``, |
| 70 |
``mknod``, ``mknodat``, ``ntohl``, ``ntohs``, ``open``, ``openat``, |
| 71 |
``pause``, ``pipe``, ``poll``, ``posix_trace_event``, ``pselect``, |
| 72 |
``pthread_kill``, ``pthread_self``, ``pthread_sigmask``, ``quick_exit``, |
| 73 |
``raise``, ``read``, ``readlink``, ``readlinkat``, ``recv``, ``recvfrom``, |
| 74 |
``recvmsg``, ``rename``, ``renameat``, ``rmdir``, ``select``, ``sem_post``, |
| 75 |
``send``, ``sendmsg``, ``sendto``, ``setgid``, ``setpgid``, ``setsid``, |
| 76 |
``setsockopt``, ``setuid``, ``shutdown``, ``sigaction``, ``sigaddset``, |
| 77 |
``sigdelset``, ``sigemptyset``, ``sigfillset``, ``sigismember``, |
| 78 |
``siglongjmp``, ``signal``, ``sigpause``, ``sigpending``, ``sigprocmask``, |
| 79 |
``sigqueue``, ``sigset``, ``sigsuspend``, ``sleep``, ``sockatmark``, |
| 80 |
``socket``, ``socketpair``, ``stat``, ``stpcpy``, ``stpncpy``, |
| 81 |
``strcat``, ``strchr``, ``strcmp``, ``strcpy``, ``strcspn``, ``strlen``, |
| 82 |
``strncat``, ``strncmp``, ``strncpy``, ``strnlen``, ``strpbrk``, |
| 83 |
``strrchr``, ``strspn``, ``strstr``, ``strtok_r``, ``symlink``, |
| 84 |
``symlinkat``, ``tcdrain``, ``tcflow``, ``tcflush``, ``tcgetattr``, |
| 85 |
``tcgetpgrp``, ``tcsendbreak``, ``tcsetattr``, ``tcsetpgrp``, |
| 86 |
``time``, ``timer_getoverrun``, ``timer_gettime``, ``timer_settime``, |
| 87 |
``times``, ``umask``, ``uname``, ``unlink``, ``unlinkat``, ``utime``, |
| 88 |
``utimensat``, ``utimes``, ``wait``, ``waitpid``, ``wcpcpy``, |
| 89 |
``wcpncpy``, ``wcscat``, ``wcschr``, ``wcscmp``, ``wcscpy``, ``wcscspn``, |
| 90 |
``wcslen``, ``wcsncat``, ``wcsncmp``, ``wcsncpy``, ``wcsnlen``, ``wcspbrk``, |
| 91 |
``wcsrchr``, ``wcsspn``, ``wcsstr``, ``wcstok``, ``wmemchr``, ``wmemcmp``, |
| 92 |
``wmemcpy``, ``wmemmove``, ``wmemset``, ``write`` |
| 93 |
|
| 94 |
The function ``quick_exit`` is not included in the POSIX list but it |
| 95 |
is included here in the set of safe functions. |
| 96 |
|
| 97 |
The default value is ``POSIX``. |