File::lchown(3pm)

🌸 File::lchown — the "User Contributed Perl Documentation" era, bestie 💅

okay so picture this: you got a symlink, and you wanna change who owns it or when it was last touched, but you do NOT wanna mess with the actual file it's pointing at. that's literally the whole plot of this module. it lives in the File::lchown package and it's here to do exactly that. periodt. ✨

---

✨ NAME ✨

File::lchown — modify attributes of symlinks without dereferencing them. that's it, that's the vibe. 🦋

---

🎀 SYNOPSIS 🎀

use File::lchown qw( lchown lutimes );

lchown $uid, $gid, $linkpath or die "Cannot lchown() - $!";

lutimes $atime, $mtime, $linkpath or die "Cannot lutimes() - $!";

look at that. two functions. both of them refusing to follow your symlink. iconic behaviour fr fr. 👑

---

💖 DESCRIPTION 💖

so the regular chown system call is giving… extra. it dereferences your symlink and applies the ownership change to the file it points at instead. not the move. 🙈

but some OSes are cool and provide system calls that don't dereference the symlink — they apply the changes straight to the named path, even when that path is a symlink. it's the same energy as lstat returning the attributes of the symlink itself rather than the file it points at. iykyk 💅

---

🌈 FUNCTIONS 🌈

🍓 lchown

$count = lchown $uid, $gid, @paths;

sets the new user or group ownership on the paths you pass in, and it will not dereference any symlinks while doing it. no cap. 🫶

pass -1 as either the $uid or the $gid and that specific attribute just stays exactly how it was — untouched, unbothered. 💜

returns the number of files that were successfully changed. simple as that.

🧚 lutimes

$count = lutimes $atime, $mtime, @paths;

sets the access time and the modification time on the given paths, again without dereferencing any symlinks. slay. ✨

pass undef as both $atime and $mtime and it'll update the times to the current system time. easy. ⭐

---

💀 okay real talk caveat time, bestie, listen up: for both lchown and lutimes — if you pass more than one path, and some later paths succeed after some earlier ones failed, then the value of $! is not reliable for telling you what actually went wrong. it's giving chaos. so if you care about using $! to report failures, only ever pass one path at a time. for real. 🚨

---

since version 0.03, either time may be given as a fractional value, or as an ARRAY reference holding at least two elements. in that array case, element [0] should hold the integer seconds and element [1] the microseconds part — same style as Time::HiRes. 📐✨

---

🔥 SEE ALSO 🔥

• lchown(2) — change ownership of a file
• lutimes(2) — change file timestamps

---

💅 AUTHOR 💅

Paul Evans <leonerd@leonerd.org.uk>

---

and that's the whole page, queen. this manual came from the perl v5.42.3 distribution and it's dated 2026-08-19 — shoutout to the docs, they ate and left no crumbs. go lchown something without following it, you got this. 💖🌈🦋