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