Debian Codegraph @

upstream/debian-unstable/man3/File::Spec::Mac.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::Mac 3perl"
58 .TH File::Spec::Mac 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::Mac \- File::Spec for Mac OS (Classic)
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& require File::Spec::Mac; # Done internally by File::Spec if needed
69 .Ve
70 .SH DESCRIPTION
71 .IX Header "DESCRIPTION"
72 Methods for manipulating file specifications.
73 .SH METHODS
74 .IX Header "METHODS"
75 .IP canonpath 2
76 .IX Item "canonpath"
77 On Mac OS, there's nothing to be done. Returns what it's given.
78 .IP \fBcatdir()\fR 2
79 .IX Item "catdir()"
80 Concatenate two or more directory names to form a path separated by colons
81 (":") ending with a directory. Resulting paths are \fBrelative\fR by default,
82 but can be forced to be absolute (but avoid this, see below). Automatically
83 puts a trailing ":" on the end of the complete path, because that's what's
84 done in MacPerl's environment and helps to distinguish a file path from a
85 directory path.
86 .Sp
87 \&\fBIMPORTANT NOTE:\fR Beginning with version 1.3 of this module, the resulting
88 path is relative by default and \fInot\fR absolute. This decision was made due
89 to portability reasons. Since \f(CW\*(C`File::Spec\->catdir()\*(C'\fR returns relative paths
90 on all other operating systems, it will now also follow this convention on Mac
91 OS. Note that this may break some existing scripts.
92 .Sp
93 The intended purpose of this routine is to concatenate \fIdirectory names\fR.
94 But because of the nature of Macintosh paths, some additional possibilities
95 are allowed to make using this routine give reasonable results for some
96 common situations. In other words, you are also allowed to concatenate
97 \&\fIpaths\fR instead of directory names (strictly speaking, a string like ":a"
98 is a path, but not a name, since it contains a punctuation character ":").
99 .Sp
100 So, beside calls like
101 .Sp
102 .Vb 3
103 \& catdir("a") = ":a:"
104 \& catdir("a","b") = ":a:b:"
105 \& catdir() = "" (special case)
106 .Ve
107 .Sp
108 calls like the following
109 .Sp
110 .Vb 5
111 \& catdir(":a:") = ":a:"
112 \& catdir(":a","b") = ":a:b:"
113 \& catdir(":a:","b") = ":a:b:"
114 \& catdir(":a:",":b:") = ":a:b:"
115 \& catdir(":") = ":"
116 .Ve
117 .Sp
118 are allowed.
119 .Sp
120 Here are the rules that are used in \f(CWcatdir()\fR; note that we try to be as
121 compatible as possible to Unix:
122 .RS 2
123 .IP 1. 2
124 The resulting path is relative by default, i.e. the resulting path will have a
125 leading colon.
126 .IP 2. 2
127 A trailing colon is added automatically to the resulting path, to denote a
128 directory.
129 .IP 3. 2
130 Generally, each argument has one leading ":" and one trailing ":"
131 removed (if any). They are then joined together by a ":". Special
132 treatment applies for arguments denoting updir paths like "::lib:",
133 see (4), or arguments consisting solely of colons ("colon paths"),
134 see (5).
135 .IP 4. 2
136 When an updir path like ":::lib::" is passed as argument, the number
137 of directories to climb up is handled correctly, not removing leading
138 or trailing colons when necessary. E.g.
139 .Sp
140 .Vb 2
141 \& catdir(":::a","::b","c") = ":::a::b:c:"
142 \& catdir(":::a::","::b","c") = ":::a:::b:c:"
143 .Ve
144 .IP 5. 2
145 Adding a colon ":" or empty string "" to a path at \fIany\fR position
146 doesn't alter the path, i.e. these arguments are ignored. (When a ""
147 is passed as the first argument, it has a special meaning, see
148 (6)). This way, a colon ":" is handled like a "." (curdir) on Unix,
149 while an empty string "" is generally ignored (see
150 "\fBcanonpath()\fR" in File::Spec::Unix ). Likewise, a "::" is handled like a ".."
151 (updir), and a ":::" is handled like a "../.." etc. E.g.
152 .Sp
153 .Vb 2
154 \& catdir("a",":",":","b") = ":a:b:"
155 \& catdir("a",":","::",":b") = ":a::b:"
156 .Ve
157 .IP 6. 2
158 If the first argument is an empty string "" or is a volume name, i.e. matches
159 the pattern /^[^:]+:/, the resulting path is \fBabsolute\fR.
160 .IP 7. 2
161 Passing an empty string "" as the first argument to \f(CWcatdir()\fR is
162 like passing\f(CW\*(C`File::Spec\->rootdir()\*(C'\fR as the first argument, i.e.
163 .Sp
164 .Vb 1
165 \& catdir("","a","b") is the same as
166 \&
167 \& catdir(rootdir(),"a","b").
168 .Ve
169 .Sp
170 This is true on Unix, where \f(CW\*(C`catdir("","a","b")\*(C'\fR yields "/a/b" and
171 \&\f(CWrootdir()\fR is "/". Note that \f(CWrootdir()\fR on Mac OS is the startup
172 volume, which is the closest in concept to Unix' "/". This should help
173 to run existing scripts originally written for Unix.
174 .IP 8. 2
175 For absolute paths, some cleanup is done, to ensure that the volume
176 name isn't immediately followed by updirs. This is invalid, because
177 this would go beyond "root". Generally, these cases are handled like
178 their Unix counterparts:
179 .Sp
180 .Vb 10
181 \& Unix:
182 \& Unix\->catdir("","") = "/"
183 \& Unix\->catdir("",".") = "/"
184 \& Unix\->catdir("","..") = "/" # can\*(Aqt go
185 \& # beyond root
186 \& Unix\->catdir("",".","..","..","a") = "/a"
187 \& Mac:
188 \& Mac\->catdir("","") = rootdir() # (e.g. "HD:")
189 \& Mac\->catdir("",":") = rootdir()
190 \& Mac\->catdir("","::") = rootdir() # can\*(Aqt go
191 \& # beyond root
192 \& Mac\->catdir("",":","::","::","a") = rootdir() . "a:"
193 \& # (e.g. "HD:a:")
194 .Ve
195 .Sp
196 However, this approach is limited to the first arguments following
197 "root" (again, see "\fBcanonpath()\fR" in File::Spec::Unix. If there are more
198 arguments that move up the directory tree, an invalid path going
199 beyond root can be created.
200 .RE
201 .RS 2
202 .Sp
203 As you've seen, you can force \f(CWcatdir()\fR to create an absolute path
204 by passing either an empty string or a path that begins with a volume
205 name as the first argument. However, you are strongly encouraged not
206 to do so, since this is done only for backward compatibility. Newer
207 versions of File::Spec come with a method called \f(CWcatpath()\fR (see
208 below), that is designed to offer a portable solution for the creation
209 of absolute paths. It takes volume, directory and file portions and
210 returns an entire path. While \f(CWcatdir()\fR is still suitable for the
211 concatenation of \fIdirectory names\fR, you are encouraged to use
212 \&\f(CWcatpath()\fR to concatenate \fIvolume names\fR and \fIdirectory
213 paths\fR. E.g.
214 .Sp
215 .Vb 2
216 \& $dir = File::Spec\->catdir("tmp","sources");
217 \& $abs_path = File::Spec\->catpath("MacintoshHD:", $dir,"");
218 .Ve
219 .Sp
220 yields
221 .Sp
222 .Vb 1
223 \& "MacintoshHD:tmp:sources:" .
224 .Ve
225 .RE
226 .IP catfile 2
227 .IX Item "catfile"
228 Concatenate one or more directory names and a filename to form a
229 complete path ending with a filename. Resulting paths are \fBrelative\fR
230 by default, but can be forced to be absolute (but avoid this).
231 .Sp
232 \&\fBIMPORTANT NOTE:\fR Beginning with version 1.3 of this module, the
233 resulting path is relative by default and \fInot\fR absolute. This
234 decision was made due to portability reasons. Since
235 \&\f(CW\*(C`File::Spec\->catfile()\*(C'\fR returns relative paths on all other
236 operating systems, it will now also follow this convention on Mac OS.
237 Note that this may break some existing scripts.
238 .Sp
239 The last argument is always considered to be the file portion. Since
240 \&\f(CWcatfile()\fR uses \f(CWcatdir()\fR (see above) for the concatenation of the
241 directory portions (if any), the following with regard to relative and
242 absolute paths is true:
243 .Sp
244 .Vb 2
245 \& catfile("") = ""
246 \& catfile("file") = "file"
247 .Ve
248 .Sp
249 but
250 .Sp
251 .Vb 3
252 \& catfile("","") = rootdir() # (e.g. "HD:")
253 \& catfile("","file") = rootdir() . file # (e.g. "HD:file")
254 \& catfile("HD:","file") = "HD:file"
255 .Ve
256 .Sp
257 This means that \f(CWcatdir()\fR is called only when there are two or more
258 arguments, as one might expect.
259 .Sp
260 Note that the leading ":" is removed from the filename, so that
261 .Sp
262 .Vb 1
263 \& catfile("a","b","file") = ":a:b:file" and
264 \&
265 \& catfile("a","b",":file") = ":a:b:file"
266 .Ve
267 .Sp
268 give the same answer.
269 .Sp
270 To concatenate \fIvolume names\fR, \fIdirectory paths\fR and \fIfilenames\fR,
271 you are encouraged to use \f(CWcatpath()\fR (see below).
272 .IP curdir 2
273 .IX Item "curdir"
274 Returns a string representing the current directory. On Mac OS, this is ":".
275 .IP devnull 2
276 .IX Item "devnull"
277 Returns a string representing the null device. On Mac OS, this is "Dev:Null".
278 .IP rootdir 2
279 .IX Item "rootdir"
280 Returns the empty string. Mac OS has no real root directory.
281 .IP tmpdir 2
282 .IX Item "tmpdir"
283 Returns the contents of \f(CW$ENV\fR{TMPDIR}, if that directory exits or the
284 current working directory otherwise. Under MacPerl, \f(CW$ENV\fR{TMPDIR} will
285 contain a path like "MacintoshHD:Temporary Items:", which is a hidden
286 directory on your startup volume.
287 .IP updir 2
288 .IX Item "updir"
289 Returns a string representing the parent directory. On Mac OS, this is "::".
290 .IP file_name_is_absolute 2
291 .IX Item "file_name_is_absolute"
292 Takes as argument a path and returns true, if it is an absolute path.
293 If the path has a leading ":", it's a relative path. Otherwise, it's an
294 absolute path, unless the path doesn't contain any colons, i.e. it's a name
295 like "a". In this particular case, the path is considered to be relative
296 (i.e. it is considered to be a filename). Use ":" in the appropriate place
297 in the path if you want to distinguish unambiguously. As a special case,
298 the filename '' is always considered to be absolute. Note that with version
299 1.2 of File::Spec::Mac, this does no longer consult the local filesystem.
300 .Sp
301 E.g.
302 .Sp
303 .Vb 5
304 \& File::Spec\->file_name_is_absolute("a"); # false (relative)
305 \& File::Spec\->file_name_is_absolute(":a:b:"); # false (relative)
306 \& File::Spec\->file_name_is_absolute("MacintoshHD:");
307 \& # true (absolute)
308 \& File::Spec\->file_name_is_absolute(""); # true (absolute)
309 .Ve
310 .IP path 2
311 .IX Item "path"
312 Returns the null list for the MacPerl application, since the concept is
313 usually meaningless under Mac OS. But if you're using the MacPerl tool under
314 MPW, it gives back \f(CW$ENV\fR{Commands} suitably split, as is done in
315 :lib:ExtUtils:MM_Mac.pm.
316 .IP splitpath 2
317 .IX Item "splitpath"
318 .Vb 3
319 \& ($volume,$directories,$file) = File::Spec\->splitpath( $path );
320 \& ($volume,$directories,$file) = File::Spec\->splitpath( $path,
321 \& $no_file );
322 .Ve
323 .Sp
324 Splits a path into volume, directory, and filename portions.
325 .Sp
326 On Mac OS, assumes that the last part of the path is a filename unless
327 \&\f(CW$no_file\fR is true or a trailing separator ":" is present.
328 .Sp
329 The volume portion is always returned with a trailing ":". The directory portion
330 is always returned with a leading (to denote a relative path) and a trailing ":"
331 (to denote a directory). The file portion is always returned \fIwithout\fR a leading ":".
332 Empty portions are returned as empty string ''.
333 .Sp
334 The results can be passed to \f(CWcatpath()\fR to get back a path equivalent to
335 (usually identical to) the original path.
336 .IP splitdir 2
337 .IX Item "splitdir"
338 The opposite of \f(CWcatdir()\fR.
339 .Sp
340 .Vb 1
341 \& @dirs = File::Spec\->splitdir( $directories );
342 .Ve
343 .Sp
344 \&\f(CW$directories\fR should be only the directory portion of the path on systems
345 that have the concept of a volume or that have path syntax that differentiates
346 files from directories. Consider using \f(CWsplitpath()\fR otherwise.
347 .Sp
348 Unlike just splitting the directories on the separator, empty directory names
349 (\f(CW""\fR) can be returned. Since \f(CWcatdir()\fR on Mac OS always appends a trailing
350 colon to distinguish a directory path from a file path, a single trailing colon
351 will be ignored, i.e. there's no empty directory name after it.
352 .Sp
353 Hence, on Mac OS, both
354 .Sp
355 .Vb 2
356 \& File::Spec\->splitdir( ":a:b::c:" ); and
357 \& File::Spec\->splitdir( ":a:b::c" );
358 .Ve
359 .Sp
360 yield:
361 .Sp
362 .Vb 1
363 \& ( "a", "b", "::", "c")
364 .Ve
365 .Sp
366 while
367 .Sp
368 .Vb 1
369 \& File::Spec\->splitdir( ":a:b::c::" );
370 .Ve
371 .Sp
372 yields:
373 .Sp
374 .Vb 1
375 \& ( "a", "b", "::", "c", "::")
376 .Ve
377 .IP catpath 2
378 .IX Item "catpath"
379 .Vb 1
380 \& $path = File::Spec\->catpath($volume,$directory,$file);
381 .Ve
382 .Sp
383 Takes volume, directory and file portions and returns an entire path. On Mac OS,
384 \&\f(CW$volume\fR, \f(CW$directory\fR and \f(CW$file\fR are concatenated. A ':' is inserted if need be. You
385 may pass an empty string for each portion. If all portions are empty, the empty
386 string is returned. If \f(CW$volume\fR is empty, the result will be a relative path,
387 beginning with a ':'. If \f(CW$volume\fR and \f(CW$directory\fR are empty, a leading ":" (if any)
388 is removed form \f(CW$file\fR and the remainder is returned. If \f(CW$file\fR is empty, the
389 resulting path will have a trailing ':'.
390 .IP abs2rel 2
391 .IX Item "abs2rel"
392 Takes a destination path and an optional base path and returns a relative path
393 from the base path to the destination path:
394 .Sp
395 .Vb 2
396 \& $rel_path = File::Spec\->abs2rel( $path ) ;
397 \& $rel_path = File::Spec\->abs2rel( $path, $base ) ;
398 .Ve
399 .Sp
400 Note that both paths are assumed to have a notation that distinguishes a
401 directory path (with trailing ':') from a file path (without trailing ':').
402 .Sp
403 If \f(CW$base\fR is not present or '', then the current working directory is used.
404 If \f(CW$base\fR is relative, then it is converted to absolute form using \f(CWrel2abs()\fR.
405 This means that it is taken to be relative to the current working directory.
406 .Sp
407 If \f(CW$path\fR and \f(CW$base\fR appear to be on two different volumes, we will not
408 attempt to resolve the two paths, and we will instead simply return
409 \&\f(CW$path\fR. Note that previous versions of this module ignored the volume
410 of \f(CW$base\fR, which resulted in garbage results part of the time.
411 .Sp
412 If \f(CW$base\fR doesn't have a trailing colon, the last element of \f(CW$base\fR is
413 assumed to be a filename. This filename is ignored. Otherwise all path
414 components are assumed to be directories.
415 .Sp
416 If \f(CW$path\fR is relative, it is converted to absolute form using \f(CWrel2abs()\fR.
417 This means that it is taken to be relative to the current working directory.
418 .Sp
419 Based on code written by Shigio Yamaguchi.
420 .IP rel2abs 2
421 .IX Item "rel2abs"
422 Converts a relative path to an absolute path:
423 .Sp
424 .Vb 2
425 \& $abs_path = File::Spec\->rel2abs( $path ) ;
426 \& $abs_path = File::Spec\->rel2abs( $path, $base ) ;
427 .Ve
428 .Sp
429 Note that both paths are assumed to have a notation that distinguishes a
430 directory path (with trailing ':') from a file path (without trailing ':').
431 .Sp
432 If \f(CW$base\fR is not present or '', then \f(CW$base\fR is set to the current working
433 directory. If \f(CW$base\fR is relative, then it is converted to absolute form
434 using \f(CWrel2abs()\fR. This means that it is taken to be relative to the
435 current working directory.
436 .Sp
437 If \f(CW$base\fR doesn't have a trailing colon, the last element of \f(CW$base\fR is
438 assumed to be a filename. This filename is ignored. Otherwise all path
439 components are assumed to be directories.
440 .Sp
441 If \f(CW$path\fR is already absolute, it is returned and \f(CW$base\fR is ignored.
442 .Sp
443 Based on code written by Shigio Yamaguchi.
444 .SH AUTHORS
445 .IX Header "AUTHORS"
446 See the authors list in \fIFile::Spec\fR. Mac OS support by Paul Schinder
447 <[email protected]> and Thomas Wegner <[email protected]>.
448 .SH COPYRIGHT
449 .IX Header "COPYRIGHT"
450 Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.
451 .PP
452 This program is free software; you can redistribute it and/or modify
453 it under the same terms as Perl itself.
454 .SH "SEE ALSO"
455 .IX Header "SEE ALSO"
456 See File::Spec and File::Spec::Unix. This package overrides the
457 implementation of these methods, not the semantics.