Cwd#

📦 std

Report the current working directory and resolve paths to their absolute, symlink-free form. This module provides the four “where am I” functions (cwd, getcwd, fastcwd, fastgetcwd), the three “make this path absolute” functions (abs_path, realpath, fast_abs_path), and a chdir that keeps $ENV{PWD} in sync.

Two groups of tradeoffs matter when choosing between them.

Current directory. getcwd is the most portable and safe call - it asks the kernel via the POSIX getcwd(3) interface and never leaves the process anywhere surprising. fastcwd walks the tree with repeated chdir('..') and is faster on deep paths, but if a parent directory disappears mid-walk (or is unreadable) it returns undef and may leave the process in a different directory than it started. cwd picks the most natural form for the platform; on Linux it is effectively getcwd. fastgetcwd is a synonym for cwd.

Path resolution. abs_path canonicalises a path, resolving symlinks and ./.. components. realpath is its POSIX-style alias - same function, different name. fast_abs_path is the faster variant that drops the “non-existent leaf” fallback: it returns undef the moment any component fails to resolve, where abs_path will still return a usable path when only the final leaf is missing.

chdir changes directory and, on success, updates $ENV{PWD} so child processes inherit a consistent view.

Cwd’s Perl half#

These come from Cwd.pm itself, unchanged:

  • cwd - the output of /bin/pwd; fastgetcwd is the same function.

  • fast_abs_path($path) (alias fast_realpath) - resolves a directory by changing into it and back; undef with $! set to ENOENT when the path does not exist, missing leaf included.

  • chdir($dir) - CORE::chdir, then keeps $ENV{PWD} LOGICAL: after entering a symlink it names the link, not its target, and .. components are folded textually. Returns 1 or 0.

  • realpath - the same function as abs_path.

This is Cwd 3.95 (PathTools); Cwd.pm is upstream’s. getcwd, cwd, fastcwd and fastgetcwd are exported by default, the rest on request.

Synopsis#

use Cwd qw(getcwd abs_path);

my $here = getcwd();                          # e.g. /home/alice/project
print abs_path('/usr/../usr/./bin'), "\n";    # /usr/bin
print abs_path('some-symlink'), "\n";         # where it points, resolved
print defined abs_path('/no/such/dir/file') ? "" : "undef\n";   # undef

Differences from upstream#

None: upstream’s tests pass unchanged (t/81-xs-native/Cwd, the upstream files), and the rest there checks against perl 5.44.

Functions#

Current directory#

getcwd#

Return the absolute path of the process’s current working directory.

cwd#

Return the absolute path of the process’s current working directory.

chdir#

Change the process’s current working directory, and update $ENV{PWD} to match.

Path resolution#

abs_path#

Canonicalise a path: resolve symlinks, ., and .., and return the absolute form.

fast_abs_path#

Canonicalise a path strictly: resolve symlinks and ./.., or return undef if any component is missing.