REVOKE(2)

💅 REVOKE(2) — the revoke girlies' era 💅

okay bestie, welcome to the REVOKE(2) page — that's section 2 of the System Calls Manual, so you know it's a real syscall and not just some lil shell thing. sit down, grab a boba, we're learning about revoking file access and honestly? iconic behaviour. 🎀

---

✨ NAME ✨

revoke — revoke file access. that's it. that's the whole vibe. she takes your file descriptors away and she does not text back. 💀

---

📚 LIBRARY 📚

Standard C Library (libc, -lc). yes queen, you get her for free with libc, no extra linking gymnastics required. 🫶

---

🌸 SYNOPSIS 🌸

#include <unistd.h>

int
revoke(const char *path);

look at her. so short. so powerful. one little path and everything changes. ⭐

---

🦋 DESCRIPTION 🦋

so here's the tea, bestie. 🍓

the revoke() system call invalidates all current open file descriptors in the system for the file named by path. ALL of them. system-wide. not just yours. not just your process's. every single one. it's giving "blocked and deleted" energy and honestly, respect. 👑

subsequent operations on any such descriptors fail, with two lil exceptions that are lowkey important:

• a read() from a character device file which has been revoked returns a count of zero (that's end-of-file, bestie, not an error — she's just done talking to you) 🥲
• a close() system call will succeed. she's not gonna trap you with an unclosable fd, that would be rude.

and if the file is a special file for a device which is open, the device close function is called as if all open references to the file had been closed — using a special close method which does not block. no waiting, no blocking, no "hold on let me finish", she simply ✨leaves✨.

---

🚨 okay so who's allowed to do this? Access to a file may be revoked only by its owner or the super user. that's the rule. no exceptions, no "but I knew her in high school."

also, heads up:

• the revoke() system call is currently supported only for block and character special device files. so like, don't come for regular files, she's not gonna answer. 🙈
• it's normally used to prepare a terminal device for a new login session, preventing any access by a previous user of the terminal. literally the original "new user, who dis" move. the old user's fds are GONE, the new session gets a clean slate, and nobody's snooping on anybody else's tty. slay. 💅

---

🎀 RETURN VALUES 🎀

• revoke() returns the value 0 if successful. ate. 🔥
• otherwise the value -1 is returned and the global variable errno is set to indicate the error. she's telling you what went wrong, you just gotta read the room (and the variable). 😭

---

⭐ ERRORS ⭐

okay so access to the named file is revoked unless one of the following happens — in which case, nope, no revocation for you:

• [ENOTDIR] — A component of the path prefix is not a directory. bestie, that's not a folder. that's a whole other thing. 💀
• [ENAMETOOLONG] — A component of a pathname exceeded 255 characters, or an entire path name exceeded 1024 characters. she has limits. literally. 255 and 1024. respect them. 🫶
• [ENOENT] — The named file or a component of the path name does not exist. ghosted. the file simply is not there. 👻
• [EACCES] — Search permission is denied for a component of the path prefix. you can't even look for her, let alone revoke her. 🚫
• [ELOOP] — Too many symbolic links were encountered in translating the pathname. the symlink chain went to infinity and beyond and honestly? exhausting. 🌈
• [EFAULT] — The path argument points outside the process's allocated address space. girl, that pointer is in the wrong neighborhood. 🏚️
• [EINVAL] — The implementation does not support the revoke() operation on the named file. not every file gets the revoke treatment, and that's valid. 💅
• [EPERM] — The caller is neither the owner of the file nor the super user. you are not her and you are not root. sit down. 🙈

---

💖 SEE ALSO 💖

• revoke(1)
• close(2)

go read those too, bestie, they're the supporting cast and they understood the assignment. 👑

---

🌈 HISTORY 🌈

The revoke() system call first appeared in 4.3BSD-Reno. so she's vintage. she's got history. she's been doing this since before you were born and she has NOT lost the plot. ⭐

---

💀 BUGS 💀

The non-blocking close method is only correctly implemented for terminal devices.

that's it. that's the bug note. so if you're revoking something that isn't a terminal and you're expecting that smooth non-blocking close energy? bestie. it's not guaranteed. she said "terminals only" and she meant it. 😭

---

and that's the whole page, bestie!! you now know more about revoke(2) than 99% of people in this group chat, no cap. fr fr. 🫶✨

this page came from Debian, dated Jan 25, 2016 — so it's a lil vintage, but the facts are forever. mwah. 💋🎀💖