Debian Codegraph @

upstream/opensuse-tumbleweed/man3/File::Spec::Unix.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::Unix 3pm"
61 .TH File::Spec::Unix 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::Unix \- File::Spec for Unix, base for other File::Spec modules
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& require File::Spec::Unix; # Done automatically by File::Spec
72 .Ve
73 .SH DESCRIPTION
74 .IX Header "DESCRIPTION"
75 Methods for manipulating file specifications. Other File::Spec
76 modules, such as File::Spec::Mac, inherit from File::Spec::Unix and
77 override specific methods.
78 .SH METHODS
79 .IX Header "METHODS"
80 .IP \fBcanonpath()\fR 2
81 .IX Item "canonpath()"
82 No physical check on the filesystem, but a logical cleanup of a
83 path. On UNIX eliminates successive slashes and successive "/.".
84 .Sp
85 .Vb 1
86 \& $cpath = File::Spec\->canonpath( $path ) ;
87 .Ve
88 .Sp
89 Note that this does *not* collapse \fIx/../y\fR sections into \fIy\fR. This
90 is by design. If \fI/foo\fR on your system is a symlink to \fI/bar/baz\fR,
91 then \fI/foo/../quux\fR is actually \fI/bar/quux\fR, not \fI/quux\fR as a naive
92 \&\fI../\fR\-removal would give you. If you want to do this kind of
93 processing, you probably want \f(CW\*(C`Cwd\*(C'\fR\*(Aqs \f(CWrealpath()\fR function to
94 actually traverse the filesystem cleaning up paths like this.
95 .IP \fBcatdir()\fR 2
96 .IX Item "catdir()"
97 Concatenate two or more directory names to form a complete path ending
98 with a directory. But remove the trailing slash from the resulting
99 string, because it doesn\*(Aqt look good, isn\*(Aqt necessary and confuses
100 OS2. Of course, if this is the root directory, don\*(Aqt cut off the
101 trailing slash :\-)
102 .IP catfile 2
103 .IX Item "catfile"
104 Concatenate one or more directory names and a filename to form a
105 complete path ending with a filename
106 .IP curdir 2
107 .IX Item "curdir"
108 Returns a string representation of the current directory. "." on UNIX.
109 .IP devnull 2
110 .IX Item "devnull"
111 Returns a string representation of the null device. "/dev/null" on UNIX.
112 .IP rootdir 2
113 .IX Item "rootdir"
114 Returns a string representation of the root directory. "/" on UNIX.
115 .IP tmpdir 2
116 .IX Item "tmpdir"
117 Returns a string representation of the first writable directory from
118 the following list or the current directory if none from the list are
119 writable:
120 .Sp
121 .Vb 2
122 \& $ENV{TMPDIR}
123 \& /tmp
124 .Ve
125 .Sp
126 If running under taint mode, and if \f(CW$ENV\fR{TMPDIR}
127 is tainted, it is not used.
128 .IP updir 2
129 .IX Item "updir"
130 Returns a string representation of the parent directory. ".." on UNIX.
131 .IP no_upwards 2
132 .IX Item "no_upwards"
133 Given a list of file names, strip out those that refer to a parent
134 directory. (Does not strip symlinks, only \*(Aq.\*(Aq, \*(Aq..\*(Aq, and equivalents.)
135 .IP case_tolerant 2
136 .IX Item "case_tolerant"
137 Returns a true or false value indicating, respectively, that alphabetic
138 is not or is significant when comparing file specifications.
139 .IP file_name_is_absolute 2
140 .IX Item "file_name_is_absolute"
141 Takes as argument a path and returns true if it is an absolute path.
142 .Sp
143 This does not consult the local filesystem on Unix, Win32, OS/2 or Mac
144 OS (Classic). It does consult the working environment for VMS (see
145 "file_name_is_absolute" in File::Spec::VMS).
146 .IP path 2
147 .IX Item "path"
148 Takes no argument, returns the environment variable PATH as an array.
149 .IP join 2
150 .IX Item "join"
151 join is the same as catfile.
152 .IP splitpath 2
153 .IX Item "splitpath"
154 .Vb 3
155 \& ($volume,$directories,$file) = File::Spec\->splitpath( $path );
156 \& ($volume,$directories,$file) = File::Spec\->splitpath( $path,
157 \& $no_file );
158 .Ve
159 .Sp
160 Splits a path into volume, directory, and filename portions. On systems
161 with no concept of volume, returns \*(Aq\*(Aq for volume.
162 .Sp
163 For systems with no syntax differentiating filenames from directories,
164 assumes that the last file is a path unless \f(CW$no_file\fR is true or a
165 trailing separator or /. or /.. is present. On Unix this means that \f(CW$no_file\fR
166 true makes this return ( \*(Aq\*(Aq, \f(CW$path\fR, \*(Aq\*(Aq ).
167 .Sp
168 The directory portion may or may not be returned with a trailing \*(Aq/\*(Aq.
169 .Sp
170 The results can be passed to "\fBcatpath()\fR" to get back a path equivalent to
171 (usually identical to) the original path.
172 .IP splitdir 2
173 .IX Item "splitdir"
174 The opposite of "\fBcatdir()\fR".
175 .Sp
176 .Vb 1
177 \& @dirs = File::Spec\->splitdir( $directories );
178 .Ve
179 .Sp
180 \&\f(CW$directories\fR must be only the directory portion of the path on systems
181 that have the concept of a volume or that have path syntax that differentiates
182 files from directories.
183 .Sp
184 Unlike just splitting the directories on the separator, empty
185 directory names (\f(CW\*(Aq\*(Aq\fR) can be returned, because these are significant
186 on some OSs.
187 .Sp
188 On Unix,
189 .Sp
190 .Vb 1
191 \& File::Spec\->splitdir( "/a/b//c/" );
192 .Ve
193 .Sp
194 Yields:
195 .Sp
196 .Vb 1
197 \& ( \*(Aq\*(Aq, \*(Aqa\*(Aq, \*(Aqb\*(Aq, \*(Aq\*(Aq, \*(Aqc\*(Aq, \*(Aq\*(Aq )
198 .Ve
199 .IP \fBcatpath()\fR 2
200 .IX Item "catpath()"
201 Takes volume, directory and file portions and returns an entire path. Under
202 Unix, \f(CW$volume\fR is ignored, and directory and file are concatenated. A \*(Aq/\*(Aq is
203 inserted if needed (though if the directory portion doesn\*(Aqt start with
204 \&\*(Aq/\*(Aq it is not added). On other OSs, \f(CW$volume\fR is significant.
205 .IP abs2rel 2
206 .IX Item "abs2rel"
207 Takes a destination path and an optional base path returns a relative path
208 from the base path to the destination path:
209 .Sp
210 .Vb 2
211 \& $rel_path = File::Spec\->abs2rel( $path ) ;
212 \& $rel_path = File::Spec\->abs2rel( $path, $base ) ;
213 .Ve
214 .Sp
215 If \f(CW$base\fR is not present or \*(Aq\*(Aq, then \fBcwd()\fR is used. If \f(CW$base\fR is
216 relative, then it is converted to absolute form using
217 "\fBrel2abs()\fR". This means that it is taken to be relative to
218 \&\fBcwd()\fR.
219 .Sp
220 On systems that have a grammar that indicates filenames, this ignores the
221 \&\f(CW$base\fR filename. Otherwise all path components are assumed to be
222 directories.
223 .Sp
224 If \f(CW$path\fR is relative, it is converted to absolute form using "\fBrel2abs()\fR".
225 This means that it is taken to be relative to \fBcwd()\fR.
226 .Sp
227 No checks against the filesystem are made, so the result may not be correct if
228 \&\f(CW$base\fR contains symbolic links. (Apply
229 \&\fBCwd::abs_path()\fR beforehand if that
230 is a concern.) On VMS, there is interaction with the working environment, as
231 logicals and macros are expanded.
232 .Sp
233 Based on code written by Shigio Yamaguchi.
234 .IP \fBrel2abs()\fR 2
235 .IX Item "rel2abs()"
236 Converts a relative path to an absolute path.
237 .Sp
238 .Vb 2
239 \& $abs_path = File::Spec\->rel2abs( $path ) ;
240 \& $abs_path = File::Spec\->rel2abs( $path, $base ) ;
241 .Ve
242 .Sp
243 If \f(CW$base\fR is not present or \*(Aq\*(Aq, then \fBcwd()\fR is used. If \f(CW$base\fR is
244 relative, then it is converted to absolute form using
245 "\fBrel2abs()\fR". This means that it is taken to be relative to
246 \&\fBcwd()\fR.
247 .Sp
248 On systems that have a grammar that indicates filenames, this ignores
249 the \f(CW$base\fR filename. Otherwise all path components are assumed to be
250 directories.
251 .Sp
252 If \f(CW$path\fR is absolute, it is cleaned up and returned using "\fBcanonpath()\fR".
253 .Sp
254 No checks against the filesystem are made. On VMS, there is
255 interaction with the working environment, as logicals and
256 macros are expanded.
257 .Sp
258 Based on code written by Shigio Yamaguchi.
259 .SH COPYRIGHT
260 .IX Header "COPYRIGHT"
261 Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.
262 .PP
263 This program is free software; you can redistribute it and/or modify
264 it under the same terms as Perl itself.
265 .PP
266 Please submit bug reports at <https://github.com/Perl/perl5/issues>.
267 .SH "SEE ALSO"
268 .IX Header "SEE ALSO"
269 File::Spec