Chapter 8: C library functions

Introduction

Introduces the C library as a portable set of everyday programming tools and explains how its specified API can separate compiler and library implementations.

• C Library Purpose: Explain that the C standard includes both the C language and the C library, whose functions provide everyday programming tools with specified interfaces and semantics for portability.
  Why it matters: This explains why library functions can serve as standard tools across platforms.
• API Implementation Separation: Explain how a clearly specified library API can allow different compiler and C library implementations to be used together on a platform.
  Why it matters: A specified interface can give programmers a choice of compiler and library implementation.

Key terms: C library, C language, interfaces, semantics, portability, application programming interface (API), compiler implementation, library implementation

8.1 General properties of the C library and its functions

This section distinguishes two purposes of C library functions and shows how one function can serve both.

• Two library function purposes: Distinguish library functions that abstract platform-specific operations from basic tools that perform common programming tasks through fixed interfaces.
  Why it matters: The distinction helps explain why different kinds of functionality belong in the C library.
• Printf as a combined example: Explain how printf illustrates both library purposes by relating its formatting and output phases to snprintf and puts.
  Why it matters: printf makes the two purposes concrete without implying that every function fits only one category.

Key terms: platform abstraction layer, basic tools, fixed interface, printf, snprintf, puts, formatting phase, output phase

8.1.1 Headers

This subsection explains that C library headers group interface descriptions for library features, chiefly functions.

• Purpose of C library headers: Explain that a header file bundles interface descriptions for C library features, mostly functions.
  Why it matters: Headers help you find the interfaces for the library functions you want to use.

Key terms: header file, interface descriptions, C library

8.1.2 Interfaces

This subsection explains that C library function interfaces may be implemented as function-like macros and sets a limited approach to pointer-valued interfaces.

• Function-like library macros: Explain that a C library interface specified as a function may be implemented as a function-like macro, and why expressions with side effects should not be passed to such interfaces.
  Why it matters: Call-like syntax does not guarantee that a library interface is implemented as an ordinary function.
• Limited pointer interface use: Describe how the subsection proposes dealing with pointer arguments and pointer return values before covering pointers fully.
  Why it matters: This lets you follow the library examples without needing a full treatment of pointers yet.

Key terms: interfaces, function-like macros, textual replacements, side effects, pointer arguments, known pointers, nullptr, error condition

8.1.3 Error checking

This section explains how to recognize C library failures, report them, and handle the library’s error state.

• Library function failure conventions: Explain why a library function’s return value must be checked according to that function’s documented convention, and describe the three broad return-value patterns.
  Why it matters: Checking against the wrong convention can make a program miss a library failure.
• Failure reporting and early exit: Describe how the section’s `puts` example responds to failure and explain why it recommends making failures visible early in development.
  Why it matters: A visible failure is easier to diagnose than one the program silently ignores.
• Error state after recoverable failures: Explain `errno`’s role in library error reporting and why the section says to reset error state when recovering from a failure.
  Why it matters: A diagnostic or later error check can be misleading if recoverable error state is left behind.

Key terms: return value, special value, error, success, puts, EOF, perror, exit, fail fast, errno

8.1.4 Bounds-checking interfaces

This section explains why C offers optional bounds-checking library interfaces, how programs enable them, and what their naming and failure behavior imply.

• Buffer overflow and runtime checks: Explain how inconsistent parameters to C library functions can cause buffer overflows and how bounds-checking interfaces address that risk at runtime. Describe the usual response to a detected runtime constraint violation.
  Why it matters: A checked interface can detect a dangerous call, but the program may then terminate.
• Optional Annex K availability: Describe how Annex K's optional bounds-checking interfaces are made available and why a program cannot assume every platform supports them.
  Why it matters: Code using these interfaces must account for both platform support and the required opt-in.
• Reserved underscore s names: Explain the usual naming pattern of bounds-checking functions and its consequence for names in your own code.
  Why it matters: Avoiding reserved names prevents your identifiers from conflicting with library interfaces.

Key terms: buffer overflow, bounds-checking interfaces, runtime constraint violation, Annex K, __STDC_LIB_EXT1__, __STDC_WANT_LIB_EXT1__, _s, printf_s, reserved

8.1.5 Platform preconditions

Explains how to make unavoidable platform requirements explicit and reject unsupported builds at compile time.

