MISRA-C:2004  Rule  20.3:  (Required)			The validity of values passed to library functions shall be checked.

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 parameter.

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 will require a deviation to Rule . 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.

Example Code:

/* PRQA S 3205 ++ */

#include <stdio.h>                      /* MISRA Violation */
#include <string.h>                     /* MISRA Violation */
#include "misra.h"
#include "m2cmex.h"

extern S16 test_2003( void )
{
   PC   buf[5];
   PC  *str1 = NULL;
   PC  *str2 = "Reaction %d";

   (void)printf(str1, 10);              /* MISRA Violation */

   (void)memcpy(buf, str2, 11u);        /* MISRA Violation */

   return 1;
}

QAC messages that encompass this guideline:

2810	Constant: Dereference of NULL pointer.
2811	Definite: Dereference of NULL pointer.
2812	Apparent: Dereference of NULL pointer.
2840	Constant: Dereference of an invalid pointer value.
2841	Definite: Dereference of an invalid pointer value.
2842	Apparent: Dereference of an invalid pointer value.

Related rules:

Rule  1.2	No reliance shall be placed on undefined or unspecified behaviour.
Rule  21.1	Minimisation of run-time failures shall be ensured by the use of at least one of (a) static analysis tools/techniques; (b) dynamic analysis tools/techniques; (c) explicit coding of checks to handle run-time faults

(c) The Motor Industry Research Association, 2004

QA C Source Code Analyser 8.1.2 MISRA-C:2004 Compliance Module 3.2 © 2013 Programming Research www.programmingresearch.com

Personality Groups | Glossary | Message Index | MISRA-C:2004 Rule Index

Contents