---
name: "error"
section: "3"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/error/3"
---

# error(3)

glibc error reporting functions

## NAME

error, error\_at\_line, error\_message\_count, error\_one\_per\_line, error\_print\_progname - glibc error reporting functions

## LIBRARY

Standard C library (*libc*, *-lc*)

## SYNOPSIS

```
#include <error.h>
```

**void error(int** *status***, int** *errnum***, const char \****format***, ...);** **void error\_at\_line(int** *status***, int** *errnum***, const char \****file***,**                    **unsigned int** *line***, const char \****format***, ...);**

**extern unsigned int** *error\_message\_count***;** **extern int** *error\_one\_per\_line***;**

**extern typeof(void (void))  \****error\_print\_progname***;**

## DESCRIPTION

**error**() is a general error-reporting function. It flushes *stdout*, and then outputs to *stderr* the program name, a colon and a space, the message specified by the [**printf**(3)](/printf/3.md)-style format string *format*, and, if *errnum* is nonzero, a second colon and a space followed by the string given by *strerror(errnum)*. Any arguments required for *format* should follow *format* in the argument list. The output is terminated by a newline character.

The program name printed by **error**() is the value of the global variable [**program\_invocation\_name**(3)](/program_invocation_name/3.md). *program\_invocation\_name* initially has the same value as *main*()'s *argv\[0\]*. The value of this variable can be modified to change the output of **error**().

If *status* has a nonzero value, then **error**() calls [**exit**(3)](/exit/3.md) to terminate the program using the given value as the exit status; otherwise it returns after printing the error message.

The **error\_at\_line**() function is exactly the same as **error**(), except for the addition of the arguments *file* and *line*. The output produced is as for **error**(), except that after the program name are written: a colon, the value of *file*, a colon, and the value of *line*. The preprocessor values **\_\_LINE\_\_** and **\_\_FILE\_\_** may be useful when calling **error\_at\_line**(), but other values can also be used. For example, these arguments could refer to a location in an input file.

If the global variable *error\_one\_per\_line* is set nonzero, a sequence of **error\_at\_line**() calls with the same value of *file* and *line* will result in only one message (the first) being output.

The global variable *error\_message\_count* counts the number of messages that have been output by **error**() and **error\_at\_line**().

If the global variable *error\_print\_progname* is assigned the address of a function (i.e., is not NULL), then that function is called instead of prefixing the message with the program name and colon. The function should print a suitable string to *stderr*.

## ATTRIBUTES

For an explanation of the terms used in this section, see [**attributes**(7)](/attributes/7.md).

| | | |
| --- | --- | --- |
| **Interface** | **Attribute** | **Value** |
| **error**() | Thread safety | MT-Safe locale |
| **error\_at\_line**() | Thread safety | MT-Unsafe race: error\_at\_line/error\_one\_per\_line locale |

The internal *error\_one\_per\_line* variable is accessed (without any form of synchronization, but since it's an *int* used once, it should be safe enough), and if *error\_one\_per\_line* is set nonzero, the internal static variables (not exposed to users) used to hold the last printed filename and line number are accessed and modified without synchronization; the update is not atomic and it occurs before disabling cancelation, so it can be interrupted only after one of the two variables is modified. After that, **error\_at\_line**() is very much like **error**().

## STANDARDS

GNU.

## SEE ALSO

[**err**(3)](/err/3.md), [**errno**(3)](/errno/3.md), [**exit**(3)](/exit/3.md), [**perror**(3)](/perror/3.md), [**program\_invocation\_name**(3)](/program_invocation_name/3.md), [**strerror**(3)](/strerror/3.md)