• Explicit platform preconditions: Explain why portable C code should minimize platform assumptions and make unavoidable requirements explicit, with missed requirements stopping compilation.
  Why it matters: A requirement caught during compilation cannot become an unnoticed platform mismatch at runtime.
• Preprocessor conditional checks: Describe how a #if–#endif conditional can check a platform requirement and how #error and #warning differ. Explain the limits on its conditions and what happens to unknown identifiers.
  Why it matters: These checks let a build fail clearly when a required platform feature is unavailable.
• Later compile-time assertions: Distinguish static_assert from preprocessor checks for conditions that are known only in subsequent compilation phases.
  Why it matters: Not every compile-time requirement can be checked during preprocessing.

Key terms: portability, execution platform, code preconditions, preprocessor conditional, #if, #endif, #error, #warning, unknown identifiers, static_assert

8.2 Integer arithmetic

This section introduces C library interfaces for integer arithmetic, checked operations, and bit properties, emphasizing their results and exceptional cases.

• Absolute Value and Division Interfaces: Explain why the library provides abs and div functions and what a div call returns.
  Why it matters: These interfaces express common integer calculations directly, especially when you need both division results.
• Checked Arithmetic Overflow: Describe how the C23 checked arithmetic functions report overflow and provide a result, including what happens for a signed operation that would otherwise fail.
  Why it matters: Checked arithmetic lets you detect an out-of-range result without first performing a failing signed expression.
• Bit Function Result Guarantees: Explain how the C23 bit functions handle exceptional argument values and distinguish results that do and do not depend on the argument type's width.
  Why it matters: The result guarantees and width distinction help you choose a bit operation whose behavior matches what your code needs.

Key terms: abs, div, quot, rem, ckd_add, checked arithmetic, <stdckdint.h>, overflow, least significant bits, <stdbit.h>

8.3 Numerics

This section introduces type-generic numerical functions and explains why programmers should generally use library implementations rather than replace them.

• Type-generic numerical calls: Explain that <math.h> provides numerical functions, while <tgmath.h> provides macros that select a function according to an argument’s type, as in sin(x) or pow(x, n).
  Why it matters: You can call numerical functions without manually choosing a version for each floating-point type.
• Library implementation advantages: Justify using library numerical functions instead of hand-written replacements, citing their expected quality, efficiency, controlled precision, and possible use of processor-specific instructions.
  Why it matters: A handwritten replacement may sacrifice numerical quality or performance that the library implementation provides.

Key terms: <math.h>, <tgmath.h>, type-generic macros, numerical precision, processor-specific instructions, numerical functions

8.4 Input, output, and file manipulation

Introduces two <stdio.h> output functions by contrasting basic string output with formatted output.

• puts and printf output: Distinguish puts from printf: puts outputs its string argument followed by an end-of-line character, whereas printf lets you format output.
  Why it matters: The distinction helps you choose between simple string output and formatted output.

Key terms: <stdio.h>, puts, printf, end-of-line character

8.4.1 Unformatted text output

Introduces single-character output and stream-based unformatted output, including error reporting, opaque FILE streams, standard output streams, and newline handling.

• Character output and errors: Explain what putchar outputs and how its return value distinguishes success from failure.
  Why it matters: The return value lets a caller detect whether character output failed.
• Streams and opaque FILE: Describe how FILE* streams extend unformatted output and why code should use their functional interfaces rather than their implementation details.
  Why it matters: Streams let the same kind of unformatted output target destinations beyond the terminal without depending on FILE internals.
• Standard output stream roles: Distinguish stdout from stderr and identify which stream puts and putchar use implicitly.
  Why it matters: Separate streams distinguish a program’s usual results from urgent messages.
• String output newline difference: Distinguish puts from fputs in how they handle the end of a string.
  Why it matters: The difference determines whether string output adds a line break.

Key terms: putchar, EOF, FILE*, stream, opaque type, fputs, fputc, stdout, stderr, puts

8.4.2 Files and streams

This section explains how to attach files to C streams, choose opening modes, handle opening failures, and reassociate an existing stream.

• File opening and failure handling: Explain how fopen attaches a file to a program and what to do if opening it fails.
  Why it matters: Opening a file is not enough: a program must also account for failure.
• File opening modes: Distinguish the base opening modes and describe what the mode characters in this section control.
  Why it matters: The mode determines whether a program reads a file or writes to it, and whether existing contents are preserved.
• Bounds-checking opening alternatives: Describe the limited purpose of the bounds-checking file-opening interfaces mentioned here.
  Why it matters: These alternatives make pointer-argument validity and error returns explicit in the interface.
