1File::Spec(3pm) Perl Programmers Reference Guide File::Spec(3pm)
2
6 File::Spec - portably perform operations on file names
7
9 use File::Spec;
10 $x=File::Spec->catfile('a', 'b', 'c');
12 which returns 'a/b/c' under Unix. Or:
14 use File::Spec::Functions;
16 $x = catfile('a', 'b', 'c');
18
20 This module is designed to support operations commonly performed on
21 file specifications (usually called "file names", but not to be con‐
22 fused with the contents of a file, or Perl's file handles), such as
23 concatenating several directory and file names into a single path, or
24 determining whether a path is rooted. It is based on code directly
25 taken from MakeMaker 5.17, code written by Andreas Koenig, Andy
26 Dougherty, Charles Bailey, Ilya Zakharevich, Paul Schinder, and others.
27 Since these functions are different for most operating systems, each
29 set of OS specific routines is available in a separate module, includ‐
30 ing:
31 File::Spec::Unix
33 File::Spec::Mac
34 File::Spec::OS2
35 File::Spec::Win32
36 File::Spec::VMS
37 The module appropriate for the current OS is automatically loaded by
39 File::Spec. Since some modules (like VMS) make use of facilities avail‐
40 able only under that OS, it may not be possible to load all modules
41 under all operating systems.
42 Since File::Spec is object oriented, subroutines should not be called
44 directly, as in:
45 File::Spec::catfile('a','b');
47 but rather as class methods:
49 File::Spec->catfile('a','b');
51 For simple uses, File::Spec::Functions provides convenient functional
53 forms of these methods.
54
56 canonpath
57 No physical check on the filesystem, but a logical cleanup of a path.
58 $cpath = File::Spec->canonpath( $path ) ;
60 Note that this does *not* collapse x/../y sections into y. This is
62 by design. If /foo on your system is a symlink to /bar/baz, then
63 /foo/../quux is actually /bar/quux, not /quux as a naive ../-removal
64 would give you. If you want to do this kind of processing, you prob‐
65 ably want "Cwd"'s "realpath()" function to actually traverse the
66 filesystem cleaning up paths like this.
67 catdir
69 Concatenate two or more directory names to form a complete path end‐
70 ing with a directory. But remove the trailing slash from the result‐
71 ing string, because it doesn't look good, isn't necessary and con‐
72 fuses OS/2. Of course, if this is the root directory, don't cut off
73 the trailing slash :-)
74 $path = File::Spec->catdir( @directories );
76 catfile
78 Concatenate one or more directory names and a filename to form a com‐
79 plete path ending with a filename
80 $path = File::Spec->catfile( @directories, $filename );
82 curdir
84 Returns a string representation of the current directory.
85 $curdir = File::Spec->curdir();
87 devnull
89 Returns a string representation of the null device.
90 $devnull = File::Spec->devnull();
92 rootdir
94 Returns a string representation of the root directory.
95 $rootdir = File::Spec->rootdir();
97 tmpdir
99 Returns a string representation of the first writable directory from
100 a list of possible temporary directories. Returns the current direc‐
101 tory if no writable temporary directories are found. The list of
102 directories checked depends on the platform; e.g. File::Spec::Unix
103 checks $ENV{TMPDIR} (unless taint is on) and /tmp.
104 $tmpdir = File::Spec->tmpdir();
106 updir
108 Returns a string representation of the parent directory.
109 $updir = File::Spec->updir();
111 no_upwards
113 Given a list of file names, strip out those that refer to a parent
114 directory. (Does not strip symlinks, only '.', '..', and equiva‐
115 lents.)
116 @paths = File::Spec->no_upwards( @paths );
118 case_tolerant
120 Returns a true or false value indicating, respectively, that alpha‐
121 betic case is not or is significant when comparing file specifica‐
122 tions.
123 $is_case_tolerant = File::Spec->case_tolerant();
125 file_name_is_absolute
127 Takes as its argument a path, and returns true if it is an absolute
128 path.
129 $is_absolute = File::Spec->file_name_is_absolute( $path );
131 This does not consult the local filesystem on Unix, Win32, OS/2, or
133 Mac OS (Classic). It does consult the working environment for VMS
134 (see "file_name_is_absolute" in File::Spec::VMS).
135 path
137 Takes no argument. Returns the environment variable "PATH" (or the
138 local platform's equivalent) as a list.
139 @PATH = File::Spec->path();
141 join
143 join is the same as catfile.
144 splitpath
146 Splits a path in to volume, directory, and filename portions. On sys‐
147 tems with no concept of volume, returns '' for volume.
148 ($volume,$directories,$file) = File::Spec->splitpath( $path );
150 ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );
151 For systems with no syntax differentiating filenames from directo‐
153 ries, assumes that the last file is a path unless $no_file is true or
154 a trailing separator or /. or /.. is present. On Unix, this means
155 that $no_file true makes this return ( '', $path, '' ).
156 The directory portion may or may not be returned with a trailing '/'.
158 The results can be passed to "catpath()" to get back a path equiva‐
160 lent to (usually identical to) the original path.
161 splitdir
163 The opposite of "catdir()".
164 @dirs = File::Spec->splitdir( $directories );
166 $directories must be only the directory portion of the path on sys‐
168 tems that have the concept of a volume or that have path syntax that
169 differentiates files from directories.
170 Unlike just splitting the directories on the separator, empty direc‐
172 tory names ('') can be returned, because these are significant on
173 some OSes.
174 catpath()
176 Takes volume, directory and file portions and returns an entire path.
177 Under Unix, $volume is ignored, and directory and file are concate‐
178 nated. A '/' is inserted if need be. On other OSes, $volume is sig‐
179 nificant.
180 $full_path = File::Spec->catpath( $volume, $directory, $file );
182 abs2rel
184 Takes a destination path and an optional base path returns a relative
185 path from the base path to the destination path:
186 $rel_path = File::Spec->abs2rel( $path ) ;
188 $rel_path = File::Spec->abs2rel( $path, $base ) ;
189 If $base is not present or '', then cwd() is used. If $base is rela‐
191 tive, then it is converted to absolute form using "rel2abs()". This
192 means that it is taken to be relative to cwd().
193 On systems with the concept of volume, if $path and $base appear to
195 be on two different volumes, we will not attempt to resolve the two
196 paths, and we will instead simply return $path. Note that previous
197 versions of this module ignored the volume of $base, which resulted
198 in garbage results part of the time.
199 On systems that have a grammar that indicates filenames, this ignores
201 the $base filename as well. Otherwise all path components are assumed
202 to be directories.
203 If $path is relative, it is converted to absolute form using
205 "rel2abs()". This means that it is taken to be relative to cwd().
206 No checks against the filesystem are made. On VMS, there is interac‐
208 tion with the working environment, as logicals and macros are
209 expanded.
210 Based on code written by Shigio Yamaguchi.
212 rel2abs()
214 Converts a relative path to an absolute path.
215 $abs_path = File::Spec->rel2abs( $path ) ;
217 $abs_path = File::Spec->rel2abs( $path, $base ) ;
218 If $base is not present or '', then cwd() is used. If $base is rela‐
220 tive, then it is converted to absolute form using "rel2abs()". This
221 means that it is taken to be relative to cwd().
222 On systems with the concept of volume, if $path and $base appear to
224 be on two different volumes, we will not attempt to resolve the two
225 paths, and we will instead simply return $path. Note that previous
226 versions of this module ignored the volume of $base, which resulted
227 in garbage results part of the time.
228 On systems that have a grammar that indicates filenames, this ignores
230 the $base filename as well. Otherwise all path components are assumed
231 to be directories.
232 If $path is absolute, it is cleaned up and returned using "canon‐
234 path()".
235 No checks against the filesystem are made. On VMS, there is interac‐
237 tion with the working environment, as logicals and macros are
238 expanded.
239 Based on code written by Shigio Yamaguchi.
241 For further information, please see File::Spec::Unix, File::Spec::Mac,
243 File::Spec::OS2, File::Spec::Win32, or File::Spec::VMS.
244
246 File::Spec::Unix, File::Spec::Mac, File::Spec::OS2, File::Spec::Win32,
247 File::Spec::VMS, File::Spec::Functions, ExtUtils::MakeMaker
248
250 Currently maintained by Ken Williams "<KWILLIAMS@cpan.org>".
251 The vast majority of the code was written by Kenneth Albanowski
253 "<kjahds@kjahds.com>", Andy Dougherty "<doughera@lafayette.edu>",
254 Andreas Koenig "<A.Koenig@franz.ww.TU-Berlin.DE>", Tim Bunce
255 "<Tim.Bunce@ig.co.uk>". VMS support by Charles Bailey "<bailey@new‐
256 man.upenn.edu>". OS/2 support by Ilya Zakharevich
257 "<ilya@math.ohio-state.edu>". Mac support by Paul Schinder "<schin‐
258 der@pobox.com>", and Thomas Wegner "<wegner_thomas@yahoo.com>".
259 abs2rel() and rel2abs() written by Shigio Yamaguchi "<shigio@tama‐
260 com.com>", modified by Barrie Slaymaker "<barries@slaysys.com>".
261 splitpath(), splitdir(), catpath() and catdir() by Barrie Slaymaker.
262
264 Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.
265 This program is free software; you can redistribute it and/or modify it
267 under the same terms as Perl itself.
268perl v5.8.8 2001-09-21 File::Spec(3pm)