```{index} single: chdir; Cwd function ``` ```{index} single: Cwd::chdir; Perl function ``` # chdir Change the process's current working directory, and update `$ENV{PWD}` to match. ## Synopsis ```perl use Cwd qw(chdir); chdir($path) or die $!; ``` ## What you get back `1` on success, `0` on failure. `$!` is set when the call fails so you can distinguish errors. ## Examples Change directory and keep `$ENV{PWD}` consistent for child processes: ```perl use Cwd qw(chdir); chdir('/tmp') or die "chdir: $!"; system('printenv', 'PWD'); # /tmp ``` Guard against a missing target: ```perl use Cwd qw(chdir); unless (chdir('/does/not/exist')) { warn "cannot enter directory: $!"; } ``` Switch directories around a block and return: ```perl use Cwd qw(getcwd chdir); my $saved = getcwd(); chdir('/var/log') or die $!; ## ... work in /var/log ... chdir($saved) or die $!; ``` ## Edge cases - Called with no argument — returns `0` (unlike the core `chdir` builtin, which chdirs to `$ENV{HOME}`). Pass the target explicitly. - Target exists but is not a directory — returns `0` with `$!` set to `ENOTDIR`. - `$ENV{PWD}` is updated only on success, through the `%ENV` tied hash, so `setenv(3)` is called as well. ## Differences from upstream - Upstream's `Cwd::chdir` normalises slashes in the argument before calling the builtin. pperl passes the path through unchanged and relies on the kernel to handle duplicate separators, which it does. - No-argument form returns `0`; upstream treats it as `chdir('')` which is equivalent to `chdir` to `HOME`. Scripts that depend on the implicit-HOME form should pass `$ENV{HOME}` explicitly. ## See also - `getcwd` — absolute path of the current directory - `abs_path` — canonicalise a path without changing directory