C Standard Library errno.h

What You’ll Learn

The <errno.h> header defines errno, a shared error indicator that many C library functions set when something goes wrong. Combined with return-value checks and helpers like perror and strerror, it lets your program report failures clearly instead of crashing silently.

Definition and Usage

errno is a macro that expands to a modifiable int lvalue. When a library function fails, it often stores a positive error code in errno so your program can tell why it failed. At program startup, errno is zero.

Crucially, library functions do not clear errno on success. A leftover value from an earlier error can mislead you if you read errno without checking the function’s return value or without resetting errno before the call.

📝 Syntax

Include the header:

#include <errno.h>

The errno macro

Portable code uses errno directly after including the header. You do not need to write extern int errno; yourself.

errno = 0;              /* reset before a call when needed */
if (some_call() fails) {
    if (errno != 0) {   /* inspect error code */
        /* handle error */
    }
}

Common error macros (errno.h)

• EDOM — domain error (invalid argument to a math function, e.g. sqrt(-1)).
• ERANGE — range error (result too large or too small to represent).
• EINVAL — invalid argument (common on POSIX systems).
• EINTR — interrupted system call (POSIX).
• ENOMEM — not enough memory (POSIX).

Additional codes like ENOENT (“No such file or directory”) come from the host system and are used by functions such as fopen.

Related helpers (other headers)

• perror(const char *s) — prints s plus error message to stderr (<stdio.h>).
• strerror(int errnum) — returns a string for error code errnum (<string.h>).

Headers and linking

• #include <errno.h> for errno, EDOM, ERANGE.
• #include <stdio.h> for perror; #include <string.h> for strerror.
• Math examples: gcc program.c -std=c11 -lm -o program

Examples Gallery

Compile with gcc file.c -std=c11 -o out. Add -lm for math examples. Always check return values; use errno to learn why a documented failure happened.

#include <stdio.h>
#include <errno.h>
#include <string.h>

int main(void) {
    FILE *file = fopen("nonexistent.txt", "r");

    if (file == NULL) {
        printf("Error opening file: %s (errno=%d)\n",
               strerror(errno), errno);
    } else {
        fclose(file);
    }

    return 0;
}

Error opening file: No such file or directory (errno=2)

#include <errno.h>
#include <math.h>
#include <stdio.h>

int main(void) {
    errno = 0;
    double result = sqrt(-1.0);

    printf("sqrt(-1) = %g\n", result);

    if (errno == EDOM) {
        perror("sqrt domain error");
    }

    return 0;
}

sqrt(-1) = nan
sqrt domain error: Numerical argument out of domain

#include <errno.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    const char *big = "999999999999999999999";
    char *end = NULL;
    long value;

    errno = 0;
    value = strtol(big, &end, 10);

    if (errno == ERANGE) {
        printf("Overflow: value out of long range\n");
    } else if (end == big) {
        printf("No digits parsed\n");
    } else {
        printf("Parsed: %ld\n", value);
    }

    return 0;
}

Overflow: value out of long range

#include <stdio.h>
#include <errno.h>
#include <string.h>

int main(void) {
  if (fopen("missing.dat", "r") == NULL) {
    perror("perror says");                    /* to stderr */
    printf("strerror says: %s\n", strerror(errno));  /* to stdout */
  }
  return 0;
}

perror says: No such file or directory
strerror says: No such file or directory

#include <errno.h>
#include <stdio.h>
#include <string.h>

int main(void) {
    /* Simulate an earlier error */
    errno = EDOM;

    /* Successful call — does NOT clear errno */
    char msg[] = "hello";
    size_t len = strlen(msg);

    printf("strlen = %zu\n", len);

    if (errno != 0) {
        printf("False alarm: errno is still %d (%s)\n",
               errno, strerror(errno));
    }

    /* Correct approach for the next operation */
    errno = 0;
    len = strlen(msg);
    if (errno != 0) {
        printf("strlen failed?\n");
    } else {
        printf("After reset: errno is 0 (correct)\n");
    }

    return 0;
}

strlen = 5
False alarm: errno is still 33 (Numerical argument out of domain)
After reset: errno is 0 (correct)

🚀 Common Use Cases

• File I/O — report why fopen, read, or fwrite failed.
• String-to-number parsing — detect overflow and invalid input with strtol/strtod.
• Math libraries — catch EDOM and ERANGE from sqrt, log, exp.
• CLI tools — print friendly errors with perror when system calls fail.
• Logging — store strerror(errno) in log files with timestamps.
• Defensive libraries — document which error codes your wrapper sets for callers.

📝 Notes

• errno is a macro, not a normal global variable you declare yourself.
• Since C11, errno is thread-local—each thread has its own value.
• Successful calls may leave errno unchanged; never assume it is zero after success.
• Only read errno immediately after a failed call—other calls may overwrite it.
• strerror returns a pointer to a static buffer; it may be overwritten by the next strerror call.
• Math functions may also set the floating-point exception flags; errno is one part of error reporting.

⚡ Optimization

Reading and setting errno is negligible overhead. In release builds, focus on correct error paths rather than avoiding errno. For hot paths, still check return values; skip string formatting (perror/strerror) unless you actually report the error.

💡 Best Practices