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