1File::Spec(3) User Contributed Perl Documentation File::Spec(3)
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
22 confused 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 König, 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,
30 including:
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
40 available only under that OS, it may not be possible to load all
41 modules 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
65 probably 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
70 ending with a directory. But remove the trailing slash from the
71 resulting string, because it doesn't look good, isn't necessary and
72 confuses OS/2. Of course, if this is the root directory, don't cut
73 off the trailing slash :-)
74 $path = File::Spec->catdir( @directories );
76 catfile
78 Concatenate one or more directory names and a filename to form a
79 complete 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
101 directory if no writable temporary directories are found. The list
102 of 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 files in a directory (such as from "readdir()"),
114 strip out '.' and '..'.
115 SECURITY NOTE: This does NOT filter paths containing '..', like
117 '../../../../etc/passwd', only literal matches to '.' and '..'.
118 @paths = File::Spec->no_upwards( readdir $dirhandle );
120 case_tolerant
122 Returns a true or false value indicating, respectively, that
123 alphabetic case is not or is significant when comparing file
124 specifications. Cygwin and Win32 accept an optional drive argument.
125 $is_case_tolerant = File::Spec->case_tolerant();
127 file_name_is_absolute
129 Takes as its argument a path, and returns true if it is an absolute
130 path.
131 $is_absolute = File::Spec->file_name_is_absolute( $path );
133 This does not consult the local filesystem on Unix, Win32, OS/2, or
135 Mac OS (Classic). It does consult the working environment for VMS
136 (see "file_name_is_absolute" in File::Spec::VMS).
137 path
139 Takes no argument. Returns the environment variable "PATH" (or the
140 local platform's equivalent) as a list.
141 @PATH = File::Spec->path();
143 join
145 join is the same as catfile.
146 splitpath
148 Splits a path in to volume, directory, and filename portions. On
149 systems with no concept of volume, returns '' for volume.
150 ($volume,$directories,$file) =
152 File::Spec->splitpath( $path );
153 ($volume,$directories,$file) =
154 File::Spec->splitpath( $path, $no_file );
155 For systems with no syntax differentiating filenames from
157 directories, assumes that the last file is a path unless $no_file is
158 true or a trailing separator or /. or /.. is present. On Unix, this
159 means that $no_file true makes this return ( '', $path, '' ).
160 The directory portion may or may not be returned with a trailing '/'.
162 The results can be passed to "catpath()" to get back a path
164 equivalent to (usually identical to) the original path.
165 splitdir
167 The opposite of "catdir".
168 @dirs = File::Spec->splitdir( $directories );
170 $directories must be only the directory portion of the path on
172 systems that have the concept of a volume or that have path syntax
173 that differentiates files from directories.
174 Unlike just splitting the directories on the separator, empty
176 directory names ('') can be returned, because these are significant
177 on some OSes.
178 catpath()
180 Takes volume, directory and file portions and returns an entire path.
181 Under Unix, $volume is ignored, and directory and file are
182 concatenated. A '/' is inserted if need be. On other OSes, $volume
183 is significant.
184 $full_path = File::Spec->catpath( $volume, $directory, $file );
186 abs2rel
188 Takes a destination path and an optional base path returns a relative
189 path from the base path to the destination path:
190 $rel_path = File::Spec->abs2rel( $path ) ;
192 $rel_path = File::Spec->abs2rel( $path, $base ) ;
193 If $base is not present or '', then Cwd::cwd() is used. If $base is
195 relative, then it is converted to absolute form using "rel2abs()".
196 This means that it is taken to be relative to Cwd::cwd().
197 On systems with the concept of volume, if $path and $base appear to
199 be on two different volumes, we will not attempt to resolve the two
200 paths, and we will instead simply return $path. Note that previous
201 versions of this module ignored the volume of $base, which resulted
202 in garbage results part of the time.
203 On systems that have a grammar that indicates filenames, this ignores
205 the $base filename as well. Otherwise all path components are assumed
206 to be directories.
207 If $path is relative, it is converted to absolute form using
209 "rel2abs()". This means that it is taken to be relative to
210 Cwd::cwd().
211 No checks against the filesystem are made. On VMS, there is
213 interaction with the working environment, as logicals and macros are
214 expanded.
215 Based on code written by Shigio Yamaguchi.
217 rel2abs()
219 Converts a relative path to an absolute path.
220 $abs_path = File::Spec->rel2abs( $path ) ;
222 $abs_path = File::Spec->rel2abs( $path, $base ) ;
223 If $base is not present or '', then Cwd::cwd() is used. If $base is
225 relative, then it is converted to absolute form using "rel2abs()".
226 This means that it is taken to be relative to Cwd::cwd().
227 On systems with the concept of volume, if $path and $base appear to
229 be on two different volumes, we will not attempt to resolve the two
230 paths, and we will instead simply return $path. Note that previous
231 versions of this module ignored the volume of $base, which resulted
232 in garbage results part of the time.
233 On systems that have a grammar that indicates filenames, this ignores
235 the $base filename as well. Otherwise all path components are assumed
236 to be directories.
237 If $path is absolute, it is cleaned up and returned using
239 "canonpath".
240 No checks against the filesystem are made. On VMS, there is
242 interaction with the working environment, as logicals and macros are
243 expanded.
244 Based on code written by Shigio Yamaguchi.
246 For further information, please see File::Spec::Unix, File::Spec::Mac,
248 File::Spec::OS2, File::Spec::Win32, or File::Spec::VMS.
249
251 File::Spec::Unix, File::Spec::Mac, File::Spec::OS2, File::Spec::Win32,
252 File::Spec::VMS, File::Spec::Functions, ExtUtils::MakeMaker
253
255 Currently maintained by Ken Williams "<KWILLIAMS@cpan.org>".
256 The vast majority of the code was written by Kenneth Albanowski
258 "<kjahds@kjahds.com>", Andy Dougherty "<doughera@lafayette.edu>",
259 Andreas König "<A.Koenig@franz.ww.TU-Berlin.DE>", Tim Bunce
260 "<Tim.Bunce@ig.co.uk>". VMS support by Charles Bailey
261 "<bailey@newman.upenn.edu>". OS/2 support by Ilya Zakharevich
262 "<ilya@math.ohio-state.edu>". Mac support by Paul Schinder
263 "<schinder@pobox.com>", and Thomas Wegner "<wegner_thomas@yahoo.com>".
264 abs2rel() and rel2abs() written by Shigio Yamaguchi
265 "<shigio@tamacom.com>", modified by Barrie Slaymaker
266 "<barries@slaysys.com>". splitpath(), splitdir(), catpath() and
267 catdir() by Barrie Slaymaker.
268
270 Copyright (c) 2004-2013 by the Perl 5 Porters. All rights reserved.
271 This program is free software; you can redistribute it and/or modify it
273 under the same terms as Perl itself.
274perl v5.32.0 2020-11-05 File::Spec(3)