Related functions, such as those that make up a library, should provide consistent and usable interfaces. Ralph Waldo Emerson might have said, "A foolish consistency is the hobgoblin of little minds," but inconsistencies in functional interfaces or behavior can lead to erroneous use so we understand this to be a "wise consistency". One aspect of providing a consistent interface is to provide a consistent and usable error checking mechanism API04-C. Provide a consistent and usable error checking mechanism.
Noncompliant Code Example (interface)
It is not necessary to go beyond the standard C library to find examples of inconsistent interfaces. This is because the standard library is a fusion of multiple different libraries with various styles and various levels of rigor.
For example, the fputs() defined in §7.19.7 is closely related to the fprintf() defined in §7.19.6. However, the fputs() has the file handle at the end and fprintf() at the beginning as shown by their function declarations.
int fputs(const char * restrict s, FILE * restrict stream); int fprintf(FILE * restrict stream, const char * restrict format, ...);
The argument order can be easily rearranged using macros, for example:
#include <stdio.h> #define fputs(X,Y) fputs(Y,X)
However, this makes the code difficult to read, for example, by causing confusion when moving between code that follows this convention and code that does not. In effect, it becomes impossible to modify an interface once that interface has been broadly adopted. Consequently, it is important to get the interface design right the first time.
Compliant Solution (interface)
The managed string library [[Burch 06]] tries to be as consistent as possible, both internally, and with established conventions from the C standard library. For example, functions that operate on a single instance of a string_m, but do modify the contents of the managed string, follow the pattern:
errno_t strlen_m(const string_m s, rsize_t *size); errno_t isnull_m(const string_m s, _Bool *nullstr); errno_t cgetstr_m(const string_m s, char **string);
where the first argument is declared as const string_m. For functions that implement a data abstraction (see DCL12-C. Implement abstract data types using opaque types), it is reasonable to define the handle for the data abstraction as the initial parameter.
Noncompliant Code Example (behavior)
The shared folder and file copy functions in the VMware virtual infrastructure (VIX) API are inconsistent in the set of characters they allow in folder names. As a result, you can create a shared folder that you subsequently can't use in a file copy function such as VixVM_CopyFileFromHostToGuest().
Compliant Solution (behavior)
Try to be consistent in the behavior of related functions that perform operations on common objects, so that an object created or modified by one function can be successfully processed by a downstream invocation of a related function.
Risk Assessment
Failure to do so can result in type errors in the program.
Rule |
Severity |
Likelihood |
Remediation Cost |
Priority |
Level |
|---|---|---|---|---|---|
API04-C |
medium |
unlikely |
medium |
P2 |
L3 |
Related Vulnerabilities
Search for vulnerabilities resulting from the violation of this rule on the CERT website.
Other Languages
This rule appears in the C++ Secure Coding Standard as cplusplus:API04-CPP. Provide a consistent and usable error checking mechanism.
References
VMware 07 VIX API Version 1.1.1 (for Workstation 6.0.1) Release Notes. 16-August-2007
[[Burch 06]]
[[CERT 06c]]
[[ISO/IEC 9945:2003]]
[[ISO/IEC 9899:1999]] Section 7.21, "String handling <string.h>"
[[ISO/IEC 23360-1:2006]]
[[ISO/IEC TR 24731-1:2007]]
[[ISO/IEC PDTR 24731-2]]
[[Miller 99]]
[[MISRA 04]] Rule 20.4
[[Seacord 05a]] Chapter 2, "Strings"
APP00-C. Functions should validate their parameters 13. Application Programming Interfaces (API) API04-C. Provide a consistent and usable error checking mechanism