== Why is this an issue?

Many functions in the standard C libraries are not required by the ISO/IEC 9899:1990 standard to check the validity of parameters passed to them. Even where checking is required by the standard, or where compiler writers claim to check parameters, there is no guarantee that adequate checking will take place.


Therefore the programmer shall provide appropriate checks of input values for all library functions which have a restricted input domain (standard libraries, other bought-in libraries, and in-house libraries).


Examples of functions that have a restricted domain and need checking are:

* many of the maths functions in ``++math.h++``, for example:
** negative numbers must not be passed to the ``++sqrt++`` or ``++log++`` functions;
** the second parameter of ``++fmod++`` should not be zero
* ``++toupper++`` and ``++tolower++``: some implementations can produce unexpected results when the function ``++toupper++`` is passed a parameter which is not a lower case letter (and similarly for ``++tolower++``)
* the character testing functions in ``++ctype.h++`` exhibit undefined behaviour if passed invalid values
* the ``++abs++`` function applied to the most negative integer gives undefined behaviour

Although most of the math library functions in ``++math.h++`` define allowed input domains, the values they return when a domain error occurs may vary from one compiler to another. Therefore pre-checking the validity of the input values is particularly important for these functions.


The programmer should identify any domain constraints which should sensibly apply to a function being used (which may or may not be documented in the standard), and provide appropriate checks that the input value(s) lies within this domain. Of course the value may be restricted further, if required, by knowledge of what the parameter represents and what constitutes a sensible range of values for the


There are a number of ways in which the requirements of this rule might be satisfied, including the following:

* Check the values before calling the function
* Design checks into the function. This is particularly applicable for in-house designed libraries, though it could apply to bought-in libraries if the supplier can demonstrate that they have built in the checks
* Produce “wrapped” versions of functions, that perform the checks then call the original function
* Demonstrate statically that the input parameters can never take invalid values

Note that when checking a floating-point parameter to a function, that has a singularity at zero, it may be appropriate to perform a test of equality to zero. This is an acceptable exception to MISRA C:2004 Rule 13.3 without the need to raise a deviation. However it will usually still be necessary to test to a tolerance around zero (or any other singularity) if the magnitude of the value of the function tends to infinity as the parameter tends to zero, so as to prevent overflow occurring.

== Resources

* MISRA C:2004, 20.3
* MISRA C:2004, 13.3
* ISO/IEC 9899:1990

ifdef::env-github,rspecator-view[]
'''
== Comments And Links
(visible only on this page)

=== on 23 Oct 2014, 14:20:39 Samuel Mercier wrote:
The description gives already some cases but we need to further define what we want to check.

=== on 23 Oct 2014, 16:04:05 Ann Campbell wrote:
Given the requirement to check params to non-standard ("brought-in") libraries and in-house libraries, I don't see this as being implementable as a single rule unless it's a very complex template rule. I see this more as a job for CFG & the multitude of rules that will be implemented with it.

endif::env-github,rspecator-view[]
