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 vari‐
28       ables combine all the power of "chdir()", File::Spec and Cwd.
29
30       $CWD
31
32       Use the $CWD variable instead of chdir() and Cwd.
33
34           use File::chdir;
35           $CWD = $dir;  # just like chdir($dir)!
36           print $CWD;   # prints the current working directory
37
38       It can be localized, and it does the right thing.
39
40           $CWD = "/foo";      # it's /foo out here.
41           {
42               local $CWD = "/bar";  # /bar in here
43           }
44           # still /foo out here!
45
46       $CWD always returns the absolute path.
47
48       $CWD and normal chdir() work together just fine.
49
50       @CWD
51
52       @CWD represents the current working directory as an array, each direc‐
53       tory in the path is an element of the array.  This can often make the
54       directory easier to manipulate, and you don't have to fumble with
55       "File::Spec->splitpath" and "File::Spec->catdir" to make portable code.
56
57         # Similar to chdir("/usr/local/src/perl")
58         @CWD = qw(usr local src perl);
59
60       pop, push, shift, unshift and splice all work.  pop and push are proba‐
61       bly the most useful.
62
63         pop @CWD;                 # same as chdir(File::Spec->updir)
64         push @CWD, 'some_dir'     # same as chdir('some_dir')
65
66       @CWD and $CWD both work fine together.
67
68       NOTE Due to a perl bug you can't localize @CWD.  See "BUGS and CAVEATS"
69       for a work around.
70

EXAMPLES

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

BUGS and CAVEATS

127       "local @CWD" will not localize @CWD.  This is a bug in Perl, you can't
128       localize tied arrays.  As a work around localizing $CWD will effec‐
129       tively localize @CWD.
130
131           {
132               local $CWD;
133               pop @CWD;
134               ...
135           }
136

NOTES

138       What should %CWD do?  Something with volumes?
139
140           # chdir to C:\Program Files\Sierra\Half Life ?
141           $CWD{C} = '\\Program Files\\Sierra\\Half Life';
142

AUTHOR

144       Michael G Schwern <schwern@pobox.com>
145

LICENSE

147       Copyright 2001-2003 by Michael G Schwern <schwern@pobox.com>.
148
149       This program is free software; you can redistribute it and/or modify it
150       under the same terms as Perl itself.
151
152       See http://www.perl.com/perl/misc/Artistic.html
153

HISTORY

155       I wanted "local chdir" to work.  p5p didn't.  Did I let that stop me?
156       No!  Did we give up after the Germans bombed Pearl Harbor?  Hell, no!
157
158       Abigail and/or Bryan Warnock suggested the $CWD thing, I forget which.
159       They were right.
160
161       The chdir() override was eliminated in 0.04.
162