[clang][modules] Don't prevent translation of FW_Private includes when explicitly...
[llvm-project.git] / clang-tools-extra / docs / clang-tidy / checks / bugprone / signal-handler.rst
blob658b6555f1a1caca6976899c3e4f03eeb42f0513
1 .. title:: clang-tidy - bugprone-signal-handler
3 bugprone-signal-handler
4 =======================
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.
9 Checked signal handler rules for C:
11 - Calls to non-asynchronous-safe functions are not allowed.
13 Checked signal handler rules for up to and including C++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).
21 The check is disabled on C++17 and later.
23 Asynchronous-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.
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``.
40 Options
41 -------
43 .. option:: AsyncSafeFunctionSet
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``
94      The function ``quick_exit`` is not included in the POSIX list but it
95      is included here in the set of safe functions.
97   The default value is ``POSIX``.