PERROR(3P)

🌸 PERROR(3P) — the POSIX Programmer's Manual page, but make it a group chat 🌸

okay bestie, sit down, hydrate, because today we're learning about perror() 💅

quick heads up before we even start: this page lives in the POSIX Programmer's Manual. The Linux implementation of this interface may differ (so like, go read the Linux man page for the actual Linux tea), or honestly the interface might not even be implemented on Linux at all 🙈

---

✨ PROLOG ✨

So real talk: this is a POSIX manual page. If you're on Linux and things look different? Consult the corresponding Linux manual page for details on Linux behavior, because they're not always twinning. And sometimes the interface isn't implemented on Linux at all, so vibe check your platform first 🫶

---

💖 NAME 💖

perror — write error messages to standard error

that's it. that's the whole job. it writes error messages to stderr and it does it iconically ✨

---

🎀 SYNOPSIS 🎀

#include <stdio.h>

void perror(const char *s);

---

🦋 DESCRIPTION 🦋

So the functionality on this reference page is aligned with the ISO C standard. Any conflict between what's written here and the ISO C standard is unintentional — nobody's trying to start drama. This volume of POSIX.1‐2017 literally defers to the ISO C standard. periodt.

The perror() function shall map the error number accessed through the symbol errno to a language-dependent error message, and that message gets written to the standard error stream like this:

• First (if s is not a null pointer and the character pointed to by s is not the null byte), the string pointed to by s followed by a <colon> and a <space>.
• Then an error message string followed by a <newline>.

So like, "malloc: " + the message + a newline. cute. chef's kiss. 💅

The contents of those error message strings shall be the same as those returned by strerror() with argument errno. Same strings, different delivery system, no cap.

perror() shall mark for update the last data modification and last file status change timestamps of the file associated with the standard error stream. When does that happen? At some time between its successful completion and exit(), abort(), or the completion of fflush() or fclose() on stderr. So it's giving "eventually, bestie" energy — the timing is deliberately loose 🌈

perror() shall not change the orientation of the standard error stream. leave the stream's orientation alone, it's thriving as it is 🙏

On error, perror() shall set the error indicator for the stream to which stderr points, and shall set errno to indicate the error. yes, it can fail, and yes, it'll tell you by setting the indicator.

And here's the big one — since no value is returned, an application wishing to check for error situations should:

1. call clearerr(stderr) before calling perror()
2. then, if ferror(stderr) returns non-zero, the value of errno indicates which error occurred

so that's the detective workflow. clear it, call it, check it. 🔍

---

👑 RETURN VALUE 👑

The perror() function shall not return a value. Like, nothing. void. it returns the vibe, not a value. 💀

---

🔥 ERRORS 🔥

Refer to fputc().

The following sections are informative. (translation: the important spec stuff is done, everything after this is bonus content ✨)

---

🍓 EXAMPLES 🍓

💜 Printing an Error Message for a Function 💜

The following example replaces bufptr with a buffer that is the necessary size. If an error occurs, the perror() function prints a message and the program exits.

#include <stdio.h>
#include <stdlib.h>
...
char *bufptr;
size_t szbuf;
...
if ((bufptr = malloc(szbuf)) == NULL) {
    perror("malloc"); exit(2);
}
...

see how it's just perror("malloc") and the whole error story gets printed? that's the main character moment right there 😭

---

🧚 APPLICATION USAGE 🧚

Application writers may prefer to use alternative interfaces instead of perror(), such as strerror_r() in combination with fprintf(). so if you want more control over your output (formatting, thread safety vibes, whatever), that combo is right there for you 🫶

---

⭐ RATIONALE ⭐

None.

(it said what it said. nothing to add. iconic.) 💅

---

🌈 FUTURE DIRECTIONS 🌈

None.

(future? unchanged. slay.) ✨

---

🌸 SEE ALSO 🌸

• fprintf()
• fputc()
• psiginfo()
• strerror()
• The Base Definitions volume of POSIX.1‐2017, <stdio.h>

---

💖 COPYRIGHT 💖

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

🫶 and that's the page!! brought to you by IEEE/The Open Group, 2017 — this was PERROR(3P), from the POSIX Programmer's Manual, and honestly? she ate. go write some error messages, bestie 💅✨🎀