FnMatch(3pm)

💖 FnMatch(3pm) — the vibe 💖

okay bestie, so this is the manual page for File::FnMatch, living in the Perl docs under "User Contributed Perl Documentation" (yes that's the man name up there, FnMatch(3pm)). It's giving lowercase-and-quiet, but it does a lot of heavy lifting for a tiny module. Sit down, we're matching filenames. 🎀

---

✨ NAME ✨

File::FnMatch — simple filename and pathname matching. That's it, that's the whole thesis. No cap.

---

🦋 SYNOPSIS 🦋

Like, here's the whole thing in action:

  use File::FnMatch qw(:fnmatch);    # import everything

  # shell-style: match "/a/bc", but not "/a/.bc" nor "/a/b/c"
  fnmatch("/a/*", $fn, FNM_PATHNAME|FNM_PERIOD);

  # find our A- executables only
  grep { fnmatch("A-*.exe", $_) } readdir SOMEDIR;

The first one is your classic shell-style moment: it matches /a/bc but NOT /a/.bc and NOT /a/b/c. The second one is girlband energy — we're finding our A- executables only, one readdir at a time. 💅

---

🌸 DESCRIPTION 🌸

File::FnMatch::fnmatch() gives you simple, shell-like pattern matching. That's the whole product, and honestly? It ate.

She's considerably less powerful than regular expressions, periodt. But shell patterns are still useful and familiar to a huge audience of end-users, which lowkey is the entire point. Your users already know how * works. You do not have to teach them regex. Iconic.

💜 Functions 💜

• fnmatch ( PATTERN, STRING [, FLAGS] ) — returns true if PATTERN matches STRING, and undef otherwise. That's the bare minimum, bestie. FLAGS can be the bitwise OR'ing of any of the supported FNM_* constants (peep the next section, they're right there 👇).

🧚 Constants 🧚

• FNM_NOESCAPE — do NOT treat a backslash ('\') in PATTERN specially. Otherwise (i.e. normally), a backslash escapes whatever character comes next. Choose your fighter.
• FNM_PATHNAME — prohibits wildcards from matching a slash ('/'). Your wildcards cannot cross the path boundary, no matter how much they want to.
• FNM_PERIOD — prohibits wildcards from matching a period ('.') at the start of a string, and — if FNM_PATHNAME is also given — immediately after a slash. Dotfiles are protected, as they deserve to be. 🫶

Other possibilities include at least FNM_CASEFOLD (compare "qr//i"), FNM_LEADING_DIR to restrict matching to everything before the first '/', FNM_FILE_NAME as a synonym for FNM_PATHNAME, and the rather more exotic FNM_EXTMATCH. Consult your system documentation for details — no fr fr, actually go read it, she's not guessing for you.

🌈 EXPORT 🌈

None by default. The export tag ":fnmatch" exports the fnmatch function and all available FNM_* constants. So when you want everything, you say qw(:fnmatch) and everything arrives. Main character tag behavior.

---

⭐ PATTERN SYNTAX ⭐

Okay so the wildcards are:

• the question mark ('?'), matching any single character
• the asterisk ('*'), matching zero or more characters

FNM_PATHNAME and FNM_PERIOD restrict the scope of those wildcards — notably supporting the classic UNIX convention of concealing "dotfiles". 💀

Then we get to bracket expressions, enclosed by '[' and ']', which match any of a set of characters. You can specify them:

• explicitly — "[abcdef]"
• as a range — "[a-f0-9]"
• as the combination of these — "[a-f0-9XYZ]"

Additionally, many implementations support named character classes such as "[[:xdigit:]]". And character sets may be negated with an initial '!', like "[![:space:]]". Negation?? She's got range, literally.

Also, important: locale influences the meaning of fnmatch() patterns. So your patterns are not living in a vacuum, she is a product of her environment. iykyk.

---

😭 CAVEATS 😭

Most UNIX-like systems provide an fnmatch implementation. This module will not work on platforms lacking an implementation — most notably Win32. So if you're on Win32 bestie, this is not your moment, and I'm so sorry. 🥲

---

👑 SEE ALSO 👑

• File::Glob
• POSIX::setlocale
• fnmatch(3)

---

💖 AUTHOR 💖

Michael J. Pomraning

Please report bugs to <mjp-perl AT pilcrow.madison.wi.us> — yes, that's the address, be normal about it.

---

🎀 COPYRIGHT AND LICENSE 🎀

Copyright 2005 by Michael J. Pomraning

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

---

okay that's the whole page, you're so welcome. 🦋 this was documented as part of perl v5.42.3 and the doc itself is dated 2026-08-19 — so when you cite me, cite the vibe and the version, both. periodt. 💅✨🌸