clang-tools-extra/docs/clang-tidy/checks/bugprone/unsafe-functions.rst

   1 .. title:: clang-tidy - bugprone-unsafe-functions
   2
   3 bugprone-unsafe-functions
   4 =========================
   5
   6 Checks for functions that have safer, more secure replacements available, or
   7 are considered deprecated due to design flaws.
   8 The check heavily relies on the functions from the
   9 **Annex K.** "Bounds-checking interfaces" of C11.
  10
  11 The check implements the following rules from the CERT C Coding Standard:
  12   - Recommendation `MSC24-C. Do not use deprecated or obsolescent functions
  13     <https://wiki.sei.cmu.edu/confluence/display/c/MSC24-C.+Do+not+use+deprecated+or+obsolescent+functions>`_.
  14   - Rule `MSC33-C. Do not pass invalid data to the asctime() function
  15     <https://wiki.sei.cmu.edu/confluence/display/c/MSC33-C.+Do+not+pass+invalid+data+to+the+asctime%28%29+function>`_.
  16
  17 `cert-msc24-c` and `cert-msc33-c` redirect here as aliases of this check.
  18
  19 Unsafe functions
  20 ----------------
  21
  22 If *Annex K.* is available, a replacement from *Annex K.* is suggested for the
  23 following functions:
  24
  25 ``asctime``, ``asctime_r``, ``bsearch``, ``ctime``, ``fopen``, ``fprintf``,
  26 ``freopen``, ``fscanf``, ``fwprintf``, ``fwscanf``, ``getenv``, ``gets``,
  27 ``gmtime``, ``localtime``, ``mbsrtowcs``, ``mbstowcs``, ``memcpy``,
  28 ``memmove``, ``memset``, ``printf``, ``qsort``, ``scanf``,  ``snprintf``,
  29 ``sprintf``,  ``sscanf``, ``strcat``, ``strcpy``, ``strerror``, ``strlen``,
  30 ``strncat``, ``strncpy``, ``strtok``, ``swprintf``, ``swscanf``, ``vfprintf``,
  31 ``vfscanf``, ``vfwprintf``, ``vfwscanf``, ``vprintf``, ``vscanf``,
  32 ``vsnprintf``, ``vsprintf``, ``vsscanf``, ``vswprintf``, ``vswscanf``,
  33 ``vwprintf``, ``vwscanf``, ``wcrtomb``, ``wcscat``, ``wcscpy``,
  34 ``wcslen``, ``wcsncat``, ``wcsncpy``, ``wcsrtombs``, ``wcstok``, ``wcstombs``,
  35 ``wctomb``, ``wmemcpy``, ``wmemmove``, ``wprintf``, ``wscanf``.
  36
  37 If *Annex K.* is not available, replacements are suggested only for the
  38 following functions from the previous list:
  39
  40  - ``asctime``, ``asctime_r``, suggested replacement: ``strftime``
  41  - ``gets``, suggested replacement: ``fgets``
  42
  43 The following functions are always checked, regardless of *Annex K* availability:
  44
  45  - ``rewind``, suggested replacement: ``fseek``
  46  - ``setbuf``, suggested replacement: ``setvbuf``
  47
  48 If `ReportMoreUnsafeFunctions
  49 <unsafe-functions.html#cmdoption-arg-ReportMoreUnsafeFunctions>`_ is enabled,
  50 the following functions are also checked:
  51
  52  - ``bcmp``, suggested replacement: ``memcmp``
  53  - ``bcopy``, suggested replacement: ``memcpy_s`` if *Annex K* is available,
  54    or ``memcpy``
  55  - ``bzero``, suggested replacement: ``memset_s`` if *Annex K* is available,
  56    or ``memset``
  57  - ``getpw``, suggested replacement: ``getpwuid``
  58  - ``vfork``, suggested replacement: ``posix_spawn``
  59
  60 Although mentioned in the associated CERT rules, the following functions are
  61 **ignored** by the check:
  62
  63 ``atof``, ``atoi``, ``atol``, ``atoll``, ``tmpfile``.
  64
  65 The availability of *Annex K* is determined based on the following macros:
  66
  67  - ``__STDC_LIB_EXT1__``: feature macro, which indicates the presence of
  68    *Annex K. "Bounds-checking interfaces"* in the library implementation
  69  - ``__STDC_WANT_LIB_EXT1__``: user-defined macro, which indicates that the
  70    user requests the functions from *Annex K.* to be defined.
  71
  72 Both macros have to be defined to suggest replacement functions from *Annex K.*
  73 ``__STDC_LIB_EXT1__`` is defined by the library implementation, and
  74 ``__STDC_WANT_LIB_EXT1__`` must be defined to ``1`` by the user **before**
  75 including any system headers.
  76
  77
  78 Options
  79 -------
  80
  81 .. option:: ReportMoreUnsafeFunctions
  82
  83    When `true`, additional functions from widely used APIs (such as POSIX) are
  84    added to the list of reported functions.
  85    See the main documentation of the check for the complete list as to what
  86    this option enables.
  87    Default is `true`.
  88
  89
  90 Examples
  91 --------
  92
  93 .. code-block:: c++
  94
  95     #ifndef __STDC_LIB_EXT1__
  96     #error "Annex K is not supported by the current standard library implementation."
  97     #endif
  98
  99     #define __STDC_WANT_LIB_EXT1__ 1
 100
 101     #include <string.h> // Defines functions from Annex K.
 102     #include <stdio.h>
 103
 104     enum { BUFSIZE = 32 };
 105
 106     void Unsafe(const char *Msg) {
 107       static const char Prefix[] = "Error: ";
 108       static const char Suffix[] = "\n";
 109       char Buf[BUFSIZE] = {0};
 110
 111       strcpy(Buf, Prefix); // warning: function 'strcpy' is not bounds-checking; 'strcpy_s' should be used instead.
 112       strcat(Buf, Msg);    // warning: function 'strcat' is not bounds-checking; 'strcat_s' should be used instead.
 113       strcat(Buf, Suffix); // warning: function 'strcat' is not bounds-checking; 'strcat_s' should be used instead.
 114       if (fputs(buf, stderr) < 0) {
 115         // error handling
 116         return;
 117       }
 118     }
 119
 120     void UsingSafeFunctions(const char *Msg) {
 121       static const char Prefix[] = "Error: ";
 122       static const char Suffix[] = "\n";
 123       char Buf[BUFSIZE] = {0};
 124
 125       if (strcpy_s(Buf, BUFSIZE, Prefix) != 0) {
 126         // error handling
 127         return;
 128       }
 129
 130       if (strcat_s(Buf, BUFSIZE, Msg) != 0) {
 131         // error handling
 132         return;
 133       }
 134
 135       if (strcat_s(Buf, BUFSIZE, Suffix) != 0) {
 136         // error handling
 137         return;
 138       }
 139
 140       if (fputs(Buf, stderr) < 0) {
 141         // error handling
 142         return;
 143       }
 144     }