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

NAME

6       File::Spec - portably perform operations on file names
7

SYNOPSIS

9               use File::Spec;
10
11               my $x = File::Spec->catfile('a', 'b', 'c');
12
13       which returns 'a/b/c' under Unix. Or:
14
15               use File::Spec::Functions;
16
17               my $x = catfile('a', 'b', 'c');
18

DESCRIPTION

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
28       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
32               File::Spec::Unix
33               File::Spec::Mac
34               File::Spec::OS2
35               File::Spec::Win32
36               File::Spec::VMS
37
38       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
43       Since File::Spec is object oriented, subroutines should not be called
44       directly, as in:
45
46               File::Spec::catfile('a','b');
47
48       but rather as class methods:
49
50               File::Spec->catfile('a','b');
51
52       For simple uses, File::Spec::Functions provides convenient functional
53       forms of these methods.
54

METHODS

56       canonpath
57         No physical check on the filesystem, but a logical cleanup of a path.
58
59             $cpath = File::Spec->canonpath( $path ) ;
60
61         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
68       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
75             $path = File::Spec->catdir( @directories );
76
77       catfile
78         Concatenate one or more directory names and a filename to form a
79         complete path ending with a filename
80
81             $path = File::Spec->catfile( @directories, $filename );
82
83       curdir
84         Returns a string representation of the current directory.
85
86             $curdir = File::Spec->curdir();
87
88       devnull
89         Returns a string representation of the null device.
90
91             $devnull = File::Spec->devnull();
92
93       rootdir
94         Returns a string representation of the root directory.
95
96             $rootdir = File::Spec->rootdir();
97
98       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
105             $tmpdir = File::Spec->tmpdir();
106
107       updir
108         Returns a string representation of the parent directory.
109
110             $updir = File::Spec->updir();
111
112       no_upwards
113         Given a list of files in a directory (such as from readdir()), strip
114         out '.' and '..'.
115
116         SECURITY NOTE: This does NOT filter paths containing '..', like
117         '../../../../etc/passwd', only literal matches to '.' and '..'.
118
119             @paths = File::Spec->no_upwards( readdir $dirhandle );
120
121       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
126             $is_case_tolerant = File::Spec->case_tolerant();
127
128       file_name_is_absolute
129         Takes as its argument a path, and returns true if it is an absolute
130         path.
131
132             $is_absolute = File::Spec->file_name_is_absolute( $path );
133
134         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
138       path
139         Takes no argument.  Returns the environment variable "PATH" (or the
140         local platform's equivalent) as a list.
141
142             @PATH = File::Spec->path();
143
144       join
145         join is the same as catfile.
146
147       splitpath
148         Splits a path in to volume, directory, and filename portions. On
149         systems with no concept of volume, returns '' for volume.
150
151             ($volume,$directories,$file) =
152                                File::Spec->splitpath( $path );
153             ($volume,$directories,$file) =
154                                File::Spec->splitpath( $path, $no_file );
155
156         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
161         The directory portion may or may not be returned with a trailing '/'.
162
163         The results can be passed to "catpath()" to get back a path
164         equivalent to (usually identical to) the original path.
165
166       splitdir
167         The opposite of "catdir".
168
169             @dirs = File::Spec->splitdir( $directories );
170
171         $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
175         Unlike just splitting the directories on the separator, empty
176         directory names ('') can be returned, because these are significant
177         on some OSes.
178
179       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
185             $full_path = File::Spec->catpath( $volume, $directory, $file );
186
187       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
191             $rel_path = File::Spec->abs2rel( $path ) ;
192             $rel_path = File::Spec->abs2rel( $path, $base ) ;
193
194         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
198         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
204         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
208         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
212         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
216         Based on code written by Shigio Yamaguchi.
217
218       rel2abs()
219         Converts a relative path to an absolute path.
220
221             $abs_path = File::Spec->rel2abs( $path ) ;
222             $abs_path = File::Spec->rel2abs( $path, $base ) ;
223
224         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
228         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
234         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
238         If $path is absolute, it is cleaned up and returned using
239         "canonpath".
240
241         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
245         Based on code written by Shigio Yamaguchi.
246
247       For further information, please see File::Spec::Unix, File::Spec::Mac,
248       File::Spec::OS2, File::Spec::Win32, or File::Spec::VMS.
249

SEE ALSO

251       File::Spec::Unix, File::Spec::Mac, File::Spec::OS2, File::Spec::Win32,
252       File::Spec::VMS, File::Spec::Functions, ExtUtils::MakeMaker
253

AUTHOR

255       Maintained by perl5-porters <perl5-porters@perl.org>.
256
257       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
272       This program is free software; you can redistribute it and/or modify it
273       under the same terms as Perl itself.
274
275
276
277perl v5.38.0                      2023-07-21                     File::Spec(3)
Impressum