How do I return an error from a boolean function in C?

Question

I'm working on a little pet program in C where I have a game board that consists of a bunch of squares:

typedef struct _square {
    bool checked;
} Square;

typedef struct _board {
    Square *squares;
    uint8_t width;
    uint8_t height;
} Board;

I don't want these structs to be visible to the public, so instead I want to write a simple function that checks if a square is checked or not, called square_is_checked. It makes sense for the return type to be a bool (I'm assuming C99 here).

bool square_is_checked(Board *b, uint8_t row, uint8_t col)
{
    return b->squares[(uint16_t)row * b->height + col].checked;
}

However, it's possible that a NULL pointer, or a row and column that don't exist could be passed as arguments. So I want to add some simple checks:

bool square_is_checked(Board *b, uint8_t row, uint8_t col)
{
    if (!b) { return ???; }
    if (row >= b->height || col >= b->width) { return ???; }
    return b->squares[(uint16_t)row * b->height + col].checked;
}

However, a bool is either true or false -- no room for error management. What's considered best practice here (e.g., do I have to rewrite this function to pass a pointer to a bool)?

Answer 1

This isn't really about how to return bool from a function in C. Your code already does that.

The question really is, is bool the right data type when the set of possible values is larger than true and false. That could be the subject of a lengthy philosophical discussion, but as this is a personal project, you don't need to worry about your decision within a larger context. On a team, where existing code might already have an opinion on situations like this, a decision might be made for you.

So in this case, there are many couple possible answers. A few options:

• Keep the bool return type, and use false for input errors such as null pointers or invalid values (row > height, etc.)
• Use an enum to represent CHECKED, UNCHECKED, UNKNOWN etc. instead of a boolean. Many C libraries effectively do this by returning 0 (e.g. INVALID_SOCKET) to indicate an error (or sometimes -1).
• Validate the inputs elsewhere to ensure that this function can always correctly return a meaningful boolean when called.

Answer 2

Some other options include passing in a pointer to a bool and returning an error value. Something like this:

typedef enum square_err_t {
    ERROR_NONE = 0,
    ERROR_BAD_PTR,
    ERROR_BAD_ROW,
    ERROR_BAD_COL
} square_err_t;

square_err_t square_is_checked(Board* b, uint8_t row, uint8_t col, bool* is_checked)
{
    ...
}

Since this is a personal project, you might be able to get away with doing your checks as preconditions via assert:

bool square_is_checked(Board* b, uint8_t row, uint8_t col)
{
    assert(b != NULL);
    assert(col < b->width);
    assert(row < b->height);
    ...etc.
}

This will catch errors during development, but the checks will be compiled out in release.

If your compiler or other tooling supports it, you might be able to annotate your functions with nullability annotations. (That example is for Swift, but a quick search shows tools that support them available for other languages, too.) These allow you to mark arguments to a function as nonnull, meaning the argument is not allowed to be NULL. This will catch some potential calls at compile time rather than runtime and let you fix them before you ship.

Answer 3

There is a fundamental decision for you to make:

Is an invalid input a violation of the contract, or expected?

You already depend on the caller to give a pointer to a Board, and the right one at that. Why do you want to special-case the invalid input NULL, aren't that all logic-errors by the programmer?

An out-of-range board-position can be argued about much more:

1. Is it a logic-error committed by the programmer?
2. Is it user-input failing validation?
3. Is there a logical continuation of the given board?

There are three ways to react to logic-errors:

1. Panic. assert() in debug-builds (be generous with assert, as it is a no-op in release), abort() in release. Depending on the severity of the error, in moderately safe languages with exceptions throwing an unchecked exception might qualify.
2. Let the dice fall where they will. That's what Undefined Behavior means, and allows by far for the highest efficiency.
3. Try to substitute sensible defaults and muddle through or return an error. In languages with exceptions, exceptions might be the way you return an error.

Answer 4

Maybe take a look at   man errno   and use one of the two strategies discussed there. Either   int square_is_checked(etc)   and   return -1   for errors, or else set   errno   to signal errors, as discussed by the man page. (Personally, I usually go with the -1 in these kinds of situations. You can use int just as well as your bool.)