Debian Codegraph @

upstream/debian-unstable/man3/File::Spec.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "File::Spec 3perl"
58 .TH File::Spec 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 File::Spec \- portably perform operations on file names
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use File::Spec;
69 \&
70 \& my $x = File::Spec\->catfile(\*(Aqa\*(Aq, \*(Aqb\*(Aq, \*(Aqc\*(Aq);
71 .Ve
72 .PP
73 which returns 'a/b/c' under Unix. Or:
74 .PP
75 .Vb 1
76 \& use File::Spec::Functions;
77 \&
78 \& my $x = catfile(\*(Aqa\*(Aq, \*(Aqb\*(Aq, \*(Aqc\*(Aq);
79 .Ve
80 .SH DESCRIPTION
81 .IX Header "DESCRIPTION"
82 This module is designed to support operations commonly performed on file
83 specifications (usually called "file names", but not to be confused with the
84 contents of a file, or Perl's file handles), such as concatenating several
85 directory and file names into a single path, or determining whether a path
86 is rooted. It is based on code directly taken from MakeMaker 5.17, code
87 written by Andreas König, Andy Dougherty, Charles Bailey, Ilya
88 Zakharevich, Paul Schinder, and others.
89 .PP
90 Since these functions are different for most operating systems, each set of
91 OS specific routines is available in a separate module, including:
92 .PP
93 .Vb 5
94 \& File::Spec::Unix
95 \& File::Spec::Mac
96 \& File::Spec::OS2
97 \& File::Spec::Win32
98 \& File::Spec::VMS
99 .Ve
100 .PP
101 The module appropriate for the current OS is automatically loaded by
102 File::Spec. Since some modules (like VMS) make use of facilities available
103 only under that OS, it may not be possible to load all modules under all
104 operating systems.
105 .PP
106 Since File::Spec is object oriented, subroutines should not be called directly,
107 as in:
108 .PP
109 .Vb 1
110 \& File::Spec::catfile(\*(Aqa\*(Aq,\*(Aqb\*(Aq);
111 .Ve
112 .PP
113 but rather as class methods:
114 .PP
115 .Vb 1
116 \& File::Spec\->catfile(\*(Aqa\*(Aq,\*(Aqb\*(Aq);
117 .Ve
118 .PP
119 For simple uses, File::Spec::Functions provides convenient functional
120 forms of these methods.
121 .SH METHODS
122 .IX Header "METHODS"
123 .IP canonpath 2
124 .IX Xref "canonpath"
125 .IX Item "canonpath"
126 No physical check on the filesystem, but a logical cleanup of a
127 path.
128 .Sp
129 .Vb 1
130 \& $cpath = File::Spec\->canonpath( $path ) ;
131 .Ve
132 .Sp
133 Note that this does *not* collapse \fIx/../y\fR sections into \fIy\fR. This
134 is by design. If \fI/foo\fR on your system is a symlink to \fI/bar/baz\fR,
135 then \fI/foo/../quux\fR is actually \fI/bar/quux\fR, not \fI/quux\fR as a naive
136 \&\fI../\fR\-removal would give you. If you want to do this kind of
137 processing, you probably want \f(CW\*(C`Cwd\*(C'\fR's \f(CWrealpath()\fR function to
138 actually traverse the filesystem cleaning up paths like this.
139 .IP catdir 2
140 .IX Xref "catdir"
141 .IX Item "catdir"
142 Concatenate two or more directory names to form a complete path ending
143 with a directory. But remove the trailing slash from the resulting
144 string, because it doesn't look good, isn't necessary and confuses
145 OS/2. Of course, if this is the root directory, don't cut off the
146 trailing slash :\-)
147 .Sp
148 .Vb 1
149 \& $path = File::Spec\->catdir( @directories );
150 .Ve
151 .IP catfile 2
152 .IX Xref "catfile"
153 .IX Item "catfile"
154 Concatenate one or more directory names and a filename to form a
155 complete path ending with a filename
156 .Sp
157 .Vb 1
158 \& $path = File::Spec\->catfile( @directories, $filename );
159 .Ve
160 .IP curdir 2
161 .IX Xref "curdir"
162 .IX Item "curdir"
163 Returns a string representation of the current directory.
164 .Sp
165 .Vb 1
166 \& $curdir = File::Spec\->curdir();
167 .Ve
168 .IP devnull 2
169 .IX Xref "devnull"
170 .IX Item "devnull"
171 Returns a string representation of the null device.
172 .Sp
173 .Vb 1
174 \& $devnull = File::Spec\->devnull();
175 .Ve
176 .IP rootdir 2
177 .IX Xref "rootdir"
178 .IX Item "rootdir"
179 Returns a string representation of the root directory.
180 .Sp
181 .Vb 1
182 \& $rootdir = File::Spec\->rootdir();
183 .Ve
184 .IP tmpdir 2
185 .IX Xref "tmpdir"
186 .IX Item "tmpdir"
187 Returns a string representation of the first writable directory from a
188 list of possible temporary directories. Returns the current directory
189 if no writable temporary directories are found. The list of directories
190 checked depends on the platform; e.g. File::Spec::Unix checks \f(CW$ENV{TMPDIR}\fR
191 (unless taint is on) and \fI/tmp\fR.
192 .Sp
193 .Vb 1
194 \& $tmpdir = File::Spec\->tmpdir();
195 .Ve
196 .IP updir 2
197 .IX Xref "updir"
198 .IX Item "updir"
199 Returns a string representation of the parent directory.
200 .Sp
201 .Vb 1
202 \& $updir = File::Spec\->updir();
203 .Ve
204 .IP no_upwards 2
205 .IX Item "no_upwards"
206 Given a list of files in a directory (such as from \f(CWreaddir()\fR),
207 strip out \f(CW\*(Aq.\*(Aq\fR and \f(CW\*(Aq..\*(Aq\fR.
208 .Sp
209 \&\fBSECURITY NOTE:\fR This does NOT filter paths containing \f(CW\*(Aq..\*(Aq\fR, like
210 \&\f(CW\*(Aq../../../../etc/passwd\*(Aq\fR, only literal matches to \f(CW\*(Aq.\*(Aq\fR and \f(CW\*(Aq..\*(Aq\fR.
211 .Sp
212 .Vb 1
213 \& @paths = File::Spec\->no_upwards( readdir $dirhandle );
214 .Ve
215 .IP case_tolerant 2
216 .IX Item "case_tolerant"
217 Returns a true or false value indicating, respectively, that alphabetic
218 case is not or is significant when comparing file specifications.
219 Cygwin and Win32 accept an optional drive argument.
220 .Sp
221 .Vb 1
222 \& $is_case_tolerant = File::Spec\->case_tolerant();
223 .Ve
224 .IP file_name_is_absolute 2
225 .IX Item "file_name_is_absolute"
226 Takes as its argument a path, and returns true if it is an absolute path.
227 .Sp
228 .Vb 1
229 \& $is_absolute = File::Spec\->file_name_is_absolute( $path );
230 .Ve
231 .Sp
232 This does not consult the local filesystem on Unix, Win32, OS/2, or
233 Mac OS (Classic). It does consult the working environment for VMS
234 (see "file_name_is_absolute" in File::Spec::VMS).
235 .IP path 2
236 .IX Xref "path"
237 .IX Item "path"
238 Takes no argument. Returns the environment variable \f(CW\*(C`PATH\*(C'\fR (or the local
239 platform's equivalent) as a list.
240 .Sp
241 .Vb 1
242 \& @PATH = File::Spec\->path();
243 .Ve
244 .IP join 2
245 .IX Xref "join, path"
246 .IX Item "join"
247 join is the same as catfile.
248 .IP splitpath 2
249 .IX Xref "splitpath split, path"
250 .IX Item "splitpath"
251 Splits a path in to volume, directory, and filename portions. On systems
252 with no concept of volume, returns '' for volume.
253 .Sp
254 .Vb 4
255 \& ($volume,$directories,$file) =
256 \& File::Spec\->splitpath( $path );
257 \& ($volume,$directories,$file) =
258 \& File::Spec\->splitpath( $path, $no_file );
259 .Ve
260 .Sp
261 For systems with no syntax differentiating filenames from directories,
262 assumes that the last file is a path unless \f(CW$no_file\fR is true or a
263 trailing separator or \fI/.\fR or \fI/..\fR is present. On Unix, this means that \f(CW$no_file\fR
264 true makes this return ( '', \f(CW$path\fR, '' ).
265 .Sp
266 The directory portion may or may not be returned with a trailing '/'.
267 .Sp
268 The results can be passed to "\fBcatpath()\fR" to get back a path equivalent to
269 (usually identical to) the original path.
270 .IP splitdir 2
271 .IX Xref "splitdir split, dir"
272 .IX Item "splitdir"
273 The opposite of "catdir".
274 .Sp
275 .Vb 1
276 \& @dirs = File::Spec\->splitdir( $directories );
277 .Ve
278 .Sp
279 \&\f(CW$directories\fR must be only the directory portion of the path on systems
280 that have the concept of a volume or that have path syntax that differentiates
281 files from directories.
282 .Sp
283 Unlike just splitting the directories on the separator, empty
284 directory names (\f(CW\*(Aq\*(Aq\fR) can be returned, because these are significant
285 on some OSes.
286 .IP \fBcatpath()\fR 2
287 .IX Item "catpath()"
288 Takes volume, directory and file portions and returns an entire path. Under
289 Unix, \f(CW$volume\fR is ignored, and directory and file are concatenated. A '/' is
290 inserted if need be. On other OSes, \f(CW$volume\fR is significant.
291 .Sp
292 .Vb 1
293 \& $full_path = File::Spec\->catpath( $volume, $directory, $file );
294 .Ve
295 .IP abs2rel 2
296 .IX Xref "abs2rel absolute, path relative, path"
297 .IX Item "abs2rel"
298 Takes a destination path and an optional base path returns a relative path
299 from the base path to the destination path:
300 .Sp
301 .Vb 2
302 \& $rel_path = File::Spec\->abs2rel( $path ) ;
303 \& $rel_path = File::Spec\->abs2rel( $path, $base ) ;
304 .Ve
305 .Sp
306 If \f(CW$base\fR is not present or '', then \fBCwd::cwd()\fR is used. If \f(CW$base\fR is
307 relative, then it is converted to absolute form using
308 "\fBrel2abs()\fR". This means that it is taken to be relative to
309 \&\fBCwd::cwd()\fR.
310 .Sp
311 On systems with the concept of volume, if \f(CW$path\fR and \f(CW$base\fR appear to be
312 on two different volumes, we will not attempt to resolve the two
313 paths, and we will instead simply return \f(CW$path\fR. Note that previous
314 versions of this module ignored the volume of \f(CW$base\fR, which resulted in
315 garbage results part of the time.
316 .Sp
317 On systems that have a grammar that indicates filenames, this ignores the
318 \&\f(CW$base\fR filename as well. Otherwise all path components are assumed to be
319 directories.
320 .Sp
321 If \f(CW$path\fR is relative, it is converted to absolute form using "\fBrel2abs()\fR".
322 This means that it is taken to be relative to \fBCwd::cwd()\fR.
323 .Sp
324 No checks against the filesystem are made. On VMS, there is
325 interaction with the working environment, as logicals and
326 macros are expanded.
327 .Sp
328 Based on code written by Shigio Yamaguchi.
329 .IP \fBrel2abs()\fR 2
330 .IX Xref "rel2abs absolute, path relative, path"
331 .IX Item "rel2abs()"
332 Converts a relative path to an absolute path.
333 .Sp
334 .Vb 2
335 \& $abs_path = File::Spec\->rel2abs( $path ) ;
336 \& $abs_path = File::Spec\->rel2abs( $path, $base ) ;
337 .Ve
338 .Sp
339 If \f(CW$base\fR is not present or '', then \fBCwd::cwd()\fR is used. If \f(CW$base\fR is relative,
340 then it is converted to absolute form using "\fBrel2abs()\fR". This means that it
341 is taken to be relative to \fBCwd::cwd()\fR.
342 .Sp
343 On systems with the concept of volume, if \f(CW$path\fR and \f(CW$base\fR appear to be
344 on two different volumes, we will not attempt to resolve the two
345 paths, and we will instead simply return \f(CW$path\fR. Note that previous
346 versions of this module ignored the volume of \f(CW$base\fR, which resulted in
347 garbage results part of the time.
348 .Sp
349 On systems that have a grammar that indicates filenames, this ignores the
350 \&\f(CW$base\fR filename as well. Otherwise all path components are assumed to be
351 directories.
352 .Sp
353 If \f(CW$path\fR is absolute, it is cleaned up and returned using "canonpath".
354 .Sp
355 No checks against the filesystem are made. On VMS, there is
356 interaction with the working environment, as logicals and
357 macros are expanded.
358 .Sp
359 Based on code written by Shigio Yamaguchi.
360 .PP
361 For further information, please see File::Spec::Unix,
362 File::Spec::Mac, File::Spec::OS2, File::Spec::Win32, or
363 File::Spec::VMS.
364 .SH "SEE ALSO"
365 .IX Header "SEE ALSO"
366 File::Spec::Unix, File::Spec::Mac, File::Spec::OS2,
367 File::Spec::Win32, File::Spec::VMS, File::Spec::Functions,
368 ExtUtils::MakeMaker
369 .SH AUTHOR
370 .IX Header "AUTHOR"
371 Maintained by perl5\-porters <\fIperl5\[email protected]\fR>.
372 .PP
373 The vast majority of the code was written by
374 Kenneth Albanowski \f(CW\*(C`<[email protected]>\*(C'\fR,
375 Andy Dougherty \f(CW\*(C`<[email protected]>\*(C'\fR,
376 Andreas König \f(CW\*(C`<[email protected]\-Berlin.DE>\*(C'\fR,
377 Tim Bunce \f(CW\*(C`<[email protected]>\*(C'\fR.
378 VMS support by Charles Bailey \f(CW\*(C`<[email protected]>\*(C'\fR.
379 OS/2 support by Ilya Zakharevich \f(CW\*(C`<[email protected]\-state.edu>\*(C'\fR.
380 Mac support by Paul Schinder \f(CW\*(C`<[email protected]>\*(C'\fR, and
381 Thomas Wegner \f(CW\*(C`<[email protected]>\*(C'\fR.
382 \&\fBabs2rel()\fR and \fBrel2abs()\fR written by Shigio Yamaguchi \f(CW\*(C`<[email protected]>\*(C'\fR,
383 modified by Barrie Slaymaker \f(CW\*(C`<[email protected]>\*(C'\fR.
384 \&\fBsplitpath()\fR, \fBsplitdir()\fR, \fBcatpath()\fR and \fBcatdir()\fR by Barrie Slaymaker.
385 .SH COPYRIGHT
386 .IX Header "COPYRIGHT"
387 Copyright (c) 2004\-2013 by the Perl 5 Porters. All rights reserved.
388 .PP
389 This program is free software; you can redistribute it and/or modify
390 it under the same terms as Perl itself.