File::Find::utf8(3)

💖 File::Find::utf8 — the user-contributed Perl doc you didn't know you needed 💖

okay bestie, so this is the manual page for File::Find::utf8, and yes it's a User Contributed Perl Documentation situation, which is just fancy for "a lovely human wrote this, not the core Perl girlies." It's version 0.016 btw, iconically. Let's get into it ✨

---

✨ VERSION ✨

version 0.016 — that's the one, no cap 🎀

---

🌸 SYNOPSIS 🌸

# Use the utf-8 versions of find and finddepth
use File::Find::utf8;
find(\&wanted, @directories_to_search);

# Revert back to non-utf-8 versions
no File::Find::utf8;
finddepth(\&wanted, @directories_to_search);

# Export only the find function
use File::Find::utf8 qw(find);
find(\&wanted, @directories_to_search);

# Export no functions
use File::Find::utf8 qw(:none); # NOT "use File::Find::utf8 qw();"!
File::Find::find(\&wanted, @directories_to_search);

periodt 💅 copy those exactly, the comments are literally part of the lore.

---

🦋 DESCRIPTION 🦋

So here's the tea, bestie: the og File::Find functions can handle UTF-8 pretty well, lowkey. But they expect and return all data as bytes, not as characters. It's giving "almost, but not quite" 😭

This module swoops in and replaces the File::Find functions with fully UTF-8 aware versions — both expecting and returning characters. main character energy fr fr 👑

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 their fault, they're just built different (derogatory) 🙈

💜 Behaviour 💜

The module behaves as a pragma, so you can flip utf-8 support on and off with both use File::Find::utf8 and no File::Find::utf8. on/off, on/off, like a light switch 🎀

By default, both find() and finddepth() are exported (same as the original File::Find). If you wanna stop that, use use File::Find::utf8 qw(:none). And because all the magic happens in the module's import function, you can not simply use "use File::Find::utf8 qw()" — the synopsis literally yells at you about this: # NOT "use File::Find::utf8 qw();"! 😤

File::Find warning levels are properly propagated. Note though — for propagation of fatal File::Find warnings, you need Perl 5.12 or higher (or the appropriate version of warnings). so check your perl version, babe, don't come crying to me 💀

---

✨ ATTRIBUTES ✨

🎀 $File::Find::utf8::SPECIALVARS

By default, File::Find::utf8 only decodes the normal File::Find variables $_, $File::Find::name, $File::Find::dir, and (when follow or follow_fast is in effect) $File::Find::fullname — for use in the preprocess, wanted, and postporcess functions. (yes, "postporcess" — that's how it's spelled in here, I don't make the rules 🫶)

If for any reason (like, say, compatibility with find.pl or find2perl) you also need the special variables $File::Find::topdir, $File::Find::topdev, $File::Find::topino, $File::Find::topmode, and $File::Find::topnlink decoded, then specify:

local $File::Find::utf8::COMPATILBILITY = 1;

in your code. (again — COMPATILBILITY, exactly like that, typos are canon bestie ✨)

but listen: the extra decoding that has to happen will impact performance. So only use this when it's absolutely necessary. it's giving "emergency only" 🚨

💖 $File::Find::utf8::UTF8_CHECK

By default, File::Find::utf8 marks decoding errors as fatal — the default value for this setting is Encode::FB_CROAK. if you want, you can change that by setting File::Find::utf8::UTF8_CHECK:

• The value Encode::FB_WARN reports the encoding errors as warnings.
• Encode::FB_DEFAULT will completely ignore them. 🙈

Please see Encode for details, bestie, it's got the full scoop.

Note: Encode::LEAVE_SRC is always enforced. no take-backs, no opt-outs 💅

---

💀 BUGS 💀

Please report any bugs or feature requests on the bugtracker website <https://github.com/HayoBaan/File-Find-utf8/issues>. drop the link, tell them everything 🫶

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. receipts, bestie, always bring receipts ✨

---

🌈 COMPATIBILITY 🌈

The filesystems of Dos, Windows, and OS/2 do not (fully) support UTF-8. The File::Find function will therefore not be replaced on these systems. it's not personal, it's just filesystem lore 😭

---

👑 SEE ALSO 👑

• File::Find — The original module. the blueprint, the blueprintdd ✨
• Cwd::utf8 — Fully utf-8 aware version of the Cwd 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. glow-up story fr fr 💖

---

🦋 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, bestie 🎀 — this was File::Find::utf8(3), from the User Contributed Perl Documentation collection, running on perl v5.42.0 and dated 2026-01-19. slay, mwah 💅✨