diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst --- a/clang/docs/analyzer/checkers.rst +++ b/clang/docs/analyzer/checkers.rst @@ -2434,7 +2434,7 @@ void test_alnum_concrete(int v) { int ret = isalnum(256); // \ - // warning: Function argument constraint is not satisfied + // warning: Function argument outside of allowed range (void)ret; } @@ -2456,24 +2456,25 @@ If the user disables the checker then the argument violation warning is suppressed. However, the assumption about the argument is still modeled. This is because exploring an execution path that already contains undefined behavior -is not valuable. +is not valuable. This applies to all the restrictions that are listed below. -There are different kind of constraints modeled: range constraint, not null -constraint, buffer size constraint. A **range constraint** requires the -argument's value to be in a specific range, see ``isalnum`` as an example above. -A **not null constraint** requires the pointer argument to be non-null. - -A **buffer size** constraint specifies the minimum size of the buffer -argument. The size might be a known constant. For example, ``asctime_r`` requires -that the buffer argument's size must be greater than or equal to ``26`` bytes. In -other cases, the size is denoted by another argument or as a multiplication of -two arguments. -For instance, ``size_t fread(void *ptr, size_t size, size_t nmemb, FILE *stream)``. -Here, ``ptr`` is the buffer, and its minimum size is ``size * nmemb`` +There may be different restrictions about values passed as function arguments. + - The argument has an allowed range (or multiple ranges) of values. The checker + can detect if a passed value is outside of the allowed range and show the + actual and allowed values. + - The argument has pointer type and is not allowed to be null pointer. Many + (but not all) standard functions can produce undefined behavior if a null + pointer is passed, these cases can be detected by the checker. + - The argument is a pointer to a memory block and the minimal size of this + buffer is determined by another argument to the function, or by + multiplication of two arguments (like at function ``fread``), or is a fixed + value (for example ``asctime_r`` requires at least a buffer of size 26). The + checker can detect if the buffer size is too small and in optimal case show + the size of the buffer and the values of the corresponding arguments. .. code-block:: c - void buffer_size_constraint_violation(FILE *file) { + void buffer_size_violation(FILE *file) { enum { BUFFER_SIZE = 1024 }; wchar_t wbuf[BUFFER_SIZE]; @@ -2486,22 +2487,62 @@ fread(wbuf, size, nitems, file); } +**List of checked functions** + +``fgetc``, ``fread``, ``fwrite``, ``getc``, ``getchar``, ``getdelim``, +``getenv``, ``getline``, ``isalnum``, ``isalpha``, ``isascii``, ``isblank``, +``isdigit``, ``isgraph``, ``islower``, ``isprint``, ``ispunct``, ``isspace``, +``isupper``, ``isxdigit``, ``read``, ``toascii``, ``tolower``, ``toupper``, +``write`` + +Additional functions in POSIX mode (see Parameters below): + +``a64l``, ``accept``, ``access``, ``alarm``, ``asctime_r``, ``bind``, ``chdir``, +``chmod``, ``chown``, ``clock_gettime``, ``close``, ``closedir``, ``connect``, +``creat``, ``ctime_r``, ``dirfd``, ``dup``, ``dup2``, ``execv``, ``execvp``, +``faccessat``, ``fchmod``, ``fchmodat``, ``fchown``, ``fchownat``, ``fclose``, +``fdatasync``, ``fdopen``, ``fdopendir``, ``fileno``, ``fileno``, ``fnmatch``, +``fopen``, ``fpathconf``, ``freopen``, ``fseek``, ``fseeko``, ``fstat``, +``fstatat``, ``fsync``, ``ftello``, ``futimens``, ``getcwd``, ``getitimer``, +``getnameinfo``, ``getopt``, ``getpeername``, ``getsockname``, ``getsockopt``, +``gmtime``, ``gmtime_r``, ``isatty``, ``l64a``, ``lchown``, ``link``, +``linkat``, ``listen``, ``localtime``, ``localtime_r``, ``lockf``, ``lseek``, +``lstat``, ``mkdir``, ``mkdirat``, ``mkdtemp``, ``mknod``, ``mknodat``, +``mkstemp``, ``mmap``, ``mmap64``, ``nanosleep``, ``opendir``, ``pathconf``, +``pclose``, ``pipe``, ``popen``, ``pthread_attr_destroy``, +``pthread_attr_getguardsize``, ``pthread_attr_getstacksize``, +``pthread_attr_init``, ``pthread_attr_setguardsize``, +``pthread_attr_setstacksize``, ``pthread_cond_broadcast``, +``pthread_cond_signal``, ``pthread_create``, ``pthread_mutex_destroy``, +``pthread_mutex_init``, ``pthread_mutex_lock``, ``pthread_mutex_trylock``, +``pthread_mutex_unlock``, ``rand_r``, ``readlink``, ``readlinkat``, +``realpath``, ``recv``, ``recvfrom``, ``recvmsg``, ``renameat``, +``rewinddir``, ``rmdir``, ``seekdir``, ``send``, ``sendmsg``, ``sendto``, +``setsockopt``, ``sleep``, ``socketpair``, ``stat``, ``strdup``, ``strndup``, +``symlink``, ``symlinkat``, ``tmpfile``, ``truncate``, ``unlink``, ``unlinkat``, +``utime``, ``utimensat``, ``utimes``, ``wcsdup`` + **Limitations** -The checker is in alpha because the reports cannot provide notes about the -values of the arguments. Without this information it is hard to confirm if the -constraint is indeed violated. For example, consider the above case for -``fread``. We display in the warning message that the size of the 1st arg -should be equal to or less than the value of the 2nd arg times the 3rd arg. -However, we fail to display the concrete values (``4`` and ``4096``) for those -arguments. +The checker can not always provide notes about the values of the arguments. +Without this information it is hard to confirm if the constraint is indeed +violated. The argument values are shown if they are known constants or the value +is determined by previous (not too complicated) assumptions. + +The checker can produce false positives in cases such as if the program has +invariants not known to the analyzer engine or the bug report path contains +calls to unknown functions. In these cases the analyzer fails to detect the real +range of the argument. **Parameters** The checker models functions (and emits diagnostics) from the C standard by -default. The ``ModelPOSIX`` option enables the checker to model (and emit -diagnostics) for functions that are defined in the POSIX standard. This option -is disabled by default. +default. The ``apiModeling.StdCLibraryFunctions:ModelPOSIX`` option enables +modeling (and emit diagnostics) of additional functions that are defined in the +POSIX standard. This option is disabled by default. Note that this option +belongs to a separate built-in checker ``apiModeling.StdCLibraryFunctions`` and +can have effect on other checkers because it toggles modeling of the functions +in various aspects. .. _alpha-unix-BlockInCriticalSection: