[Analyzer] Add docs to StdCLibraryFunctionArgsChecker

[NoQ]

clang/docs/analyzer/checkers.rst

2401

I recommend against using clang_analyzer_eval in user docs. Users aren't expected to know what it is.

2406

Nitpick: the program doesn't become ill-formed just because the user has turned off the checker. Maybe it's better to say that exploring an execution path that already contains undefined behavior is not valuable, or something along those lines(?)

[steakhal]

I like it. Terse but complete.
I think you could polish the example code to look less synthetic.

[dkrupp]

clang/docs/analyzer/checkers.rst

2411

I think it would be useful for the user to see one example per constraint type that this checker supports.
RangeConstraint (was covered), ComparisonConstraint, ValueConstraint, Not null Constraint, BufferSize constraint etc.

It would be also nice to add a section "Limitations".

Describe there well known false positive cases or limitations in the bug diagnostics that limits understandability.
Essentially the most important well known cases why this checker is alpha.

This section would be useful for users to understand and help identifying cases that are known false positives and for the developers to know how to improve this checker. I remember many cases when we had to test multiple times "why a checker is in alpha", because we forgot about it. I think it is best to document it.

[martong]

• Describe the different kind of constraints and limitations
• Some rewording

clang/docs/analyzer/checkers.rst

2401

Ok, I've changed to have an infeasible branch condition and below that an unreported div zero warning demonstrates the same.

2406

Ok, I've changed the wording.

2411

Ok, I've added a few paragraphs to describe these things.

[steakhal]

Looks great.

clang/docs/analyzer/checkers.rst

 External taint configuration is in `YAML <http://llvm.org/docs/YamlIO.html#introduction-to-yaml>`_ format. The taint-related options defined in the config file extend but do not override the built-in sources, rules, sinks.
 The format of the external taint configuration file is not stable, and could change without any notice even in a non-backward compatible way.
 
 For a more detailed description of configuration options, please see the :doc:`user-docs/TaintAnalysisConfiguration`. For an example see :ref:`clangsa-taint-configuration-example`.
 
 alpha.unix
 ^^^^^^^^^^^
 
+.. _alpha-unix-StdCLibraryFunctionArgs:
+
+alpha.unix.StdCLibraryFunctionArgs (C)
+""""""""""""""""""""""""""""""""""""""
+Check for calls of standard library functions that violate predefined argument
+constraints. For example, it is stated in the C standard that for the ``int
+isalnum(int ch)`` function the behavior is undefined if the value of ``ch`` is
+not representable as unsigned char and is not equal to ``EOF``.
+
+.. code-block:: c
+
+  void test_alnum_concrete(int v) {
+    int ret = isalnum(256); // \
+    // warning: Function argument constraint is not satisfied
+    (void)ret;
+  }
+
+If the argument's value is unknown then the value is assumed to hold the proper value range.
+
+.. code-block:: c
+
+  #define EOF -1
+  int test_alnum_symbolic(int x) {
+    int ret = isalnum(x);
+    // after the call, ret is assumed to be in the range [-1, 255]
+
+    if (ret > 255)      // impossible (infeasible branch)
+      if (x == 0)
+        return ret / x; // division by zero is not reported
+    return ret;
+  }
+
+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.
+
+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``
+
+.. code-block:: c
+
+  void buffer_size_constraint_violation(FILE *file) {
+    enum { BUFFER_SIZE = 1024 };
+    wchar_t wbuf[BUFFER_SIZE];
+
+    const size_t size = sizeof(*wbuf);   // 4
+    const size_t nitems = sizeof(wbuf);  // 4096
+
+    // Below we receive a warning because the 3rd parameter should be the
+    // number of elements to read, not the size in bytes. This case is a known
+    // vulnerability described by the the ARR38-C SEI-CERT rule.
+    fread(wbuf, size, nitems, file);
+  }
+
+**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.
+
+**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.
+
 .. _alpha-unix-BlockInCriticalSection:
 
 alpha.unix.BlockInCriticalSection (C)
 """""""""""""""""""""""""""""""""""""
 Check for calls to blocking functions inside a critical section.
 Applies to: ``lock, unlock, sleep, getc, fgets, read, recv, pthread_mutex_lock,``
 `` pthread_mutex_unlock, mtx_lock, mtx_timedlock, mtx_trylock, mtx_unlock, lock_guard, unique_lock``
 

clang/include/clang/StaticAnalyzer/Checkers/Checkers.td

def BlockInCriticalSectionChecker : Checker<"BlockInCriticalSection">,
   Documentation<HasAlphaDocumentation>;
 
 def StdCLibraryFunctionArgsChecker : Checker<"StdCLibraryFunctionArgs">,
   HelpText<"Check constraints of arguments of C standard library functions, "
            "such as whether the parameter of isalpha is in the range [0, 255] "
            "or is EOF.">,
   Dependencies<[StdCLibraryFunctionsChecker]>,
   WeakDependencies<[CallAndMessageChecker, NonNullParamChecker, StreamChecker]>,
-  Documentation<NotDocumented>;
+  Documentation<HasAlphaDocumentation>;
 
 } // end "alpha.unix"
 
 //===----------------------------------------------------------------------===//
 // C++ checkers.
 //===----------------------------------------------------------------------===//
 
 let ParentPackage = Cplusplus in {