RTOS C Library Reentrancy: errno, stdio Locks and Per-Task State

Treat the C library as another concurrent subsystem

An RTOS application can protect every driver and still corrupt its heap or report the wrong error because two tasks enter the C library concurrently. The library is not a single object with one universal “thread-safe” switch. It contains per-thread state, shared streams, shared allocation machinery, and low-level platform hooks. Review these separately before deciding that enabling newlib support has solved concurrency.

This guide uses the FreeRTOS Kernel V11.1.0 integration with newlib as a concrete example. The deployed compiler, newlib or newlib-nano build, vendor patches, and link options must still be recorded. Other C runtimes may use different thread-local mechanisms and lock interfaces. The pinned FreeRTOS newlib integration explicitly separates its per-task reentrancy support from the application’s responsibility to provide necessary system stubs and allocator locking.

Distinguish reentrancy from shared-resource protection

A routine is reentrant when an interrupted invocation can safely coexist with another invocation under its documented conditions. Thread safety may instead rely on locking, which can make a routine unsuitable for an interrupt or for a path that already owns a related lock. Functions with caller-provided state can avoid one global variable while still calling a shared allocator internally. Read the entire call path, not only the function name or a suffix.

Build an inventory of the actual operations used: numeric conversion, formatted output, dynamic allocation, file access, locale handling, and multibyte conversion. For each operation, write down the state it touches, whether that state is task-local, and which lock protects any shared part. Include failure paths and diagnostics. An error handler that calls printf() may reenter precisely the subsystem whose lock is already held when the error occurs.

Follow errno to the actual storage

Do not redeclare errno as a global variable in application code. Include the supplied errno.h and inspect how the selected runtime resolves its access. Newlib supports reentrancy structures and interfaces that receive an explicit reentrancy pointer; the newlib manual describes how this interacts with platform system-call stubs. Verify that the stubs and normal library calls agree on the active task’s state.

In V11.1.0, configUSE_NEWLIB_REENTRANT enables runtime-TLS hooks that initialize a struct _reent, select it through _impure_ptr, and reclaim associated state during task cleanup. That describes this integration, not a portable recipe for every SMP configuration. Also remember that successful library calls do not universally clear errno. Capture the relevant error immediately after a documented failure and before logging or another library operation can change it.

Audit malloc and stdio independently

Per-task reentrancy state does not create a separate heap for every task. Newlib’s documented __malloc_lock() and __malloc_unlock() hooks protect the shared allocation pool, and their implementation must tolerate recursive acquisition as required by that allocator. Confirm which lock symbols the linked library actually uses. A symbol present in an example source file proves little if the linker chose a different object or a no-op implementation.

Inspect the map file and, where necessary, disassembly or symbol references for the allocator and stream-lock paths. Distinguish FreeRTOS heap functions from libc malloc(): an application can accidentally operate two heaps with different protection. Decide whether one owner task serializes output or whether multiple tasks may use independent or shared FILE streams. Thread-safe stream internals do not promise that several separate printf() calls from one task form an indivisible log record. Assemble a bounded record first if that is the required interface.

Make startup, interrupts and shutdown explicit

An RTOS mutex wrapper may be invalid before the scheduler starts, and a blocking lock is inappropriate in an ISR. Define what the library may do during early initialization, after scheduler startup, in fault handling, and while a task is being deleted. Avoid using formatted output from a lock implementation or from an allocator failure path that might allocate again. A minimal emergency output path should have a separately reviewed contract.

For task deletion, account for runtime-owned allocations and the selected reentrancy cleanup hook. Do not delete a task while it owns a stream or allocator lock and expect the kernel to unwind the library. If library operations cannot be interrupted safely, establish a cooperative shutdown point after those calls return. In a multicore product, verify that both the runtime’s current-thread selection and the locking primitives actually support simultaneous execution on separate cores.

Test failures as well as successful output

A useful proposed test uses two tasks synchronized around independent conversion failures. Each sets up its own input, triggers a documented error, yields at a controlled point, and records its own error value before calling any diagnostic formatter. Use results appropriate to the chosen library and inspect both the returned value and errno. The goal is to detect cross-task state contamination, not to assume every function sets an error on every invalid string.

Run allocation and deallocation from competing tasks with ownership tracking and canaries in a development build. Exercise stream errors, allocation failures, recursive lock acquisition, scheduler-not-running paths, and orderly task shutdown. Record which lock implementation was linked and count balanced lock/unlock operations without logging from inside those locks. Compare a single-owner logging design with the multi-caller design if the product permits both. These are suggested validation steps; no toolchain binary or board workload was executed for this article.

Acceptance checklist

• Compiler, runtime variant, library version and relevant link options are reproducible.
• errno and other task-local state resolve to the intended task instance.
• Shared allocator and stream locks are identified in the linked image.
• Recursive acquisition, startup and ISR restrictions are documented.
• Diagnostic paths cannot recursively depend on a failed or already locked service.
• Shutdown waits for a library-safe boundary and performs required runtime cleanup.

The deliverable is a runtime-specific concurrency contract. A configuration macro is evidence of intent, not proof that every C library call is safe in every context.