Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 46

Designing Safer APIs with `const` Parameters

Recommended resources

Hello! Let's dive into the next lesson in our module on Type Qualifiers.

In our previous session, we established the fundamental difference between a 'pointer to const data' (const int *p) and a 'const pointer' (int * const p). You learned to read these declarations and understand what is and isn't allowed for each type. This distinction is the foundation for today's topic.

Our learning outcome is to apply const correctness to function parameters to create safer, more readable APIs. We're moving from theory to practice, exploring how const acts as a crucial communication tool between a function and its caller. This is not just an academic exercise; it is a cornerstone of defensive programming, directly contributing to the robustness and safety requirements mandated by standards like ISO 26262 and MISRA-C that are central to your work in automotive software.

The const Promise: A Contract for Your Code

Before we get into the syntax, it's important to understand the philosophy behind const correctness. When you use const in a function signature, you are making a promise—a contract—to the caller. You are stating your function's intentions explicitly.

To get a quick overview of this philosophy, please watch this short segment. While it mentions C++, the core ideas about const as a promise and its role in creating safer, more readable code are identical in C.

CONSTANTS in C++

The video 'CONSTANTS in C++' from cazz explains why the const keyword is so important for programmers.

Please watch from 00:40 to 02:37. Focus on the idea that const is a promise to the compiler and to other programmers, making your intentions clear and your code safer.

As the video highlighted, const exists for the programmer. It allows the compiler to act as your safety net, catching mistakes where you might accidentally modify data that should have remained unchanged.

Protecting Function Arguments with const

In C, arguments are passed by value. For a pointer, this means the function receives a copy of the pointer. Changing the pointer itself inside the function (e.g., making it point to a different address) won't affect the original pointer in the calling function.

The real issue arises when you dereference the pointer. Without const, a function has the power to modify the caller's original data, which can lead to dangerous, unintended side effects. const correctness is our primary tool to prevent this.

Let's explore this with a practical guide.

Mead's Guide to const in C and C++

The following resource, 'Mead's Guide to const in C and C++', provides an excellent, practical comparison between a function that uses const and one that doesn't.

Please read the section titled 'Protecting Function Arguments (C and C++)'. Pay close attention to the side-by-side 'Unsafe' vs. 'Safe' examples for the find_largest function. Note how the 'Safe' version (find_largest2) cannot accidentally modify the array and can be called with const data.

Let's summarize the key insights from that reading:

  1. The Contract:

    • void func(int *p); implies a contract: "I may modify the data you pass me."
    • void func(const int *p); implies a contract: "I will not modify the data you pass me; I only need to read it."

  2. Compiler Enforcement: The "safe" version, find_largest2(const int a[], int size), provides a compile-time guarantee. If a programmer later tries to add a line like a[0] = 0; inside that function, the compiler will immediately flag it as an error because a points to const data. This prevents bugs before they happen.

  3. Flexibility: The "safe" function is more versatile.

    • It can accept a non-constant array: int b[] = { ... }; find_largest2(b, 8); (OK)
    • It can also accept a constant array: const int a[] = { ... }; find_largest2(a, 8); (OK)

    The "unsafe" function, find_largest1(int a[], int size), can only accept non-constant arrays. Calling it with a would produce a compiler warning or error because it would require casting away the const qualification—a dangerous practice.

A Real-World API Example: strcat

This principle is used throughout the C standard library. A classic example is the strcat function, which concatenates two strings.

char *strcat(char *dest, const char *src);

  • dest: The destination buffer. It is not const because strcat's entire purpose is to modify it by appending characters.
  • src: The source string. It is const because strcat only needs to read from it. It promises not to change the source string.

This use of const makes the API's behavior perfectly clear and safe. The SEI CERT C Coding Standard, a set of rules for secure C programming highly relevant in safety-critical domains, has a specific rule for this.

DCL13-C. Declare function parameters that are pointers ... as const

Let's examine the official recommendation from the SEI CERT C Coding Standard. This resource shows the problems that arise when an API is not const-correct.

Please read the sections from the first 'Noncompliant Code Example' (which modifies '*x') through the 'Compliant Solution' that shows the proper strcat prototype. Pay special attention to the fictional strcat_nc() example and the analysis of why its calls lead to warnings or dangerous behavior.

The strcat_nc(char *s1, char *s2) example from the reading is a powerful illustration of poor API design:

  • strcat_nc(c_str3, c_str2); where c_str2 is const: The compiler correctly warns you that you are passing a const argument to a function that expects a non-const one. The API forced you into a potentially unsafe situation.
  • strcat_nc(c_str1, c_str3); where c_str1 is a string literal: This is the most dangerous case. The compiler might not warn you, but at runtime, your program will attempt to modify a string literal, which results in undefined behavior (often a crash). The lack of const in the function signature created a hidden trap.

The compliant strcat signature avoids all of this. It correctly documents its intent, allowing the compiler to be your ally in catching errors. In your work with AUTOSAR interfaces, where software components exchange data, this principle is paramount. If a component's runnable is only supposed to read data from a port, its API should reflect that by accepting a pointer to const.

Test your understanding!

For each function prototype below, decide which pointer parameters, if any, should be declared const. Your goal is to make the API as safe and clear as possible.

  1. A function that calculates a checksum over a data buffer.
    uint32_t calculate_crc(uint8_t *data, size_t length);

  2. A function that copies a source string to a destination buffer.
    void string_copy(char *dest, char *src);

  3. A function that searches for a byte within a buffer and returns a pointer to the first occurrence.
    uint8_t* find_byte(uint8_t *buffer, size_t length, uint8_t byte_to_find);

  4. A function that swaps the values of two integers.
    void swap_integers(int *a, int *b);

Show answer

  1. Correct: uint32_t calculate_crc(const uint8_t *data, size_t length);

    • Reasoning: The function only needs to read the data to calculate the CRC; it should not modify the buffer.

  2. Correct: void string_copy(char *dest, const char *src);

    • Reasoning: The function modifies the dest buffer but only reads from the src string. This mirrors the standard strcpy function.

  3. Correct: const uint8_t* find_byte(const uint8_t *buffer, size_t length, uint8_t byte_to_find);

    • Reasoning: The function only needs to read the buffer to search for the byte. The return type should also be const uint8_t*. This prevents the caller from using the returned pointer to modify the contents of the original buffer, which is a good defensive practice. (Returning a uint8_t* would also be valid, but returning a pointer-to-const is safer.)

  4. Correct: void swap_integers(int *a, int *b);

    • Reasoning: The entire purpose of this function is to modify the values pointed to by a and b. Therefore, neither should be const.

Conclusion

Today we've seen that const correctness is a fundamental aspect of professional C programming. It's a simple yet powerful feature that transforms a function's signature from a simple name into a self-documenting contract that the compiler can enforce.

Key Takeaways:

  • const is a Contract: Using const on pointer parameters declares a function's intent: "I will not change this data."
  • Improves Safety: It allows the compiler to catch accidental modifications of data, preventing a whole class of bugs.
  • Increases Readability: It makes APIs easier to understand and use correctly. Anyone can see which parameters are for input and which are for output.
  • Enhances Flexibility: A function that accepts a const pointer can be called with both const and non-const variables, making it more versatile.

Preview of the Next Lesson:
We've focused on how to apply const and the immediate safety benefits. In the next lesson, we will formalize this by explaining the broader benefits of const correctness for code safety and even compiler optimization. We will also touch upon another important qualifier, volatile, which is critical when interacting with hardware in an embedded context.