GETC_UNLOCKED(3P)

🦋 GETC_UNLOCKED(3P) 🦋

okay bestie, welcome to the POSIX Programmer's Manual page for GETC_UNLOCKED(3P) — yes the title is shouty, it's giving formal, we love that for it 💅

---

✨ PROLOG ✨

So like, real talk first: this manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ — and if it does, you go consult the corresponding Linux manual page for the deets on Linux behavior. Or, plot twist, the interface may just not be implemented on Linux at all. 🙈

---

🌸 NAME 🌸

getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked — stdio with explicit client locking. that's it, that's the name section, iconic.

---

💜 SYNOPSIS 💜

#include <stdio.h>

int getc_unlocked(FILE *stream);
int getchar_unlocked(void);
int putc_unlocked(int c, FILE *stream);
int putchar_unlocked(int c);

look at those little signatures, so neat, so tidy 🎀

---

🌈 DESCRIPTION 🌈

Okay so here's the tea. Versions of the functions getc(), getchar(), putc(), and putchar() — respectively named getc_unlocked(), getchar_unlocked(), putc_unlocked(), and putchar_unlocked() — shall be provided. They're functionally equivalent to the original versions, with one (1) exception: they are not required to be implemented in a fully thread-safe manner. 😭

They shall be thread-safe when used within a scope protected by flockfile() (or ftrylockfile()) and funlockfile().

These functions can safely be used in a multi-threaded program if and only if they are called while the invoking thread owns the (FILE *) object — as is the case after a successful call to the flockfile() or ftrylockfile() functions. so like, own your stream or don't touch it, no cap 👑

⚠️ big warning energy: if getc_unlocked() or putc_unlocked() are implemented as macros, they may evaluate stream more than once. So the stream argument should never be an expression with side-effects. fr fr, don't do it.

---

⭐ RETURN VALUE ⭐

See getc(), getchar(), putc(), and putchar(). that's the whole section, she's brief and she knows it 💅

---

🎀 ERRORS 🎀

See getc(), getchar(), putc(), and putchar(). (same energy, same brevity)

The following sections are informative. okay so everything after this is just ✨vibes and context✨, not requirements. noted.

---

🍓 EXAMPLES 🍓

None.

...

that's it. no examples. she said "figure it out bestie" 😭

---

🫶 APPLICATION USAGE 🫶

Since they may be implemented as macros, getc_unlocked() and putc_unlocked() may treat incorrectly a stream argument with side-effects. In particular, getc_unlocked(*f++) and putc_unlocked(c,*f++) do not necessarily work as expected. 😬

Therefore, use of these functions in such situations should be preceded by the following statement, as appropriate:

#undef getc_unlocked
#undef putc_unlocked

boom. un-macro'd. problem solved, you're welcome 🧚

---

👑 RATIONALE 👑

okay this is the long one, grab a snack 🍓

Some I/O functions are typically implemented as macros for performance reasons — for example, putc() and getc(). For safety, they need to be synchronized, but it is often too expensive to synchronize on every character. Nevertheless, it was felt that the safety concerns were more important; consequently, the getc(), getchar(), putc(), and putchar() functions are required to be thread-safe.

However, unlocked versions are also provided, with names that clearly indicate the unsafe nature of their operation, but which can be used to exploit their higher performance. 🔥

These unlocked versions can be safely used only within explicitly locked program regions, using exported locking primitives. In particular, a sequence such as:

flockfile(fileptr);
putc_unlocked('1', fileptr);
putc_unlocked('\n', fileptr);
fprintf(fileptr, "Line 2\n");
funlockfile(fileptr);

is permissible, and results in the text sequence:

1
Line 2

being printed without being interspersed with output from other threads. so clean, so synchronized, we love a locked region 💖

It would be wrong to have the standard names such as getc(), putc(), and so on, map to the faster, but unsafe'' rather than the slower, but safe'' versions. In either case, you would still want to inspect all uses of getc(), putc(), and so on, by hand when converting existing code. Choosing the safe bindings as the default, at least, results in correct code and maintains the ``atomicity at the function'' invariant. To do otherwise would introduce gratuitous synchronization errors into converted code. Other routines that modify the stdio (FILE *) structures or buffers are also safely synchronized.

Note that there is no need for functions of the form getc_locked(), putc_locked(), and so on, since this is the functionality of getc(), putc(), et al. It would be inappropriate to use a feature test macro to switch a macro definition of getc() between getc_locked() and getc_unlocked(), since the ISO C standard requires an actual function to exist — a function whose behavior could not be changed by the feature test macro. Also, providing both the xxx_locked() and xxx_unlocked() forms leads to the confusion of whether the suffix describes the behavior of the function or the circumstances under which it should be used. 🙈

Three additional routines, flockfile(), ftrylockfile(), and funlockfile() (which may be macros), are provided to allow the user to delineate a sequence of I/O statements that are executed synchronously.

The ungetc() function is infrequently called relative to the other functions/macros so no unlocked variation is needed. she's simply not popular enough for a remix 💀

---

🦄 FUTURE DIRECTIONS 🦄

None.

---

💫 SEE ALSO 💫

• Section 2.5, Standard I/O Streams
• flockfile()
• getc()
• getchar()
• putc()
• putchar()
• 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 whole page bestie!! 💖✨🦋 this one came to you courtesy of IEEE/The Open Group, dated 2017 — mwah, thanks for the lore, love you, bye 👑💅🎀