FILE::SPEC::UNIX(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

💅 NAME 💅

File::Spec::Unix — bestie, this is the File::Spec module for Unix, and it's also the blueprint that all the other File::Spec modules build on. 👑

✨ SYNOPSIS ✨

require File::Spec::Unix; # Done automatically by File::Spec

ngl, you basically never have to type that yourself — File::Spec pulls it in for you, automatic, no cap. 🫶

🦋 DESCRIPTION 🦋

These are the methods for messing with file specifications — the paths, the dirs, all of it. Other File::Spec modules, like File::Spec::Mac, literally inherit from File::Spec::Unix and then override the specific methods they need to change. It's giving ✨ family tree ✨.

🎀 METHODS 🎀

🌸 canonpath()

No physical check on the filesystem!! It's a logical cleanup of a path, purely vibes-based on the string. On UNIX it eliminates successive slashes and successive "/.".

$cpath = File::Spec->canonpath( $path ) ;
🚨 Okay so heads up, and this matters: this does NOT collapse x/../y sections into y. That is by design, periodt. Imagine /foo on your system is a symlink to /bar/baz — then /foo/../quux is actually /bar/quux, not /quux like a naive ../-removal would have you believe. 😭 So if you want that kind of processing, bestie you probably want "Cwd"'s realpath() function, because that one actually traverses the filesystem and cleans paths up for real. 🔥

🌸 catdir()

Concatenate two or more directory names to form a complete path ending with a directory. But then it removes the trailing slash from the resulting string — because it doesn't look good, it isn't necessary, and it confuses OS2. 😤 That's the whole reason. Of course, if this is the root directory, don't cut off the trailing slash :-) (yes, the manpage really did put a little smiley there, iconic)

🌸 catfile

Concatenate one or more directory names and a filename to form a complete path ending with a filename. Simple. Clean. 🧚

🌸 curdir

Returns a string representation of the current directory. On UNIX that's ".". 🏠

🌸 devnull

Returns a string representation of the null device. On UNIX that's "/dev/null". 🕳️ the void, but make it legal

🌸 rootdir

Returns a string representation of the root directory. On UNIX that's "/". 👑

🌸 tmpdir

Returns a string representation of the first writable directory from this list, or the current directory if none from the list are writable:

$ENV{TMPDIR}
/tmp
⚠️ If you're running under taint mode, and $ENV{TMPDIR} is tainted, it is not used. Safety first, bestie. 🛡️

🌸 updir

Returns a string representation of the parent directory. On UNIX that's "..". ⬆️

🌸 no_upwards

Given a list of file names, strip out those that refer to a parent directory. (Does not strip symlinks, only '.', '..', and equivalents.) So don't get it twisted, it's not doing any fancy link tracking. 🙈

🌸 case_tolerant

Returns a true or false value indicating, respectively, that alphabetic is not or is significant when comparing file specifications. 🔤 case sensitivity tea ☕

🌸 file_name_is_absolute

Takes as argument a path and returns true if it is an absolute path.

This does not consult the local filesystem on Unix, Win32, OS/2 or Mac OS (Classic). It does consult the working environment for VMS though — see "file_name_is_absolute" in File::Spec::VMS. 💫

🌸 path

Takes no argument, returns the environment variable PATH as an array. 🛣️

🌸 join

join is the same as catfile. twin behavior, no thoughts, just concatenation 🫶

🌸 splitpath

($volume,$directories,$file) = File::Spec->splitpath( $path );
($volume,$directories,$file) = File::Spec->splitpath( $path,
                                                      $no_file );

Splits a path into volume, directory, and filename portions. On systems with no concept of volume, returns '' for volume. 📦

For systems with no syntax differentiating filenames from directories, it assumes that the last file is a path — unless $no_file is true or a trailing separator or /. or /.. is present. On Unix this means that $no_file true makes this return:

( '', $path, '' )

The directory portion may or may not be returned with a trailing /. mysterious. unpredictable. main character energy. 💅

The results can be passed to "catpath()" to get back a path equivalent to (usually identical to) the original path. 🌀

🌸 splitdir

The opposite of "catdir()". 🔄

@dirs = File::Spec->splitdir( $directories );

$directories must be only the directory portion of the path on systems that have the concept of a volume, or that have path syntax that differentiates files from directories. Don't hand it a filename, bestie, it's not built for that. 🙅

Unlike just splitting the directories on the separator, empty directory names ('') can be returned, because these are significant on some OSs. So no, they're not bugs, they're ✨ features ✨.

On Unix:

File::Spec->splitdir( "/a/b//c/" );

Yields:

( '', 'a', 'b', '', 'c', '' )

look at all those empty strings thriving 💖

🌸 catpath()

Takes volume, directory and file portions and returns an entire path. Under Unix, $volume is ignored, and directory and file are concatenated. A / is inserted if needed — though if the directory portion doesn't start with / it is not added. 🧩 On other OSs, $volume is significant. 🌍

🌸 abs2rel

Takes a destination path and an optional base path, returns a relative path from the base path to the destination path:

$rel_path = File::Spec->abs2rel( $path ) ;
$rel_path = File::Spec->abs2rel( $path, $base ) ;

If $base is not present or '', then cwd() is used. If $base is relative, then it is converted to absolute form using "rel2abs()". This means that it is taken to be relative to cwd(). 📍

On systems that have a grammar that indicates filenames, this ignores the $base filename. Otherwise all path components are assumed to be directories. 🗂️

If $path is relative, it is converted to absolute form using "rel2abs()". This means that it is taken to be relative to cwd(). 🧭

⚠️ No checks against the filesystem are made, so the result may not be correct if $base contains symbolic links. (Apply Cwd::abs_path() beforehand if that is a concern.) On VMS, there is interaction with the working environment, as logicals and macros are expanded. 😵💫

Based on code written by Shigio Yamaguchi. 🙇♀️

🌸 rel2abs()

Converts a relative path to an absolute path. 🚀

$abs_path = File::Spec->rel2abs( $path ) ;
$abs_path = File::Spec->rel2abs( $path, $base ) ;

If $base is not present or '', then cwd() is used. If $base is relative, then it is converted to absolute form using "rel2abs()". This means that it is taken to be relative to cwd(). 📍

On systems that have a grammar that indicates filenames, this ignores the $base filename. Otherwise all path components are assumed to be directories. 🗂️

If $path is absolute, it is cleaned up and returned using "canonpath()". ✨

⚠️ No checks against the filesystem are made. On VMS, there is interaction with the working environment, as logicals and macros are expanded. 👀

Based on code written by Shigio Yamaguchi. 🙇♀️

Copyright (c) 2004 by the Perl 5 Porters. All rights reserved. 📜

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

Please submit bug reports at https://github.com/Perl/perl5/issues — they want to hear from you, bestie, fr fr 🐛

🌈 SEE ALSO 🌈

  • File::Spec

okay and that's the whole page, you ate that 💅 this was File::Spec::Unix(3perl) from perl v5.44.0, dated 2026-10-17 — go forth and concatenate responsibly, ily 🫶✨

📦 where this page comes from