• Stream reassociation with freopen: Explain what freopen can change about an existing stream and give the use identified here.
  Why it matters: Reassociating a stream lets a program direct a standard stream to a file.

Key terms: fopen, stream, perror, mode argument, base modes, append, update mode, fopen_s, freopen_s, errno_t

8.4.3 Text I/O

This section explains buffering and flushing of text output, conversions between program text and external text, and why text lines should avoid trailing whitespace.

• Buffered text output: Explain why text output may not appear immediately and when to use fflush or fclose to flush it. Describe how line buffering affects output from puts and fputs.
  Why it matters: It explains why printed output may be delayed and how to make it appear without closing a stream.
• Text representation conversion: Explain why characters written through a text stream need not correspond one-to-one with external bytes, and how C uses '\n' despite platform-dependent end-of-line encodings.
  Why it matters: It prevents you from assuming that a text file contains exactly the bytes suggested by the program's characters.
• Trailing whitespace in text lines: State why text lines should avoid blanks or tabs immediately before a line ending.
  Why it matters: Avoiding trailing whitespace keeps text from depending on characters that may not survive text I/O.

Key terms: buffered, flushed, fflush, fclose, line buffering, puts, text input and output, converts data, character encodings, end-of-line

8.4.4 Formatted output

This section explains how to choose and construct formatted-output conversions, match them to arguments, and use formats suited to display or later readback.

• Formatted output argument matching: Explain that fprintf adds a stream parameter to printf-style output, and that trailing arguments must match the format’s conversions in number and type.
  Why it matters: A format string determines how the function interprets arguments, so a mismatch is more than a display mistake.
• Format specification components: Describe the required specifier and optional flags, width, precision, and modifier in a format specification, including how width, precision, and flags affect output.
  Why it matters: The parts of a format let you distinguish the conversion itself from choices about its type and presentation.
• Formats suited to values: Distinguish the recommended formats for integer values, bit patterns, and ordinary floating-point decimal output.
  Why it matters: Choosing by meaning helps a reader see a number as a value or as the bit pattern you intend to show.
• Formats for later readback: State which output formats the section recommends for signed integers, unsigned integers, and floating-point numbers that will later be read from a file, and why.
  Why it matters: Output meant for later conversion has different requirements from output chosen simply for easy reading.
• Checked output interface limits: Explain what the optional printf_s and fprintf_s interfaces check and what they do not check.
  Why it matters: A checked interface does not remove the need to match arguments to the format.

Key terms: printf, fprintf, trailing arguments, format specifiers, modifier, undefined behavior, format specification, flags, width, precision

8.4.5 Unformatted text input

This section introduces unformatted text input functions and explains how to distinguish a failed read from reaching end-of-file.

• Unformatted input choices: Describe when to use fgetc and fgets for unformatted text input, and identify stdin as the standard input stream.
  Why it matters: These are the basic interfaces the section recommends for reading unformatted text.
• EOF and failed reads: Explain why fgetc returns int and how to determine whether a failed read means the stream has reached end-of-file.
  Why it matters: It prevents a program from treating every failed character read as proof that input is finished.
• Unsafe gets interface: Justify the section's warning not to use gets.
  Why it matters: The warning distinguishes a removed, unsafe interface from the input functions the section recommends.

Key terms: fgetc, fgets, stdin, int, EOF, feof, failed read, gets, buffer overflow

8.5 String processing and conversion

This section explains portable character handling, string-to-number conversion, and the string-search operations used in a simplified strtoul implementation.

• Character classes and case conversion: Explain why character literals and <ctype.h> classifiers help C programs handle characters across different encodings, and describe what toupper and tolower do.
  Why it matters: These tools let you work with common character categories without assuming one character encoding.
• Numeric character escape portability: Explain how octal and hexadecimal character escapes are delimited and why their meanings are not fully portable.
  Why it matters: A numeric escape can consume more of a string—or denote a different character—than intended.
• String to number conversion: Describe how strtoul interprets a numeric string, including its base argument and the limited use of its second parameter taught here.
  Why it matters: It explains how one library call can accept several familiar written forms of integers.
• Simplified strtoul implementation stages: Trace the division of work between Strtoul and Strtoul_inner, including the error cases stated for the inner function.
  Why it matters: Separating input preparation from digit accumulation makes the conversion’s behavior easier to follow.
