File::chmod(3pm)

💖 File::chmod — the manual, but make it make sense 💖

okay bestie, buckle up, because this is File::chmod, a Perl module from the 3pm manual section, and it is genuinely iconic. it's giving "I don't wanna make a syscall, I just wanna vibe with permissions." let's go 🦋

---

✨ NAME ✨

File::chmod — it implements symbolic and ls chmod modes 💅

---

🌸 VERSION 🌸

version 0.42

---

🎀 SYNOPSIS 🎀

use File::chmod;
$File::chmod::UMASK = 0;
# It is recommended that you explicitly set $File::chmod::UMASK
# as the default will change in the future
#
# 0 is recommended to behave like system chmod
# 1 if you want File::chmod to apply your environment set umask.
# 2 is how we detect that it's internally set, undef will become the
# default in the future, eventually a lexicaly scoped API may be designed

# chmod takes all three types
# these all do the same thing
chmod(0666,@files);
chmod("=rw",@files);
chmod("-rw-rw-rw-",@files);

# or

use File::chmod qw( symchmod lschmod );

chmod(0666,@files);           # this is the normal chmod
symchmod("=rw",@files);       # takes symbolic modes only
lschmod("-rw-rw-rw-",@files); # takes "ls" modes only

# more functions, read on to understand

bestie, real talk: please set $File::chmod::UMASK yourself. the default is gonna change someday and you do NOT want to be the person whose code breaks in the group chat. 🙈

---

🦋 DESCRIPTION 🦋

File::chmod is a little utility that lets you bypass system calls or the whole bit-processing situation for a file's permissions. it overloads the chmod() function with its own version, and that version accepts an octal mode, a symbolic mode (scroll down, bestie), or an "ls" mode (also scroll down). and if overloading chmod() isn't your vibe? no worries — you can export symchmod() and lschmod() instead, which take a symbolic mode and an "ls" mode respectively. 🫶

version 0.30 brought us an added feature: the $UMASK variable, and it's explained in detail below. here's the tea: if "symchmod()" gets called and that variable is true, then the function uses the (also new) $MASK variable — which defaults to "umask()" — as a mask against the new mode. this mode is on by default, and ngl, it changes the behavior from what you'd expect if you're used to UNIX chmod. it may change in the future. 👀

Symbolic modes are thoroughly described in your chmod(1) man page, but here are a few examples, because examples >>> everything.

chmod("+x","file1","file2");  # overloaded chmod(), that is...
# turns on the execute bit for all users on those two files

chmod("o=,g-w","file1","file2");
# removes 'other' permissions, and the write bit for 'group'

chmod("=u","file1","file2");
# sets all bits to those in 'user'

"ls" modes are the type produced on the left-hand side of an ls -l on a directory. examples, periodt:

chmod("-rwxr-xr-x","file1","file2");
# the 0755 setting; user has read-write-execute, group and others
# have read-execute priveleges

chmod("-rwsrws---","file1","file2");
# sets read-write-execute for user and group, none for others
# also sets set-uid and set-gid bits

okay so here's the key difference, and it matters: the regular chmod() and lschmod() are absolute. like, they are not appending to or subtracting from the current file mode. they SET it, no matter what it was before. gone, replaced, new era. 💅

symchmod() is the useful one for letting you modify a file's permissions without having to run a system call or figure out the file's permissions and then combine that with whatever bits are appropriate. it also operates separately on each file. main character energy fr fr. ✨

---

🔥 FUNCTIONS - EXPORT 🔥

💜 chmod(MODE,FILES)

Takes an octal, symbolic, or "ls" mode, and then chmods each file appropriately. that's it, that's the whole job. 👑

💜 getchmod(MODE,FILES)

Returns a list of modified permissions, without chmodding files. accepts any of the three kinds of modes.

@newmodes = getchmod("+x","file1","file2");
# @newmodes holds the octal permissions of the files'
# modes, if they were to be sent through chmod("+x"...)

---

🌈 FUNCTIONS - EXPORT_OK 🌈

⭐ symchmod(MODE,FILES)

Takes a symbolic permissions mode, and chmods each file.

⭐ lschmod(MODE,FILES)

Takes an "ls" permissions mode, and chmods each file.

⭐ getsymchmod(MODE,FILES)

Returns a list of modified permissions, without chmodding files. accepts only symbolic permission modes.

⭐ getlschmod(MODE,FILES)

Returns a list of modified permissions, without chmodding files. accepts only "ls" permission modes.

⭐ getmod(FILES)

Returns a list of the current mode of each file. just peeking, no touching. 🙈

---

🍓 VARIABLES 🍓

🧚 $File::chmod::DEBUG

If set to a true value, it will report warnings, similar to those produced by chmod() on your system. Otherwise, the functions will not report errors.

Example: a file can not have file-locking and the set-gid bits on at the same time. If $File::chmod::DEBUG is true, the function will report an error. If not, you are not warned of the conflict.

It is set to 1 as default.

🧚 $File::chmod::MASK

Contains the umask to apply to new file modes when using getsymchmod(). This defaults to the return value of umask() at compile time. Is only applied if $UMASK is true.

🧚 $File::chmod::UMASK

This is a boolean which tells getsymchmod() whether or not to apply the umask found in $MASK. It defaults to true.

---

🌟 PORTING 🌟

This is only good on Unix-like boxes. I would like people to help me work on File::chmod for any OS that deserves it. If you would like to help, please email me (address below) with the OS and any information you might have on how chmod() should work on it; if you don't have any specific information, but would still like to help, hey, that's good too. I have the following information (from "perlport"):

💻 Win32

Only good for changing "owner" read-write access, "group", and "other" bits are meaningless. NOTE: Win32::File and Win32::FileSecurity already do this. I do not currently see a need to port File::chmod.

💻 MacOS

Only limited meaning. Disabling/enabling write permission is mapped to locking/unlocking the file.

💻 RISC OS

Only good for changing "owner" and "other" read-write access.

---

👀 SEE ALSO 👀

• Stat::lsMode (by Mark-James Dominus, CPAN ID: MJD)
• chmod(1) manpage
• perldoc -f chmod
• perldoc -f stat

---

💀 BUGS 💀

Please report any bugs or feature requests on the bugtracker website https://github.com/xenoterracide/file-chmod/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

---

🫶 CONTRIBUTORS 🫶

• David Steinbrunner <dsteinbrunner@pobox.com>
• Slaven Rezic <slaven@rezic.de>
• Steve Throckmorton <arrestee@gmail.com>
• Tim <oylenshpeegul@gmail.com>

---

👑 AUTHORS 👑

• Jeff Pinyan <japhy.734+CPAN@gmail.com>
• Caleb Cushing <xenoterracide@gmail.com>

---

💖 COPYRIGHT AND LICENSE 💖

This software is copyright (c) 2015 by Caleb Cushing and Jeff Pinyan.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie, no cap. this one came out of perl v5.36.0, dated 2022-11-19, filed under File::chmod(3pm) — go forth and chmod responsibly, mwah 💅✨🌈