FWIDE(3POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 FWIDE(3POSIX) — the fwide() page, bestie edition 💖

okay so real talk, this is fwide from the POSIX Programmer's Manual (that's the 3POSIX volume, in case the vibe check demanded receipts). pull up a chair, we're gonna find out which direction a stream is facing. yes literally, that's the whole job. it's giving orientation counselor for FILE *s. 🦋

🌸 PROLOG 🌸

okay so before anything else, a lil disclaimer, and I need you to actually read it:

  • this manual page is part of the POSIX Programmer's Manual.
  • the Linux implementation of this interface may differ — so like, go check the corresponding Linux manual page for the details of how Linux actually does it, iykyk.
  • orrr the interface may not be implemented on Linux at all. no cap. 🙈

✨ NAME ✨

fwide — set stream orientation 💅

🎀 SYNOPSIS 🎀

#include <stdio.h>
#include <wchar.h>

int fwide(FILE *stream, int mode);

🌈 DESCRIPTION 🌈

bestie, the tea is that the functionality described on this reference page is aligned with the ISO C standard. and if there's any conflict between what's written here and what the ISO C standard says? that's unintentional, fr fr. this volume of POSIX.1‐2017 defers to the ISO C standard. so like, ISO C is the main character here. 👑

so what does fwide() actually do? it shall determine the orientation of the stream pointed to by stream. that's it. that's the mission.

now here's the part where mode runs the show:

  • if mode is greater than zero, the function first attempts to make the stream wide-oriented. 🫶
  • if mode is less than zero, the function first attempts to make the stream byte-oriented. 🍓
  • otherwise, mode is zero, and the function does not alter the orientation of the stream. it just looks. respectfully. 👀

and okay, important: if the orientation of the stream has already been determined, fwide() shall not change it. periodt. the stream said what it said.

also, fwide() shall not change the setting of errno if it's successful. so if you see errno doing something, that's not from a happy path.

🚨 and now the plot twist: no return value is reserved to indicate an error. so an application that wants to check for error situations should do this lil ritual: set errno to 0, then call fwide(), then check errno, and if it's non-zero, assume an error has occurred. that's the whole strat. no shortcuts. 😭

🔥 RETURN VALUE 🔥

after the call, fwide() shall return:

  • a value greater than zero if the stream has wide-orientation
  • a value less than zero if the stream has byte-orientation
  • zero if the stream has no orientation

three outcomes, three vibes, one int. iconic. ⭐

💜 ERRORS 💜

the fwide() function may fail if:

  • EBADF — the stream argument is not a valid stream.

that's it, that's the whole error list. and remember: these following sections are informative. (noted! 💅)

🧚 EXAMPLES 🧚

None. the page literally says none, so like, we're not inventing any. the source material said no and we respect that. 🫡

💖 APPLICATION USAGE 💖

here's the lil hack, bestie: a call to fwide() with mode set to zero can be used to determine the current orientation of a stream. it's the "hey what are you" of function calls. no changing, just asking. 🌸

🌟 RATIONALE 🌟

None. the standard said no thoughts, head empty. and honestly? slay. 💅

🦋 FUTURE DIRECTIONS 🦋

None. the future is, apparently, wide open and also empty. ✨

👑 SEE ALSO 👑

  • the Base Definitions volume of POSIX.1‐2017, <stdio.h>, <wchar.h>

okay so legally I have to say all of this and I'm gonna say it exactly right because facts are facts:

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 .

aaaand that's the whole page, bestie!! 🎀 this cutie came to you courtesy of IEEE/The Open Group, 2017 — that's the source and the date right there in the sign-off, so now you know exactly who to thank. FWIDE(3POSIX), out. 💖✨🦋

📦 where this page comes from