bsearch(), memchr(), strchr(), strpbrk(), strrchr() and strstr() all
accept a const pointer/object but return a non-const pointer to the
matched element or byte, matching their standard C library interfaces.
The casts in these implementations strip const so that callers searching
a non-const object get back a mutable pointer. Avoiding the casts would
require deviating from the standard C library prototypes of these
functions, so document these uses as deviations instead.

Update docs/misra/rules.rst to note that this class of double-use
library functions is deviated on a per-function basis.

Signed-off-by: Dmytro Prokopchuk <dmytro_prokopchuk1@epam.com>
Acked-by: Jan Beulich <jbeulich@suse.com>
Reviewed-by: Nicola Vetrini <nicola.vetrini@bugseng.com> # automation/eclair_analysis/.*
---
Changes in v3:
- reword "public API" in the commit message to refer to the standard C
  library prototypes instead
- fold strchr and strrchr into str+chr in the ECLAIR config
- add Acked-by and Reviewed-by tags

Test CI pipeline:
https://gitlab.com/xen-project/people/dimaprkp4k/xen/-/pipelines/3017261694
---
 automation/eclair_analysis/ECLAIR/deviations.ecl | 8 ++++++++
 docs/misra/deviations.rst                        | 9 +++++++++
 docs/misra/rules.rst                             | 6 +++++-
 3 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/automation/eclair_analysis/ECLAIR/deviations.ecl b/automation/eclair_analysis/ECLAIR/deviations.ecl
index c7a800c62f..296340bb4c 100644
--- a/automation/eclair_analysis/ECLAIR/deviations.ecl
+++ b/automation/eclair_analysis/ECLAIR/deviations.ecl
@@ -451,6 +451,14 @@ write or not"
 -config=MC3A2.R11.8,reports+={safe,"any_area(any_loc(file(hvm_guestcopy)&&text(^.*__hvm_copy.*HVMCOPY_to_guest doesn't modify.*$)))"}
 -doc_end
 
+-doc_begin="Functions bsearch(), memchr(), strchr(), strpbrk(), strrchr() and
+strstr() accept a const pointer/object and return a non-const pointer to the
+matched element or byte, matching their standard C library interfaces. The
+casts in these implementations strip const so that a search of a non-const
+object yields a mutable pointer. This use is deemed safe."
+-config=MC3A2.R11.8,reports+={safe,"any_area(any_loc(file(^xen/include/xen/bsearch\\.h$||^xen/lib/(memchr|str+chr|strpbrk|strstr)\\.c$)))"}
+-doc_end
+
 -doc_begin="This construct is used to check if the type is scalar, and for this purpose the use of 0 as a null pointer constant is deliberate."
 -config=MC3A2.R11.9,reports+={deliberate, "any_area(any_loc(any_exp(macro(^__ACCESS_ONCE$))))"
 }
diff --git a/docs/misra/deviations.rst b/docs/misra/deviations.rst
index 76be6b3251..bee4686675 100644
--- a/docs/misra/deviations.rst
+++ b/docs/misra/deviations.rst
@@ -440,6 +440,15 @@ Deviations related to MISRA C:2012 Rules:
        readability.
      - Tagged as `safe` for ECLAIR.
 
+   * - R11.8
+     - Functions bsearch(), memchr(), strchr(), strpbrk(), strrchr() and
+       strstr() accept a const pointer/object and return a non-const pointer
+       to the matched element or byte, matching their standard C library
+       interfaces. The casts in these implementations strip const so that a
+       search of a non-const object yields a mutable pointer. This use is
+       deemed safe.
+     - Tagged as `safe` for ECLAIR.
+
    * - R11.9
      - __ACCESS_ONCE uses an integer, which happens to be zero, as a
        compile time check. The typecheck uses a cast. The usage of zero or other
diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
index 5f9fe4c860..7e191a0d4a 100644
--- a/docs/misra/rules.rst
+++ b/docs/misra/rules.rst
@@ -475,7 +475,11 @@ maintainers if you want to suggest a change.
    * - `Rule 11.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_08.c>`_
      - Required
      - A cast shall not remove any const or volatile qualification from the type pointed to by a pointer
-     -
+     - Some standard C library-style functions are inherently double-use,
+       accepting a const argument and returning a non-const pointer into
+       it so that callers searching a non-const object get back a
+       mutable pointer. The casts that implement this are deviated per
+       function.
 
    * - `Rule 11.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_09.c>`_
      - Required
-- 
2.43.0