Debian Codegraph @

upstream/opensuse-tumbleweed/man3/File::Spec::Mac.3pm

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