5 Cwd - get pathname of current working directory
13 my $abs_path = abs_path($file);
17 This module provides functions for determining the pathname of the
18 current working directory. It is recommended that getcwd (or another
19 *cwd() function) be used in I<all> code to ensure portability.
21 By default, it exports the functions cwd(), getcwd(), fastcwd(), and
22 fastgetcwd() (and, on Win32, getdcwd()) into the caller's namespace.
25 =head2 getcwd and friends
27 Each of these functions are called without arguments and return the
28 absolute path of the current working directory.
36 Returns the current working directory.
38 Re-implements the getcwd(3) (or getwd(3)) functions in Perl.
44 The cwd() is the most natural form for the current architecture. For
45 most systems it is identical to `pwd` (but without the trailing line
52 A more dangerous version of getcwd(), but potentially faster.
54 It might conceivably chdir() you out of a directory that it can't
55 chdir() you back into. If fastcwd encounters a problem it will return
56 undef but will probably leave you in a different directory. For a
57 measure of extra security, if everything appears to have worked, the
58 fastcwd() function will check that it leaves you in the same directory
59 that it started in. If it has changed it will C<die> with the message
60 "Unstable directory path, current directory changed
61 unexpectedly". That should never happen.
65 my $cwd = fastgetcwd();
67 The fastgetcwd() function is provided as a synonym for cwd().
72 my $cwd = getdcwd('C:');
74 The getdcwd() function is also provided on Win32 to get the current working
75 directory on the specified drive, since Windows maintains a separate current
76 working directory for each drive. If no drive is specified then the current
79 This function simply calls the Microsoft C library _getdcwd() function.
84 =head2 abs_path and friends
86 These functions are exported only on request. They each take a single
87 argument and return the absolute pathname for it. If no argument is
88 given they'll use the current working directory.
94 my $abs_path = abs_path($file);
96 Uses the same algorithm as getcwd(). Symbolic links and relative-path
97 components ("." and "..") are resolved to return the canonical
98 pathname, just like realpath(3).
102 my $abs_path = realpath($file);
104 A synonym for abs_path().
108 my $abs_path = fast_abs_path($file);
110 A more dangerous, but potentially faster version of abs_path.
116 If you ask to override your chdir() built-in function,
120 then your PWD environment variable will be kept up to date. Note that
121 it will only be kept up to date if all packages which use chdir import
131 Since the path seperators are different on some operating systems ('/'
132 on Unix, ':' on MacPerl, etc...) we recommend you use the File::Spec
133 modules wherever portability is a concern.
137 Actually, on Mac OS, the C<getcwd()>, C<fastgetcwd()> and C<fastcwd()>
138 functions are all aliases for the C<cwd()> function, which, on Mac OS,
139 calls `pwd`. Likewise, the C<abs_path()> function is an alias for
146 Originally by the perl5-porters.
148 Maintained by Ken Williams <KWILLIAMS@cpan.org>
152 Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.
154 This program is free software; you can redistribute it and/or modify
155 it under the same terms as Perl itself.
157 Portions of the C code in this library are copyright (c) 1994 by the
158 Regents of the University of California. All rights reserved. The
159 license on this code is compatible with the licensing of the rest of
160 the distribution - please see the source code in F<Cwd.xs> for the
171 use vars qw(@ISA @EXPORT @EXPORT_OK $VERSION);
175 @ISA = qw/ Exporter /;
176 @EXPORT = qw(cwd getcwd fastcwd fastgetcwd);
177 push @EXPORT, qw(getdcwd) if $^O eq 'MSWin32';
178 @EXPORT_OK = qw(chdir abs_path fast_abs_path realpath fast_realpath);
180 # sys_cwd may keep the builtin command
182 # All the functionality of this module may provided by builtins,
183 # there is no sense to process the rest of the file.
184 # The best choice may be to have this in BEGIN, but how to return from BEGIN?
189 *cwd = defined &sys_cwd ? \&sys_cwd : \&_os2_cwd;
194 *fast_abs_path = \&sys_abspath if defined &sys_abspath;
195 *abs_path = \&fast_abs_path;
196 *realpath = \&fast_abs_path;
197 *fast_realpath = \&fast_abs_path;
205 XSLoader::load( __PACKAGE__, $VERSION );
208 push @ISA, 'DynaLoader';
209 __PACKAGE__->bootstrap( $VERSION );
213 # Must be after the DynaLoader stuff:
214 $VERSION = eval $VERSION;
216 # Big nasty table of function aliases
222 getcwd => '_vms_cwd',
223 fastcwd => '_vms_cwd',
224 fastgetcwd => '_vms_cwd',
225 abs_path => '_vms_abs_path',
226 fast_abs_path => '_vms_abs_path',
231 # We assume that &_NT_cwd is defined as an XSUB or in the core.
234 fastcwd => '_NT_cwd',
235 fastgetcwd => '_NT_cwd',
236 abs_path => 'fast_abs_path',
237 realpath => 'fast_abs_path',
243 getcwd => '_dos_cwd',
244 fastgetcwd => '_dos_cwd',
245 fastcwd => '_dos_cwd',
246 abs_path => 'fast_abs_path',
252 getcwd => '_qnx_cwd',
253 fastgetcwd => '_qnx_cwd',
254 fastcwd => '_qnx_cwd',
255 abs_path => '_qnx_abs_path',
256 fast_abs_path => '_qnx_abs_path',
264 abs_path => 'fast_abs_path',
265 realpath => 'fast_abs_path',
271 getcwd => '_epoc_cwd',
272 fastgetcwd => '_epoc_cwd',
273 fastcwd => '_epoc_cwd',
274 abs_path => 'fast_abs_path',
282 abs_path => 'fast_abs_path',
286 $METHOD_MAP{NT} = $METHOD_MAP{MSWin32};
287 $METHOD_MAP{nto} = $METHOD_MAP{qnx};
290 # Find the pwd command in the expected locations. We assume these
291 # are safe. This prevents _backtick_pwd() consulting $ENV{PATH}
292 # so everything works under taint mode.
294 foreach my $try ('/bin/pwd',
296 '/QOpenSys/bin/pwd', # OS/400 PASE.
305 # Isn't this wrong? _backtick_pwd() will fail if somenone has
306 # pwd in their path but it is not /bin/pwd or /usr/bin/pwd?
307 # See [perl #16774]. --jhi
312 sub _carp { require Carp; Carp::carp(@_) }
313 sub _croak { require Carp; Carp::croak(@_) }
315 # The 'natural and safe form' for UNIX (pwd may be setuid root)
317 local @ENV{qw(PATH IFS CDPATH ENV BASH_ENV)};
318 my $cwd = `$pwd_cmd`;
319 # Belt-and-suspenders in case someone said "undef $/".
321 # `pwd` may fail e.g. if the disk is full
322 chomp($cwd) if defined $cwd;
326 # Since some ports may predefine cwd internally (e.g., NT)
327 # we take care not to override an existing definition for cwd().
329 unless ($METHOD_MAP{$^O}{cwd} or defined &cwd) {
330 # The pwd command is not available in some chroot(2)'ed environments
331 my $sep = $Config::Config{path_sep} || ':';
332 if( $^O eq 'MacOS' || (defined $ENV{PATH} &&
333 $^O ne 'MSWin32' && # no pwd on Windows
334 grep { -x "$_/pwd" } split($sep, $ENV{PATH})) )
336 *cwd = \&_backtick_pwd;
343 # set a reasonable (and very safe) default for fastgetcwd, in case it
344 # isn't redefined later (20001212 rspier)
347 # By Brandon S. Allbery
349 # Usage: $cwd = getcwd();
359 # Usage: $cwd = &fastcwd;
361 # This is a faster version of getcwd. It's also more dangerous because
362 # you might chdir out of a directory that you can't chdir back into.
365 my($odev, $oino, $cdev, $cino, $tdev, $tino);
369 my($orig_cdev, $orig_cino) = stat('.');
370 ($cdev, $cino) = ($orig_cdev, $orig_cino);
373 ($odev, $oino) = ($cdev, $cino);
374 CORE::chdir('..') || return undef;
375 ($cdev, $cino) = stat('.');
376 last if $odev == $cdev && $oino == $cino;
377 opendir(DIR, '.') || return undef;
379 $direntry = readdir(DIR);
380 last unless defined $direntry;
381 next if $direntry eq '.';
382 next if $direntry eq '..';
384 ($tdev, $tino) = lstat($direntry);
385 last unless $tdev != $odev || $tino != $oino;
388 return undef unless defined $direntry; # should never happen
389 unshift(@path, $direntry);
391 $path = '/' . join('/', @path);
392 if ($^O eq 'apollo') { $path = "/".$path; }
393 # At this point $path may be tainted (if tainting) and chdir would fail.
394 # Untaint it then check that we landed where we started.
395 $path =~ /^(.*)\z/s # untaint
396 && CORE::chdir($1) or return undef;
397 ($cdev, $cino) = stat('.');
398 die "Unstable directory path, current directory changed unexpectedly"
399 if $cdev != $orig_cdev || $cino != $orig_cino;
402 if (not defined &fastcwd) { *fastcwd = \&fastcwd_ }
405 # Keeps track of current working directory in PWD environment var
413 if ($ENV{'PWD'} and $^O ne 'os2' and $^O ne 'dos' and $^O ne 'MSWin32') {
414 my($dd,$di) = stat('.');
415 my($pd,$pi) = stat($ENV{'PWD'});
416 if (!defined $dd or !defined $pd or $di != $pi or $dd != $pd) {
422 $wd = Win32::GetFullPathName($wd) if $^O eq 'MSWin32';
425 # Strip an automounter prefix (where /tmp_mnt/foo/bar == /foo/bar)
426 if ($^O ne 'MSWin32' and $ENV{'PWD'} =~ m|(/[^/]+(/[^/]+/[^/]+))(.*)|s) {
427 my($pd,$pi) = stat($2);
428 my($dd,$di) = stat($1);
429 if (defined $pd and defined $dd and $di == $pi and $dd == $pd) {
437 my $newdir = @_ ? shift : ''; # allow for no arg (chdir to HOME dir)
438 $newdir =~ s|///*|/|g unless $^O eq 'MSWin32';
439 chdir_init() unless $chdir_init;
441 if ($^O eq 'MSWin32') {
442 # get the full path name *before* the chdir()
443 $newpwd = Win32::GetFullPathName($newdir);
446 return 0 unless CORE::chdir $newdir;
449 return $ENV{'PWD'} = $ENV{'DEFAULT'}
451 elsif ($^O eq 'MacOS') {
452 return $ENV{'PWD'} = cwd();
454 elsif ($^O eq 'MSWin32') {
455 $ENV{'PWD'} = $newpwd;
459 if ($newdir =~ m#^/#s) {
460 $ENV{'PWD'} = $newdir;
462 my @curdir = split(m#/#,$ENV{'PWD'});
463 @curdir = ('') unless @curdir;
465 foreach $component (split(m#/#, $newdir)) {
466 next if $component eq '.';
467 pop(@curdir),next if $component eq '..';
468 push(@curdir,$component);
470 $ENV{'PWD'} = join('/',@curdir) || '/';
478 my $start = @_ ? shift : '.';
479 my($dotdots, $cwd, @pst, @cst, $dir, @tst);
481 unless (@cst = stat( $start ))
483 _carp("stat($start): $!");
488 # Make sure we can be invoked on plain files, not just directories.
489 # NOTE that this routine assumes that '/' is the only directory separator.
491 my ($dir, $file) = $start =~ m{^(.*)/(.+)$}
492 or return cwd() . '/' . $start;
494 # Can't use "-l _" here, because the previous stat was a stat(), not an lstat().
496 my $link_target = readlink($start);
497 die "Can't resolve link $start: $!" unless defined $link_target;
500 $link_target = $dir . '/' . $link_target
501 unless File::Spec->file_name_is_absolute($link_target);
503 return abs_path($link_target);
506 return $dir ? abs_path($dir) . "/$file" : "/$file";
516 unless (opendir(PARENT, $dotdots))
518 _carp("opendir($dotdots): $!");
521 unless (@cst = stat($dotdots))
523 _carp("stat($dotdots): $!");
527 if ($pst[0] == $cst[0] && $pst[1] == $cst[1])
535 unless (defined ($dir = readdir(PARENT)))
537 _carp("readdir($dotdots): $!");
541 $tst[0] = $pst[0]+1 unless (@tst = lstat("$dotdots/$dir"))
543 while ($dir eq '.' || $dir eq '..' || $tst[0] != $pst[0] ||
546 $cwd = (defined $dir ? "$dir" : "" ) . "/$cwd" ;
548 } while (defined $dir);
549 chop($cwd) unless $cwd eq '/'; # drop the trailing /
556 local $ENV{PWD} = $ENV{PWD} || ''; # Guard against clobberage
559 my $path = @_ ? shift : ($Curdir ||= File::Spec->curdir);
561 # Detaint else we'll explode in taint mode. This is safe because
562 # we're not doing anything dangerous with it.
563 ($path) = $path =~ /(.*)/;
564 ($cwd) = $cwd =~ /(.*)/;
567 _croak("$path: No such file or directory");
571 # Make sure we can be invoked on plain files, not just directories.
573 my ($vol, $dir, $file) = File::Spec->splitpath($path);
574 return File::Spec->catfile($cwd, $path) unless length $dir;
577 my $link_target = readlink($path);
578 die "Can't resolve link $path: $!" unless defined $link_target;
580 $link_target = File::Spec->catpath($vol, $dir, $link_target)
581 unless File::Spec->file_name_is_absolute($link_target);
583 return fast_abs_path($link_target);
586 return $dir eq File::Spec->rootdir
587 ? File::Spec->catpath($vol, $dir, $file)
588 : fast_abs_path(File::Spec->catpath($vol, $dir, '')) . '/' . $file;
591 if (!CORE::chdir($path)) {
592 _croak("Cannot chdir to $path: $!");
594 my $realpath = getcwd();
595 if (! ((-d $cwd) && (CORE::chdir($cwd)))) {
596 _croak("Cannot chdir back to $cwd: $!");
601 # added function alias to follow principle of least surprise
602 # based on previous aliasing. --tchrist 27-Jan-00
603 *fast_realpath = \&fast_abs_path;
606 # --- PORTING SECTION ---
608 # VMS: $ENV{'DEFAULT'} points to default directory at all times
609 # 06-Mar-1996 Charles Bailey bailey@newman.upenn.edu
610 # Note: Use of Cwd::chdir() causes the logical name PWD to be defined
611 # in the process logical name table as the default device and directory
612 # seen by Perl. This may not be the same as the default device
613 # and directory seen by DCL after Perl exits, since the effects
614 # the CRTL chdir() function persist only until Perl exits.
617 return $ENV{'DEFAULT'};
621 return $ENV{'DEFAULT'} unless @_;
623 # may need to turn foo.dir into [.foo]
624 my $path = VMS::Filespec::pathify($_[0]);
625 $path = $_[0] unless defined $path;
627 return VMS::Filespec::rmsexpand($path);
631 $ENV{'PWD'} = `cmd /c cd`;
633 $ENV{'PWD'} =~ s:\\:/:g ;
638 $ENV{'PWD'} = Win32::GetCwd();
639 $ENV{'PWD'} =~ s:\\:/:g ;
643 *_NT_cwd = \&_win32_cwd if (!defined &_NT_cwd &&
644 defined &Win32::GetCwd);
646 *_NT_cwd = \&_os2_cwd unless defined &_NT_cwd;
649 if (!defined &Dos::GetCwd) {
650 $ENV{'PWD'} = `command /c cd`;
652 $ENV{'PWD'} =~ s:\\:/:g ;
654 $ENV{'PWD'} = Dos::GetCwd();
660 local $ENV{PATH} = '';
661 local $ENV{CDPATH} = '';
662 local $ENV{ENV} = '';
663 $ENV{'PWD'} = `/usr/bin/fullpath -t`;
669 local $ENV{PATH} = '';
670 local $ENV{CDPATH} = '';
671 local $ENV{ENV} = '';
672 my $path = @_ ? shift : '.';
675 defined( open(REALPATH, '-|') || exec '/usr/bin/fullpath', '-t', $path ) or
676 die "Can't open /usr/bin/fullpath: $!";
677 my $realpath = <REALPATH>;
684 $ENV{'PWD'} = EPOC::getcwd();
689 # Now that all the base-level functions are set up, alias the
690 # user-level functions to the right places
692 if (exists $METHOD_MAP{$^O}) {
693 my $map = $METHOD_MAP{$^O};
694 foreach my $name (keys %$map) {
695 local $^W = 0; # assignments trigger 'subroutine redefined' warning
697 *{$name} = \&{$map->{$name}};
701 # In case the XS version doesn't load.
702 *abs_path = \&_perl_abs_path unless defined &abs_path;
704 # added function alias for those of us more
705 # used to the libc function. --tchrist 27-Jan-00
706 *realpath = \&abs_path;