Editing Errno.h (section)

{{Short description|Header file for C programs}}
{{C Standard Library}}
{{lowercase|title=errno.h}}
'''errno.h''' is a [[header file]] in the [[C standard library|standard library]] of the [[C (programming language)|C programming language]]. It defines [[Macro (computer science)|macro]]s for reporting and retrieving error conditions using the symbol <code>errno</code> (short form for "error number").<ref name=C11>International Standard for Programming Language C (C11), ISO/IEC 9899:2011, p. 205</ref>

<code>errno</code> acts like an integer variable. A value (the error number) is stored in <code>errno</code> by certain [[library function]]s when they detect errors. At program startup, the value stored is zero. Library functions store only values greater than zero. Any library function can alter the value stored before return, whether or not they detect errors.<ref name=C99>International Standard for Programming Language C (C99), ISO/IEC 9899:1999, p. 186</ref> Most functions indicate that they detected an error by returning a special value, typically [[Null pointer|NULL]] for functions that return [[Pointer (computer programming)|pointer]]s, and -1 for functions that return integers. A few functions require the caller to preset <code>errno</code> to zero and test it afterwards to see if an error was detected.

The <code>errno</code> macro expands to an [[Value (computer science)|lvalue]] with type <code>int</code>, sometimes with the <code>extern</code> and/or <code>volatile</code> type specifiers depending upon the platform.<ref>{{cite web |url=https://www.gnu.org/software/libc/manual/html_node/Checking-for-Errors.html |title=Checking for Errors |date=2014-02-08 |website=The GNU C Library (glibc) |publisher=GNU Project |access-date=2014-06-25}}</ref> Originally this was a static memory location, but macros are almost always used today to allow for [[Multithreading (software)|multi-threading]], so that each thread will see its own [[Thread-local storage|thread-local]] error number.

The header file also defines macros that expand to integer constants that represent the error codes. The [[C standard library]] only requires three to be defined:<ref name=C99 />

{|class="wikitable"
|-
| {{tt|EDOM}} || A parameter was outside a function's domain, e.g. {{Code|lang=c|sqrt(-1)}}
|-
| {{tt|ERANGE}} || A result outside a function's range, e.g. {{Code|lang=c|strtol("0xfffffffff", NULL, 0)}} on systems with a 32-bit wide <code>long</code>
|-
| {{tt|EILSEQ}} || <small>(Required since 1994 Amendment 1 to C89 standard)</small><ref>{{cite web|url=http://www.lysator.liu.se/c/na1.html|title=A brief description of Normative Addendum 1|access-date=2013-09-12}}</ref><br/>Illegal byte sequence, e.g. {{Code|lang=c|mbstowcs(buf, "\xff", 1)}} on systems that use [[UTF-8]].
|}

[[POSIX]] compliant [[operating system]]s like [[AIX]], [[Linux]] or [[Solaris (operating system)|Solaris]] include many other error values, many of which are used much more often than the above ones, such as {{tt|EACCES}} for when a file cannot be opened for reading.<ref>{{man|bd|errno.h|SUS|system error numbers}}</ref> [[C++11]] additionally defines many of the same values found within the POSIX specification.<ref>{{cite web |url=http://en.cppreference.com/w/cpp/error/errno_macros |title=Error numbers - cppreference.com |access-date=2015-05-08 }}</ref>

Traditionally, the first page of [[man page|Unix system manuals]], named intro(2), lists all errno.h macros, but this is not the case with [[Linux]], where these macros are instead listed in the errno(3).{{sfn|Stevens|Rago|2013|p=14}}

An {{code|errno}} can be translated to a descriptive string using [[strerror]] (defined in [[string.h]]) or a BSD extension called {{code|sys_errlist}}. The translation can be printed directly to the [[standard error stream]] using [[perror]] (defined in [[stdio.h]]). As {{code|strerror}} in many Unix-like systems is not thread-safe, a thread-safe version {{code|strerror_r}} is used, but conflicting definitions from POSIX and GNU makes it even less portable than the {{code|sys_errlist}} table.<ref>{{cite web |last1=McCabe |first1=Colin |title=The problem with strerror |url=http://www.club.cc.cmu.edu/~cmccabe/blog_strerror.html |website=www.club.cc.cmu.edu}}</ref>