File::chdir(3pm)

1File::chdir(3)        User Contributed Perl Documentation       File::chdir(3)
2
3
4

NAME

6       File::chdir - a more sensible way to change directories
7

SYNOPSIS

9         use File::chdir;
10
11         $CWD = "/foo/bar";     # now in /foo/bar
12         {
13             local $CWD = "/moo/baz";  # now in /moo/baz
14             ...
15         }
16
17         # still in /foo/bar!
18

DESCRIPTION

20       Perl's chdir() has the unfortunate problem of being very, very, very
21       global.  If any part of your program calls chdir() or if any library
22       you use calls chdir(), it changes the current working directory for the
23       whole program.
24
25       This sucks.
26
27       File::chdir gives you an alternative, $CWD and @CWD.  These two
28       variables combine all the power of "chdir()", File::Spec and Cwd.
29
30   $CWD
31       Use the $CWD variable instead of chdir() and Cwd.
32
33           use File::chdir;
34           $CWD = $dir;  # just like chdir($dir)!
35           print $CWD;   # prints the current working directory
36
37       It can be localized, and it does the right thing.
38
39           $CWD = "/foo";      # it's /foo out here.
40           {
41               local $CWD = "/bar";  # /bar in here
42           }
43           # still /foo out here!
44
45       $CWD always returns the absolute path in the native form for the
46       operating system.
47
48       $CWD and normal chdir() work together just fine.
49
50   @CWD
51       @CWD represents the current working directory as an array, each
52       directory in the path is an element of the array.  This can often make
53       the directory easier to manipulate, and you don't have to fumble with
54       "File::Spec->splitpath" and "File::Spec->catdir" to make portable code.
55
56         # Similar to chdir("/usr/local/src/perl")
57         @CWD = qw(usr local src perl);
58
59       pop, push, shift, unshift and splice all work.  pop and push are
60       probably the most useful.
61
62         pop @CWD;                 # same as chdir(File::Spec->updir)
63         push @CWD, 'some_dir'     # same as chdir('some_dir')
64
65       @CWD and $CWD both work fine together.
66
67       NOTE Due to a perl bug you can't localize @CWD.  See "BUGS and CAVEATS"
68       for a work around.
69

EXAMPLES

71       (We omit the "use File::chdir" from these examples for terseness)
72
73       Here's $CWD instead of chdir:
74
75           $CWD = 'foo';           # chdir('foo')
76
77       and now instead of Cwd.
78
79           print $CWD;             # use Cwd;  print Cwd::abs_path
80
81       you can even do zsh style "cd foo bar"
82
83           $CWD = '/usr/local/foo';
84           $CWD =~ s/usr/var/;
85
86       if you want to localize that, make sure you get the parens right
87
88           {
89               (local $CWD) =~ s/usr/var/;
90               ...
91           }
92
93       It's most useful for writing polite subroutines which don't leave the
94       program in some strange directory:
95
96           sub foo {
97               local $CWD = 'some/other/dir';
98               ...do your work...
99           }
100
101       which is much simplier than the equivalent:
102
103           sub foo {
104               use Cwd;
105               my $orig_dir = Cwd::abs_path;
106               chdir('some/other/dir');
107
108               ...do your work...
109
110               chdir($orig_dir);
111           }
112
113       @CWD comes in handy when you want to start moving up and down the
114       directory hierarchy in a cross-platform manner without having to use
115       File::Spec.
116
117           pop @CWD;                   # chdir(File::Spec->updir);
118           push @CWD, 'some', 'dir'    # chdir(File::Spec->catdir(qw(some dir)));
119
120       You can easily change your parent directory:
121
122           # chdir from /some/dir/bar/moo to /some/dir/foo/moo
123           $CWD[-2] = 'foo';
124

BUGS and CAVEATS

126       "local @CWD" does not work.
127
128       "local @CWD" will not localize @CWD.  This is a bug in Perl, you can't
129       localize tied arrays.  As a work around localizing $CWD will
130       effectively localize @CWD.
131
132           {
133               local $CWD;
134               pop @CWD;
135               ...
136           }
137
138       Volumes not handled
139
140       There is currently no way to change the current volume via File::chdir.
141

NOTES

143       $CWD returns the current directory using native path separators, i.e.
144       '\' on Win32.  This ensures that $CWD will compare correctly with
145       directories created using File::Spec.  For example:
146
147           my $working_dir = File::Spec->catdir( $CWD, "foo" );
148           $CWD = $working_dir;
149           doing_stuff_might_chdir();
150           is( $CWD, $working_dir, "back to original working_dir?" );
151
152       Deleting the last item of @CWD will act like a pop.  Deleting from the
153       middle will throw an exception.
154
155           delete @CWD[-1]; # OK
156           delete @CWD[-2]; # Dies
157
158       What should %CWD do?  Something with volumes?
159
160           # chdir to C:\Program Files\Sierra\Half Life ?
161           $CWD{C} = '\\Program Files\\Sierra\\Half Life';
162

DIAGNOSTICS

164       If an error is encountered when changing $CWD or @CWD, one of the
165       following exceptions will be thrown:
166
167       ·   Can't delete except at the end of @CWD
168
169       ·   Failed to change directory to '$dir'
170

AUTHOR

172       ·   Michael G Schwern <schwern@pobox.com> (original author)
173
174       ·   David A Golden <dagolden@cpan.org> (co-maintainer)
175

LICENSE

177       Copyright 2001-2003 by Michael G Schwern <schwern@pobox.com>.  Portions
178       copyright 2006-2007 by David A Golden <dagolden@cpan.org>.
179
180       This program is free software; you can redistribute it and/or modify it
181       under the same terms as Perl itself.
182
183       See http://dev.perl.org/licenses/
184

HISTORY

186       Michael wanted "local chdir" to work.  p5p didn't.  But it wasn't over!
187       Was it over when the Germans bombed Pearl Harbor?  Hell, no!
188
189       Abigail and/or Bryan Warnock suggested the $CWD thing (Michael forgets
190       which).  They were right.
191
192       The chdir() override was eliminated in 0.04.
193
194       David became co-maintainer with 0.06_01 to fix some chronic Win32 path
195       bugs.
196
197       As of 0.08, if changing $CWD or @CWD fails to change the directory, an
198       error will be thrown.
199