• Initial string span searches: Distinguish what strspn and strcspn count at the start of a string.
  Why it matters: The distinction explains how the example skips leading whitespace.

Key terms: integer character constants, <ctype.h>, classifiers, toupper, tolower, octal value, hexadecimal value, execution character set, strtoul, base

8.5.1 Portability of string processing

This subsection explains why changes to C number syntax can make string-to-number conversion unreliable for finding number boundaries or scanning text derived from number literals.

• Version-dependent conversion boundaries: Explain why string-to-number functions cannot reliably determine where a number ends across C versions, using the hexadecimal floating-point and binary-prefix examples.
  Why it matters: Code that treats a conversion's stopping point as a number boundary may behave differently across C versions.
• Literal-derived number scanning: Explain why text originating from a number literal may not be portable input to a string-to-number function when C23 digit separators are involved.
  Why it matters: Even text produced from a valid number literal may not be scanned as the complete number.

Key terms: string-conversion functions, hexadecimal floating-point literals, 0b, strtol, formatted input, digit separator, number literals, strtoull, ULLONG_MAX

8.6 Time

This section explains C’s calendar-time representations, conversions, text formatting, and clocks for finer-resolution or processing-time measurements.

• Calendar time representations: Distinguish the broken-down calendar fields of struct tm from the arithmetic, linear-time representation time_t, including the main counting conventions for struct tm.
  Why it matters: Choosing and interpreting the right representation prevents mistakes when working with dates or elapsed time.
• Current time and differences: Explain how time and difftime are used to obtain a timestamp and express the difference between two time_t values in seconds.
  Why it matters: It gives you a way to report elapsed calendar time without assuming how time_t values are scaled.
• Calendar time conversions: Describe how mktime normalizes a struct tm and produces a time_t, and distinguish local-time from UTC conversion back into struct tm.
  Why it matters: These conversions connect arithmetic timestamps to calendar dates while preserving the distinction between local time and UTC.
• Textual calendar time formatting: Explain why strftime is preferred for producing calendar-time text and why asctime is unsuitable for new code.
  Why it matters: Using strftime provides flexible output without relying on asctime’s easily overwritten result.
• Higher resolution and processing clocks: Distinguish the use of timespec_get for finer-resolution time from clock for processing time attributed to the current execution.
  Why it matters: The choice of clock determines whether a measurement describes finer-resolution time or processing time.

Key terms: calendar times, struct tm, time_t, tm_mon, tm_mday, tm_year, time(0), difftime, double, mktime

8.7 Runtime environment settings

This section explains how a C program reads runtime environment variables and controls its locale setting.

• Environment variables and safe access: Explain that the environment list supplies string name-value pairs to a program, and describe how getenv_s copies a named value into a buffer only if it fits.
  Why it matters: Environment variables let a program obtain settings supplied by its runtime environment without writing an oversized value into its target buffer.
• Startup locale and selection: Explain that C starts a program in the normalized "C" locale and that setlocale can inspect or change the locale, including selecting the system default with an empty string.
  Why it matters: Locale selection affects library choices such as the presentation of numbers, times, and dates.

Key terms: environment list, environment variables, getenv, getenv_s, maxsize, locale, "C" locale, setlocale, <locale.h>, category

8.8 Program termination and assertions

Explains how to end a C program while preserving cleanup, how termination handlers work, and how assertions support debugging but can be disabled for production.

• Normal program termination: Distinguish returning from main from calling exit in another function, and explain why normal termination should preserve cleanup.
  Why it matters: Choosing normal termination gives the program a chance to finish important cleanup.
• Registered termination handlers: Describe what an atexit handler does and explain why atexit(sayGoodBye) passes a function rather than calling it immediately.
  Why it matters: A registered handler can perform application cleanup when normal execution ends.
• Exceptional termination severity: Distinguish quick_exit, _Exit, and abort by which termination handlers or cleanups they bypass, and explain why they require care.
  Why it matters: Bypassing cleanup can leave work unfinished, so these termination functions should not replace ordinary exits casually.
• Runtime assertions and NDEBUG: Explain how assert checks a runtime condition during debugging, what happens when it fails, and how NDEBUG changes its behavior in production compilations.
  Why it matters: Assertions can expose false assumptions during debugging without making those checks trigger abort in a production build.

Key terms: return from main, exit, cleanup, atexit, exit handler, function reference, quick_exit, at_quick_exit, _Exit, abort

8.9 Summary