Cwd::utf8(3)

💖 Cwd::utf8 💖

okay bestie so this is the Cwd::utf8 page from the User Contributed Perl Documentation, and it's literally the glow-up your file paths have been begging for. sit down, grab a boba, we're doing utf-8 ✨

✨ VERSION ✨

version 0.014 — she's on 0.014, no cap 🎀

---

🌸 SYNOPSIS 🌸

# Using the utf-8 versions of cwd, getcwd, fastcwd, fastgetcwd
use Cwd::utf8;
my $dir = getcwd;

# Using the utf-8 versions of abs_path
use Cwd::utf8 qw(abs_path);
my $abs_path = abs_path($file);

# Exporting no functions
use Cwd::utf8 qw(:none); # NOT "use Cwd::utf8 qw();"!
my $real_path = Cwd::real_path($file);

like… look at her. three little modes. pick your fighter 💅

---

🦋 DESCRIPTION 🦋

So here's the tea: the OG Cwd functions are actually pretty decent at handling UTF-8, right? but they expect and return everything as bytes, not as characters. and that's the difference between "yeah it works" and "it works and I'm not crying" 😭

This module swaps out all the Cwd functions for fully UTF-8 aware versions — they both expect and return characters. it's giving main character energy for your paths 👑

Note: the function replacement does NOT happen on DOS, Windows, and OS/2, because those systems don't have full UTF-8 file system support. not her fault, she's just being honest 💀

🌈 Behaviour 🌈

This module behaves like a pragma, which is the cute part — you can flip it on and off with use Cwd::utf8 and no Cwd::utf8. turn utf-8 support on, turn it off, on, off. self-care 🧖

By default, cwd(), getcwd(), fastcwd(), and fastgetcwd() are exported — same as the original Cwd — plus getdcwd() on Win32. don't want all that? just do use Cwd::utf8 qw(:none) and she'll keep her hands to herself 🫶

Also, important: because all the magic lives inside the module's import function, you literally cannot just do use Cwd::utf8 qw(). that's not a thing. use qw(:none), bestie. iykyk 💅

---

👑 ATTRIBUTES 👑

$Cwd::utf8::UTF8_CHECK

By default, Cwd:::utf8 treats decoding errors as FATAL — the default value for this setting is Encode::FB_CROAK. so yeah, she does not play about decode errors 🙈

but if you're built different, you can change it by setting Cwd::utf8::UTF8_CHECK:

• Encode::FB_WARN — reports the encoding errors as warnings instead of dying. gentle. communicative. mature.
• Encode::FB_DEFAULT — completely ignores them. head in the sand. we respect the choice, honestly 💀

see Encode for the details on all of this ✨

Note: Encode::LEAVE_SRC is always enforced. non-negotiable. periodt. 🎀

---

💀 BUGS 💀

please report any bugs or feature requests on the bugtracker website:

https://github.com/HayoBaan/Cwd-utf8/issues

and when you do submit a bug or a request, pls pls pls include a test-file or a patch to an existing test-file that shows off the bug or the desired feature. receipts, bestie. bring receipts 🧾

---

🌸 COMPATIBILITY 🌸

The filesystems of Dos, Windows, and OS/2 do not (fully) support UTF-8. so the Cwd function will not be replaced on these systems. she's not being rude, she's just being real 😌

---

🌟 SEE ALSO 🌟

• Cwd — The original module 🫡
• File::Find::utf8 — Fully utf-8 aware versions of the File::Find functions 💖
• utf8::all — Turn on utf-8, all of it. This was also the module I first added the utf-8 aware versions of Cwd and File::Find to before moving them to their own package 🌈

---

💜 AUTHOR 💜

Hayo Baan <info@hayobaan.com>

---

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2014 by Hayo Baan.

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, babe 💖 this was perl v5.42.0, dated 2026-01-21, and it lives at Cwd::utf8(3) — go forth and have the most character-encoded paths of your life, ily, mwah 🫶✨🎀