FCHMOD(3POSIX)

💅 FCHMOD — POSIX Programmer's Manual, bestie edition 💅

okay so quick vibe check before we even start: this page is literally from the POSIX Programmer's Manual (that's the manual name, hi, welcome, it's iconic). But real talk — the Linux implementation of this interface may differ, so go peek at the matching Linux manual page for the actual Linux behavior, or the interface might just… not be implemented on Linux at all. 😭 So keep that in mind, bestie.

---

✨ NAME ✨

fchmod — change mode of a file 🌈

(that's it. that's the name. short, sweet, main character energy.)

---

🎀 SYNOPSIS 🎀

#include <sys/stat.h>

int fchmod(int fildes, mode_t mode);

like. look at it. two args. fildes and mode. so clean. ✨

---

🦋 DESCRIPTION 🦋

So here's the tea, bestie. fchmod() shall be equivalent to chmod() — with one glow-up: instead of naming the file by path, you name it by file descriptor, fildes. That's literally the whole difference. You already have the fd open, you just vibe-check its permissions directly. 👑

Now, the specifics, because we do NOT skip specifics in this house:

• If fildes references a shared memory object, then fchmod() need only affect the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits. Just those six. Not a bit more. periodt.
• If fildes references a typed memory object, the behavior of fchmod() is unspecified. 🫠 (translation: don't do that and expect anything, it's giving chaos)
• If fildes refers to a socket, the behavior of fchmod() is unspecified. same energy. don't.
• If fildes refers to a STREAM (one that's fattach()-ed into the file system name space) the call returns successfully, doing nothing. yes literally. it just smiles and nods. 💀

---

💖 RETURN VALUE 💖

• Slayed? 🎉 Upon successful completion, fchmod() shall return 0.
• Not slayed? It shall return -1 and set errno to indicate the error. (the error is in errno, go look, it's right there)

---

🔥 ERRORS 🔥

the "shall fail" girlies (these are guaranteed):

• EBADF — The fildes argument is not an open file descriptor. bestie that fd is not a thing. 🙈
• EPERM — The effective user ID does not match the owner of the file and the process does not have appropriate privileges. no permission, no party. ✋
• EROFS — The file referred to by fildes resides on a read-only file system. it said read-only and it MEANT it. 📖

the "may fail" girlies (sometimes, depending):

• EINTR — The fchmod() function was interrupted by a signal. rude, honestly. 😤
• EINVAL — The value of the mode argument is invalid. that mode is not giving what it needs to give. 🚫
• EINVAL — The fildes argument refers to a pipe and the implementation disallows execution of fchmod() on a pipe. (yes EINVAL shows up twice, that's not a typo, both of them are real, we don't merge them 💅)

Also: the following sections are informative. meaning: cute context, not requirements. noted. 🫶

---

🌸 EXAMPLES 🌸

Changing the Current Permissions for a File

Okay so this example is chef's kiss, it shows you how to change the permissions for a file named /home/cnd/mod1 so that the owner and group have read/write/execute permissions, but the world only has read/write permissions. here's the whole thing, verbatim, no cap:

#include <sys/stat.h>
#include <fcntl.h>

mode_t mode;
int    fildes;
...
fildes = open("/home/cnd/mod1", O_RDWR);
fchmod(fildes, S_IRWXU | S_IRWXG | S_IROTH | S_IWOTH);

look at those flags. S_IRWXU | S_IRWXG | S_IROTH | S_IWOTH. we love a bitwise moment. 🎀

---

🧚 APPLICATION USAGE 🧚

None. literally nothing. we said what we said. 💜

---

💀 RATIONALE 💀

None. again. nothing. the reasoning is a mystery, the vibes are immaculate. ✨

---

🌈 FUTURE DIRECTIONS 🌈

None. the future is… exactly the same. slay. 👑

---

🍓 SEE ALSO 🍓

go read these next, bestie, they're all connected, iykyk:

• chmod(), chown(), creat(), fcntl(), fstatat(), fstatvfs(), mknod(), open(), read(), write()

Also the Base Definitions volume of POSIX.1‐2017, <sys_stat.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 manual page came to you from IEEE/The Open Group, dated 2017, and it lives under the name FCHMOD(3POSIX) — that's the source, the version and the date, all folded into one cute little sign-off. bye, love u, go chmod responsibly. 💖