This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Cwd: Change strcmp into strEQ
[perl5.git] / dist / PathTools / Cwd.pm
1 package Cwd;
2 use strict;
3 use Exporter;
4
5
6 our $VERSION = '3.71';
7 my $xs_version = $VERSION;
8 $VERSION =~ tr/_//d;
9
10 our @ISA = qw/ Exporter /;
11 our @EXPORT = qw(cwd getcwd fastcwd fastgetcwd);
12 push @EXPORT, qw(getdcwd) if $^O eq 'MSWin32';
13 our @EXPORT_OK = qw(chdir abs_path fast_abs_path realpath fast_realpath);
14
15 # sys_cwd may keep the builtin command
16
17 # All the functionality of this module may provided by builtins,
18 # there is no sense to process the rest of the file.
19 # The best choice may be to have this in BEGIN, but how to return from BEGIN?
20
21 if ($^O eq 'os2') {
22     local $^W = 0;
23
24     *cwd                = defined &sys_cwd ? \&sys_cwd : \&_os2_cwd;
25     *getcwd             = \&cwd;
26     *fastgetcwd         = \&cwd;
27     *fastcwd            = \&cwd;
28
29     *fast_abs_path      = \&sys_abspath if defined &sys_abspath;
30     *abs_path           = \&fast_abs_path;
31     *realpath           = \&fast_abs_path;
32     *fast_realpath      = \&fast_abs_path;
33
34     return 1;
35 }
36
37 # Need to look up the feature settings on VMS.  The preferred way is to use the
38 # VMS::Feature module, but that may not be available to dual life modules.
39
40 my $use_vms_feature;
41 BEGIN {
42     if ($^O eq 'VMS') {
43         if (eval { local $SIG{__DIE__};
44                    local @INC = @INC;
45                    pop @INC if $INC[-1] eq '.';
46                    require VMS::Feature; }) {
47             $use_vms_feature = 1;
48         }
49     }
50 }
51
52 # Need to look up the UNIX report mode.  This may become a dynamic mode
53 # in the future.
54 sub _vms_unix_rpt {
55     my $unix_rpt;
56     if ($use_vms_feature) {
57         $unix_rpt = VMS::Feature::current("filename_unix_report");
58     } else {
59         my $env_unix_rpt = $ENV{'DECC$FILENAME_UNIX_REPORT'} || '';
60         $unix_rpt = $env_unix_rpt =~ /^[ET1]/i; 
61     }
62     return $unix_rpt;
63 }
64
65 # Need to look up the EFS character set mode.  This may become a dynamic
66 # mode in the future.
67 sub _vms_efs {
68     my $efs;
69     if ($use_vms_feature) {
70         $efs = VMS::Feature::current("efs_charset");
71     } else {
72         my $env_efs = $ENV{'DECC$EFS_CHARSET'} || '';
73         $efs = $env_efs =~ /^[ET1]/i; 
74     }
75     return $efs;
76 }
77
78
79 # If loading the XS stuff doesn't work, we can fall back to pure perl
80 if(! defined &getcwd && defined &DynaLoader::boot_DynaLoader) { # skipped on miniperl
81     require XSLoader;
82     XSLoader::load( __PACKAGE__, $xs_version);
83 }
84
85 # Big nasty table of function aliases
86 my %METHOD_MAP =
87   (
88    VMS =>
89    {
90     cwd                 => '_vms_cwd',
91     getcwd              => '_vms_cwd',
92     fastcwd             => '_vms_cwd',
93     fastgetcwd          => '_vms_cwd',
94     abs_path            => '_vms_abs_path',
95     fast_abs_path       => '_vms_abs_path',
96    },
97
98    MSWin32 =>
99    {
100     # We assume that &_NT_cwd is defined as an XSUB or in the core.
101     cwd                 => '_NT_cwd',
102     getcwd              => '_NT_cwd',
103     fastcwd             => '_NT_cwd',
104     fastgetcwd          => '_NT_cwd',
105     abs_path            => 'fast_abs_path',
106     realpath            => 'fast_abs_path',
107    },
108
109    dos => 
110    {
111     cwd                 => '_dos_cwd',
112     getcwd              => '_dos_cwd',
113     fastgetcwd          => '_dos_cwd',
114     fastcwd             => '_dos_cwd',
115     abs_path            => 'fast_abs_path',
116    },
117
118    # QNX4.  QNX6 has a $os of 'nto'.
119    qnx =>
120    {
121     cwd                 => '_qnx_cwd',
122     getcwd              => '_qnx_cwd',
123     fastgetcwd          => '_qnx_cwd',
124     fastcwd             => '_qnx_cwd',
125     abs_path            => '_qnx_abs_path',
126     fast_abs_path       => '_qnx_abs_path',
127    },
128
129    cygwin =>
130    {
131     getcwd              => 'cwd',
132     fastgetcwd          => 'cwd',
133     fastcwd             => 'cwd',
134     abs_path            => 'fast_abs_path',
135     realpath            => 'fast_abs_path',
136    },
137
138    epoc =>
139    {
140     cwd                 => '_epoc_cwd',
141     getcwd              => '_epoc_cwd',
142     fastgetcwd          => '_epoc_cwd',
143     fastcwd             => '_epoc_cwd',
144     abs_path            => 'fast_abs_path',
145    },
146
147    MacOS =>
148    {
149     getcwd              => 'cwd',
150     fastgetcwd          => 'cwd',
151     fastcwd             => 'cwd',
152     abs_path            => 'fast_abs_path',
153    },
154
155    amigaos =>
156    {
157     getcwd              => '_backtick_pwd',
158     fastgetcwd          => '_backtick_pwd',
159     fastcwd             => '_backtick_pwd',
160     abs_path            => 'fast_abs_path',
161    }
162   );
163
164 $METHOD_MAP{NT} = $METHOD_MAP{MSWin32};
165
166
167 # Find the pwd command in the expected locations.  We assume these
168 # are safe.  This prevents _backtick_pwd() consulting $ENV{PATH}
169 # so everything works under taint mode.
170 my $pwd_cmd;
171 if($^O ne 'MSWin32') {
172     foreach my $try ('/bin/pwd',
173                      '/usr/bin/pwd',
174                      '/QOpenSys/bin/pwd', # OS/400 PASE.
175                     ) {
176         if( -x $try ) {
177             $pwd_cmd = $try;
178             last;
179         }
180     }
181 }
182
183 # Android has a built-in pwd. Using $pwd_cmd will DTRT if
184 # this perl was compiled with -Dd_useshellcmds, which is the
185 # default for Android, but the block below is needed for the
186 # miniperl running on the host when cross-compiling, and
187 # potentially for native builds with -Ud_useshellcmds.
188 if ($^O =~ /android/) {
189     # If targetsh is executable, then we're either a full
190     # perl, or a miniperl for a native build.
191     if (-x $Config::Config{targetsh}) {
192         $pwd_cmd = "$Config::Config{targetsh} -c pwd"
193     }
194     else {
195         my $sh = $Config::Config{sh} || (-x '/system/bin/sh' ? '/system/bin/sh' : 'sh');
196         $pwd_cmd = "$sh -c pwd"
197     }
198 }
199
200 my $found_pwd_cmd = defined($pwd_cmd);
201 unless ($pwd_cmd) {
202     # Isn't this wrong?  _backtick_pwd() will fail if someone has
203     # pwd in their path but it is not /bin/pwd or /usr/bin/pwd?
204     # See [perl #16774]. --jhi
205     $pwd_cmd = 'pwd';
206 }
207
208 # Lazy-load Carp
209 sub _carp  { require Carp; Carp::carp(@_)  }
210 sub _croak { require Carp; Carp::croak(@_) }
211
212 # The 'natural and safe form' for UNIX (pwd may be setuid root)
213 sub _backtick_pwd {
214
215     # Localize %ENV entries in a way that won't create new hash keys.
216     # Under AmigaOS we don't want to localize as it stops perl from
217     # finding 'sh' in the PATH.
218     my @localize = grep exists $ENV{$_}, qw(PATH IFS CDPATH ENV BASH_ENV) if $^O ne "amigaos";
219     local @ENV{@localize} if @localize;
220     
221     my $cwd = `$pwd_cmd`;
222     # Belt-and-suspenders in case someone said "undef $/".
223     local $/ = "\n";
224     # `pwd` may fail e.g. if the disk is full
225     chomp($cwd) if defined $cwd;
226     $cwd;
227 }
228
229 # Since some ports may predefine cwd internally (e.g., NT)
230 # we take care not to override an existing definition for cwd().
231
232 unless ($METHOD_MAP{$^O}{cwd} or defined &cwd) {
233     # The pwd command is not available in some chroot(2)'ed environments
234     my $sep = $Config::Config{path_sep} || ':';
235     my $os = $^O;  # Protect $^O from tainting
236
237
238     # Try again to find a pwd, this time searching the whole PATH.
239     if (defined $ENV{PATH} and $os ne 'MSWin32') {  # no pwd on Windows
240         my @candidates = split($sep, $ENV{PATH});
241         while (!$found_pwd_cmd and @candidates) {
242             my $candidate = shift @candidates;
243             $found_pwd_cmd = 1 if -x "$candidate/pwd";
244         }
245     }
246
247     # MacOS has some special magic to make `pwd` work.
248     if( $os eq 'MacOS' || $found_pwd_cmd )
249     {
250         *cwd = \&_backtick_pwd;
251     }
252     else {
253         *cwd = \&getcwd;
254     }
255 }
256
257 if ($^O eq 'cygwin') {
258   # We need to make sure cwd() is called with no args, because it's
259   # got an arg-less prototype and will die if args are present.
260   local $^W = 0;
261   my $orig_cwd = \&cwd;
262   *cwd = sub { &$orig_cwd() }
263 }
264
265
266 # set a reasonable (and very safe) default for fastgetcwd, in case it
267 # isn't redefined later (20001212 rspier)
268 *fastgetcwd = \&cwd;
269
270 # A non-XS version of getcwd() - also used to bootstrap the perl build
271 # process, when miniperl is running and no XS loading happens.
272 sub _perl_getcwd
273 {
274     abs_path('.');
275 }
276
277 # By John Bazik
278 #
279 # Usage: $cwd = &fastcwd;
280 #
281 # This is a faster version of getcwd.  It's also more dangerous because
282 # you might chdir out of a directory that you can't chdir back into.
283     
284 sub fastcwd_ {
285     my($odev, $oino, $cdev, $cino, $tdev, $tino);
286     my(@path, $path);
287     local(*DIR);
288
289     my($orig_cdev, $orig_cino) = stat('.');
290     ($cdev, $cino) = ($orig_cdev, $orig_cino);
291     for (;;) {
292         my $direntry;
293         ($odev, $oino) = ($cdev, $cino);
294         CORE::chdir('..') || return undef;
295         ($cdev, $cino) = stat('.');
296         last if $odev == $cdev && $oino == $cino;
297         opendir(DIR, '.') || return undef;
298         for (;;) {
299             $direntry = readdir(DIR);
300             last unless defined $direntry;
301             next if $direntry eq '.';
302             next if $direntry eq '..';
303
304             ($tdev, $tino) = lstat($direntry);
305             last unless $tdev != $odev || $tino != $oino;
306         }
307         closedir(DIR);
308         return undef unless defined $direntry; # should never happen
309         unshift(@path, $direntry);
310     }
311     $path = '/' . join('/', @path);
312     if ($^O eq 'apollo') { $path = "/".$path; }
313     # At this point $path may be tainted (if tainting) and chdir would fail.
314     # Untaint it then check that we landed where we started.
315     $path =~ /^(.*)\z/s         # untaint
316         && CORE::chdir($1) or return undef;
317     ($cdev, $cino) = stat('.');
318     die "Unstable directory path, current directory changed unexpectedly"
319         if $cdev != $orig_cdev || $cino != $orig_cino;
320     $path;
321 }
322 if (not defined &fastcwd) { *fastcwd = \&fastcwd_ }
323
324
325 # Keeps track of current working directory in PWD environment var
326 # Usage:
327 #       use Cwd 'chdir';
328 #       chdir $newdir;
329
330 my $chdir_init = 0;
331
332 sub chdir_init {
333     if ($ENV{'PWD'} and $^O ne 'os2' and $^O ne 'dos' and $^O ne 'MSWin32') {
334         my($dd,$di) = stat('.');
335         my($pd,$pi) = stat($ENV{'PWD'});
336         if (!defined $dd or !defined $pd or $di != $pi or $dd != $pd) {
337             $ENV{'PWD'} = cwd();
338         }
339     }
340     else {
341         my $wd = cwd();
342         $wd = Win32::GetFullPathName($wd) if $^O eq 'MSWin32';
343         $ENV{'PWD'} = $wd;
344     }
345     # Strip an automounter prefix (where /tmp_mnt/foo/bar == /foo/bar)
346     if ($^O ne 'MSWin32' and $ENV{'PWD'} =~ m|(/[^/]+(/[^/]+/[^/]+))(.*)|s) {
347         my($pd,$pi) = stat($2);
348         my($dd,$di) = stat($1);
349         if (defined $pd and defined $dd and $di == $pi and $dd == $pd) {
350             $ENV{'PWD'}="$2$3";
351         }
352     }
353     $chdir_init = 1;
354 }
355
356 sub chdir {
357     my $newdir = @_ ? shift : '';       # allow for no arg (chdir to HOME dir)
358     if ($^O eq "cygwin") {
359       $newdir =~ s|\A///+|//|;
360       $newdir =~ s|(?<=[^/])//+|/|g;
361     }
362     elsif ($^O ne 'MSWin32') {
363       $newdir =~ s|///*|/|g;
364     }
365     chdir_init() unless $chdir_init;
366     my $newpwd;
367     if ($^O eq 'MSWin32') {
368         # get the full path name *before* the chdir()
369         $newpwd = Win32::GetFullPathName($newdir);
370     }
371
372     return 0 unless CORE::chdir $newdir;
373
374     if ($^O eq 'VMS') {
375         return $ENV{'PWD'} = $ENV{'DEFAULT'}
376     }
377     elsif ($^O eq 'MacOS') {
378         return $ENV{'PWD'} = cwd();
379     }
380     elsif ($^O eq 'MSWin32') {
381         $ENV{'PWD'} = $newpwd;
382         return 1;
383     }
384
385     if (ref $newdir eq 'GLOB') { # in case a file/dir handle is passed in
386         $ENV{'PWD'} = cwd();
387     } elsif ($newdir =~ m#^/#s) {
388         $ENV{'PWD'} = $newdir;
389     } else {
390         my @curdir = split(m#/#,$ENV{'PWD'});
391         @curdir = ('') unless @curdir;
392         my $component;
393         foreach $component (split(m#/#, $newdir)) {
394             next if $component eq '.';
395             pop(@curdir),next if $component eq '..';
396             push(@curdir,$component);
397         }
398         $ENV{'PWD'} = join('/',@curdir) || '/';
399     }
400     1;
401 }
402
403
404 sub _perl_abs_path
405 {
406     my $start = @_ ? shift : '.';
407     my($dotdots, $cwd, @pst, @cst, $dir, @tst);
408
409     unless (@cst = stat( $start ))
410     {
411         _carp("stat($start): $!");
412         return '';
413     }
414
415     unless (-d _) {
416         # Make sure we can be invoked on plain files, not just directories.
417         # NOTE that this routine assumes that '/' is the only directory separator.
418         
419         my ($dir, $file) = $start =~ m{^(.*)/(.+)$}
420             or return cwd() . '/' . $start;
421         
422         # Can't use "-l _" here, because the previous stat was a stat(), not an lstat().
423         if (-l $start) {
424             my $link_target = readlink($start);
425             die "Can't resolve link $start: $!" unless defined $link_target;
426             
427             require File::Spec;
428             $link_target = $dir . '/' . $link_target
429                 unless File::Spec->file_name_is_absolute($link_target);
430             
431             return abs_path($link_target);
432         }
433         
434         return $dir ? abs_path($dir) . "/$file" : "/$file";
435     }
436
437     $cwd = '';
438     $dotdots = $start;
439     do
440     {
441         $dotdots .= '/..';
442         @pst = @cst;
443         local *PARENT;
444         unless (opendir(PARENT, $dotdots))
445         {
446             # probably a permissions issue.  Try the native command.
447             require File::Spec;
448             return File::Spec->rel2abs( $start, _backtick_pwd() );
449         }
450         unless (@cst = stat($dotdots))
451         {
452             _carp("stat($dotdots): $!");
453             closedir(PARENT);
454             return '';
455         }
456         if ($pst[0] == $cst[0] && $pst[1] == $cst[1])
457         {
458             $dir = undef;
459         }
460         else
461         {
462             do
463             {
464                 unless (defined ($dir = readdir(PARENT)))
465                 {
466                     _carp("readdir($dotdots): $!");
467                     closedir(PARENT);
468                     return '';
469                 }
470                 $tst[0] = $pst[0]+1 unless (@tst = lstat("$dotdots/$dir"))
471             }
472             while ($dir eq '.' || $dir eq '..' || $tst[0] != $pst[0] ||
473                    $tst[1] != $pst[1]);
474         }
475         $cwd = (defined $dir ? "$dir" : "" ) . "/$cwd" ;
476         closedir(PARENT);
477     } while (defined $dir);
478     chop($cwd) unless $cwd eq '/'; # drop the trailing /
479     $cwd;
480 }
481
482
483 my $Curdir;
484 sub fast_abs_path {
485     local $ENV{PWD} = $ENV{PWD} || ''; # Guard against clobberage
486     my $cwd = getcwd();
487     require File::Spec;
488     my $path = @_ ? shift : ($Curdir ||= File::Spec->curdir);
489
490     # Detaint else we'll explode in taint mode.  This is safe because
491     # we're not doing anything dangerous with it.
492     ($path) = $path =~ /(.*)/s;
493     ($cwd)  = $cwd  =~ /(.*)/s;
494
495     unless (-e $path) {
496         _croak("$path: No such file or directory");
497     }
498
499     unless (-d _) {
500         # Make sure we can be invoked on plain files, not just directories.
501         
502         my ($vol, $dir, $file) = File::Spec->splitpath($path);
503         return File::Spec->catfile($cwd, $path) unless length $dir;
504
505         if (-l $path) {
506             my $link_target = readlink($path);
507             die "Can't resolve link $path: $!" unless defined $link_target;
508             
509             $link_target = File::Spec->catpath($vol, $dir, $link_target)
510                 unless File::Spec->file_name_is_absolute($link_target);
511             
512             return fast_abs_path($link_target);
513         }
514         
515         return $dir eq File::Spec->rootdir
516           ? File::Spec->catpath($vol, $dir, $file)
517           : fast_abs_path(File::Spec->catpath($vol, $dir, '')) . '/' . $file;
518     }
519
520     if (!CORE::chdir($path)) {
521         _croak("Cannot chdir to $path: $!");
522     }
523     my $realpath = getcwd();
524     if (! ((-d $cwd) && (CORE::chdir($cwd)))) {
525         _croak("Cannot chdir back to $cwd: $!");
526     }
527     $realpath;
528 }
529
530 # added function alias to follow principle of least surprise
531 # based on previous aliasing.  --tchrist 27-Jan-00
532 *fast_realpath = \&fast_abs_path;
533
534
535 # --- PORTING SECTION ---
536
537 # VMS: $ENV{'DEFAULT'} points to default directory at all times
538 # 06-Mar-1996  Charles Bailey  bailey@newman.upenn.edu
539 # Note: Use of Cwd::chdir() causes the logical name PWD to be defined
540 #   in the process logical name table as the default device and directory
541 #   seen by Perl. This may not be the same as the default device
542 #   and directory seen by DCL after Perl exits, since the effects
543 #   the CRTL chdir() function persist only until Perl exits.
544
545 sub _vms_cwd {
546     return $ENV{'DEFAULT'};
547 }
548
549 sub _vms_abs_path {
550     return $ENV{'DEFAULT'} unless @_;
551     my $path = shift;
552
553     my $efs = _vms_efs;
554     my $unix_rpt = _vms_unix_rpt;
555
556     if (defined &VMS::Filespec::vmsrealpath) {
557         my $path_unix = 0;
558         my $path_vms = 0;
559
560         $path_unix = 1 if ($path =~ m#(?<=\^)/#);
561         $path_unix = 1 if ($path =~ /^\.\.?$/);
562         $path_vms = 1 if ($path =~ m#[\[<\]]#);
563         $path_vms = 1 if ($path =~ /^--?$/);
564
565         my $unix_mode = $path_unix;
566         if ($efs) {
567             # In case of a tie, the Unix report mode decides.
568             if ($path_vms == $path_unix) {
569                 $unix_mode = $unix_rpt;
570             } else {
571                 $unix_mode = 0 if $path_vms;
572             }
573         }
574
575         if ($unix_mode) {
576             # Unix format
577             return VMS::Filespec::unixrealpath($path);
578         }
579
580         # VMS format
581
582         my $new_path = VMS::Filespec::vmsrealpath($path);
583
584         # Perl expects directories to be in directory format
585         $new_path = VMS::Filespec::pathify($new_path) if -d $path;
586         return $new_path;
587     }
588
589     # Fallback to older algorithm if correct ones are not
590     # available.
591
592     if (-l $path) {
593         my $link_target = readlink($path);
594         die "Can't resolve link $path: $!" unless defined $link_target;
595
596         return _vms_abs_path($link_target);
597     }
598
599     # may need to turn foo.dir into [.foo]
600     my $pathified = VMS::Filespec::pathify($path);
601     $path = $pathified if defined $pathified;
602         
603     return VMS::Filespec::rmsexpand($path);
604 }
605
606 sub _os2_cwd {
607     my $pwd = `cmd /c cd`;
608     chomp $pwd;
609     $pwd =~ s:\\:/:g ;
610     $ENV{'PWD'} = $pwd;
611     return $pwd;
612 }
613
614 sub _win32_cwd_simple {
615     my $pwd = `cd`;
616     chomp $pwd;
617     $pwd =~ s:\\:/:g ;
618     $ENV{'PWD'} = $pwd;
619     return $pwd;
620 }
621
622 sub _win32_cwd {
623     my $pwd;
624     $pwd = Win32::GetCwd();
625     $pwd =~ s:\\:/:g ;
626     $ENV{'PWD'} = $pwd;
627     return $pwd;
628 }
629
630 *_NT_cwd = defined &Win32::GetCwd ? \&_win32_cwd : \&_win32_cwd_simple;
631
632 sub _dos_cwd {
633     my $pwd;
634     if (!defined &Dos::GetCwd) {
635         chomp($pwd = `command /c cd`);
636         $pwd =~ s:\\:/:g ;
637     } else {
638         $pwd = Dos::GetCwd();
639     }
640     $ENV{'PWD'} = $pwd;
641     return $pwd;
642 }
643
644 sub _qnx_cwd {
645         local $ENV{PATH} = '';
646         local $ENV{CDPATH} = '';
647         local $ENV{ENV} = '';
648     my $pwd = `/usr/bin/fullpath -t`;
649     chomp $pwd;
650     $ENV{'PWD'} = $pwd;
651     return $pwd;
652 }
653
654 sub _qnx_abs_path {
655         local $ENV{PATH} = '';
656         local $ENV{CDPATH} = '';
657         local $ENV{ENV} = '';
658     my $path = @_ ? shift : '.';
659     local *REALPATH;
660
661     defined( open(REALPATH, '-|') || exec '/usr/bin/fullpath', '-t', $path ) or
662       die "Can't open /usr/bin/fullpath: $!";
663     my $realpath = <REALPATH>;
664     close REALPATH;
665     chomp $realpath;
666     return $realpath;
667 }
668
669 sub _epoc_cwd {
670     return $ENV{'PWD'} = EPOC::getcwd();
671 }
672
673
674 # Now that all the base-level functions are set up, alias the
675 # user-level functions to the right places
676
677 if (exists $METHOD_MAP{$^O}) {
678   my $map = $METHOD_MAP{$^O};
679   foreach my $name (keys %$map) {
680     local $^W = 0;  # assignments trigger 'subroutine redefined' warning
681     no strict 'refs';
682     *{$name} = \&{$map->{$name}};
683   }
684 }
685
686 # In case the XS version doesn't load.
687 *abs_path = \&_perl_abs_path unless defined &abs_path;
688 *getcwd = \&_perl_getcwd unless defined &getcwd;
689
690 # added function alias for those of us more
691 # used to the libc function.  --tchrist 27-Jan-00
692 *realpath = \&abs_path;
693
694 1;
695 __END__
696
697 =head1 NAME
698
699 Cwd - get pathname of current working directory
700
701 =head1 SYNOPSIS
702
703     use Cwd;
704     my $dir = getcwd;
705
706     use Cwd 'abs_path';
707     my $abs_path = abs_path($file);
708
709 =head1 DESCRIPTION
710
711 This module provides functions for determining the pathname of the
712 current working directory.  It is recommended that getcwd (or another
713 *cwd() function) be used in I<all> code to ensure portability.
714
715 By default, it exports the functions cwd(), getcwd(), fastcwd(), and
716 fastgetcwd() (and, on Win32, getdcwd()) into the caller's namespace.  
717
718
719 =head2 getcwd and friends
720
721 Each of these functions are called without arguments and return the
722 absolute path of the current working directory.
723
724 =over 4
725
726 =item getcwd
727
728     my $cwd = getcwd();
729
730 Returns the current working directory.
731
732 Exposes the POSIX function getcwd(3) or re-implements it if it's not
733 available.
734
735 =item cwd
736
737     my $cwd = cwd();
738
739 The cwd() is the most natural form for the current architecture.  For
740 most systems it is identical to `pwd` (but without the trailing line
741 terminator).
742
743 =item fastcwd
744
745     my $cwd = fastcwd();
746
747 A more dangerous version of getcwd(), but potentially faster.
748
749 It might conceivably chdir() you out of a directory that it can't
750 chdir() you back into.  If fastcwd encounters a problem it will return
751 undef but will probably leave you in a different directory.  For a
752 measure of extra security, if everything appears to have worked, the
753 fastcwd() function will check that it leaves you in the same directory
754 that it started in.  If it has changed it will C<die> with the message
755 "Unstable directory path, current directory changed
756 unexpectedly".  That should never happen.
757
758 =item fastgetcwd
759
760   my $cwd = fastgetcwd();
761
762 The fastgetcwd() function is provided as a synonym for cwd().
763
764 =item getdcwd
765
766     my $cwd = getdcwd();
767     my $cwd = getdcwd('C:');
768
769 The getdcwd() function is also provided on Win32 to get the current working
770 directory on the specified drive, since Windows maintains a separate current
771 working directory for each drive.  If no drive is specified then the current
772 drive is assumed.
773
774 This function simply calls the Microsoft C library _getdcwd() function.
775
776 =back
777
778
779 =head2 abs_path and friends
780
781 These functions are exported only on request.  They each take a single
782 argument and return the absolute pathname for it.  If no argument is
783 given they'll use the current working directory.
784
785 =over 4
786
787 =item abs_path
788
789   my $abs_path = abs_path($file);
790
791 Uses the same algorithm as getcwd().  Symbolic links and relative-path
792 components ("." and "..") are resolved to return the canonical
793 pathname, just like realpath(3).
794
795 =item realpath
796
797   my $abs_path = realpath($file);
798
799 A synonym for abs_path().
800
801 =item fast_abs_path
802
803   my $abs_path = fast_abs_path($file);
804
805 A more dangerous, but potentially faster version of abs_path.
806
807 =back
808
809 =head2 $ENV{PWD}
810
811 If you ask to override your chdir() built-in function, 
812
813   use Cwd qw(chdir);
814
815 then your PWD environment variable will be kept up to date.  Note that
816 it will only be kept up to date if all packages which use chdir import
817 it from Cwd.
818
819
820 =head1 NOTES
821
822 =over 4
823
824 =item *
825
826 Since the path separators are different on some operating systems ('/'
827 on Unix, ':' on MacPerl, etc...) we recommend you use the File::Spec
828 modules wherever portability is a concern.
829
830 =item *
831
832 Actually, on Mac OS, the C<getcwd()>, C<fastgetcwd()> and C<fastcwd()>
833 functions are all aliases for the C<cwd()> function, which, on Mac OS,
834 calls `pwd`.  Likewise, the C<abs_path()> function is an alias for
835 C<fast_abs_path()>.
836
837 =back
838
839 =head1 AUTHOR
840
841 Originally by the perl5-porters.
842
843 Maintained by Ken Williams <KWILLIAMS@cpan.org>
844
845 =head1 COPYRIGHT
846
847 Copyright (c) 2004 by the Perl 5 Porters.  All rights reserved.
848
849 This program is free software; you can redistribute it and/or modify
850 it under the same terms as Perl itself.
851
852 Portions of the C code in this library are copyright (c) 1994 by the
853 Regents of the University of California.  All rights reserved.  The
854 license on this code is compatible with the licensing of the rest of
855 the distribution - please see the source code in F<Cwd.xs> for the
856 details.
857
858 =head1 SEE ALSO
859
860 L<File::chdir>
861
862 =cut