setmode(3bsd)

💖 setmode(3bsd) 💖

okay bestie, so this is a LOCAL manual page for getmode, setmode — the two little icons that modify mode bits ✨

🎀 NAME 🎀

getmode, setmode — modify mode bits 💅

📚 LIBRARY 📚

Utility functions from BSD systems (libbsd, -lbsd) 🦋

✨ SYNOPSIS ✨

#include <unistd.h>
(See libbsd(7) for include usage.)

void *
setmode(const char *mode_str);

mode_t
getmode(const void *set, mode_t mode);

💜 DESCRIPTION 💜

so. setmode() is the girl who takes a string representation of a file mode change, compiles it into binary form, and hands you back an abstract representation you can then pass to getmode(). that string can be a numeric (octal) one or a symbolic string in the form chmod(1) accepts — and it can represent either an exact mode to set or a change to make to the existing mode. either way, slay 💅

then getmode() takes the file permission bits you gave it as mode, adjusts them according to that compiled change representation set, and returns the adjusted mode. important: only the permission bits get altered, but other parts of the file mode — the type especially — may be examined. so like, it's peeking but not touching, iykyk 👀

now here's the tea 🍓 because some of the possible symbolic values are defined relative to the file creation mask, setmode() may call umask(2), temporarily changing the mask. if that happens, the file creation mask will be restored before setmode() returns. BUT — and this is the part where you need to listen — if the calling program changes the value of its file creation mask after calling setmode(), then setmode() must be called again to recompile the mode string, if getmode() is to modify future file modes correctly. no shortcuts bestie 😭

if the mode you passed to setmode() is invalid, setmode() returns NULL. that's it, that's the whole vibe check 💀

and the value returned from setmode() is obtained from malloc() and should be returned to the system with free() when the program is done with it — generally after a call to getmode(). free your girls, periodt 🫶

🌈 EXAMPLES 🌈

the effects of the shell command ‘chmod a+x myscript.sh’ can be duplicated as follows:

const char *file = "myscript.sh";
struct stat st;
mode_t newmode;

stat(file, &st);
newmode = getmode(setmode("a+x"), st.st_mode);
chmod(file, newmode);

iconic behavior honestly 👑

💀 ERRORS 💀

setmode() may fail and set errno for any of the errors specified for the library routines malloc(3) or strtol(3). and on top of that, setmode() will fail and set errno to:

• [EINVAL] — The mode argument does not represent a valid mode. (invalid input, we don't know her 🙈)

👀 SEE ALSO 👀

chmod(1), stat(2), umask(2), malloc(3)

🧚 HISTORY 🧚

getmode() and setmode() first appeared in 4.4BSD. ancient. vintage. legendary. ⭐

🍓 BUGS 🍓

the type of set should really be some opaque struct type used only by these functions rather than void *. yeah. we know. we're all thinking it 💀

and that's the whole page, bestie!! this one came to you from the good people at Debian, dated January 4, 2009 — so yeah, she's been serving accurate documentation since before some of us could read. mwah 💖✨🎀