This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).

File::chdir(3)                       User Contributed Perl Documentation                      File::chdir(3)



NAME
       File::chdir - a more sensible way to change directories

SYNOPSIS
         use File::chdir;

         $CWD = "/foo/bar";     # now in /foo/bar
         {
             local $CWD = "/moo/baz";  # now in /moo/baz
             ...
         }

         # still in /foo/bar!

DESCRIPTION
       Perl's chdir() has the unfortunate problem of being very, very, very global.  If any part of your
       program calls chdir() or if any library you use calls chdir(), it changes the current working
       directory for the whole program.

       This sucks.

       File::chdir gives you an alternative, $CWD and @CWD.  These two variables combine all the power of
       "chdir()", File::Spec and Cwd.

       $CWD

       Use the $CWD variable instead of chdir() and Cwd.

           use File::chdir;
           $CWD = $dir;  # just like chdir($dir)!
           print $CWD;   # prints the current working directory

       It can be localized, and it does the right thing.

           $CWD = "/foo";      # it's /foo out here.
           {
               local $CWD = "/bar";  # /bar in here
           }
           # still /foo out here!

       $CWD always returns the absolute path.

       $CWD and normal chdir() work together just fine.

       @CWD

       @CWD represents the current working directory as an array, each directory in the path is an element
       of the array.  This can often make the directory easier to manipulate, and you don't have to fumble
       with "File::Spec->splitpath" and "File::Spec->catdir" to make portable code.

         # Similar to chdir("/usr/local/src/perl")
         @CWD = qw(usr local src perl);

       pop, push, shift, unshift and splice all work.  pop and push are probably the most useful.

         pop @CWD;                 # same as chdir(File::Spec->updir)
         push @CWD, 'some_dir'     # same as chdir('some_dir')

       @CWD and $CWD both work fine together.

       NOTE Due to a perl bug you can't localize @CWD.  See "BUGS and CAVEATS" for a work around.

EXAMPLES
       (We omit the "use File::chdir" from these examples for terseness)

       Here's $CWD instead of chdir:

           $CWD = 'foo';           # chdir('foo')

       and now instead of Cwd.

           print $CWD;             # use Cwd;  print Cwd::abs_path

       you can even do zsh style "cd foo bar"

           $CWD = '/usr/local/foo';
           $CWD =~ s/usr/var/;

       if you want to localize that, make sure you get the parens right

           {
               (local $CWD) =~ s/usr/var/;
               ...
           }

       It's most useful for writing polite subroutines which don't leave the program in some strange
       directory:

           sub foo {
               local $CWD = 'some/other/dir';
               ...do your work...
           }

       which is much simplier than the equivalent:

           sub foo {
               use Cwd;
               my $orig_dir = Cwd::abs_path;
               chdir('some/other/dir');

               ...do your work...

               chdir($orig_dir);
           }

       @CWD comes in handy when you want to start moving up and down the directory hierarchy in a cross-platform crossplatform
       platform manner without having to use File::Spec.

           pop @CWD;                   # chdir(File::Spec->updir);
           push @CWD, 'some', 'dir'    # chdir(File::Spec->catdir(qw(some dir)));

       You can easily change your parent directory:

           # chdir from /some/dir/bar/moo to /some/dir/foo/moo
           $CWD[-2] = 'foo';

BUGS and CAVEATS
       "local @CWD" will not localize @CWD.  This is a bug in Perl, you can't localize tied arrays.  As a
       work around localizing $CWD will effectively localize @CWD.

           {
               local $CWD;
               pop @CWD;
               ...
           }

NOTES
       What should %CWD do?  Something with volumes?

           # chdir to C:\Program Files\Sierra\Half Life ?
           $CWD{C} = '\\Program Files\\Sierra\\Half Life';

AUTHOR
       Michael G Schwern <schwern@pobox.com>

LICENSE
       Copyright 2001-2003 by Michael G Schwern <schwern@pobox.com>.

       This program is free software; you can redistribute it and/or modify it under the same terms as Perl
       itself.

       See http://www.perl.com/perl/misc/Artistic.html

HISTORY
       I wanted "local chdir" to work.  p5p didn't.  Did I let that stop me?  No!  Did we give up after the
       Germans bombed Pearl Harbor?  Hell, no!

       Abigail and/or Bryan Warnock suggested the $CWD thing, I forget which.  They were right.

       The chdir() override was eliminated in 0.04.

SEE ALSO
       File::Spec, Cwd, "chdir" in perlfunc



perl v5.8.8                                      2003-08-14                                   File::chdir(3)