1 package File::Spec::Unix;
12 File::Spec::Unix - File::Spec for Unix, base for other File::Spec modules
16 require File::Spec::Unix; # Done automatically by File::Spec
20 Methods for manipulating file specifications. Other File::Spec
21 modules, such as File::Spec::Mac, inherit from File::Spec::Unix and
22 override specific methods.
30 No physical check on the filesystem, but a logical cleanup of a
31 path. On UNIX eliminates successive slashes and successive "/.".
33 $cpath = File::Spec->canonpath( $path ) ;
38 my ($self,$path) = @_;
40 # Handle POSIX-style node names beginning with double slash (qnx, nto)
41 # Handle network path names beginning with double slash (cygwin)
42 # (POSIX says: "a pathname that begins with two successive slashes
43 # may be interpreted in an implementation-defined manner, although
44 # more than two leading slashes shall be treated as a single slash.")
46 if ( $^O =~ m/^(?:qnx|nto|cygwin)$/ && $path =~ s:^(//[^/]+)(/|\z):/:s ) {
50 # $path =~ s|/+|/|g unless($^O eq 'cygwin');
51 # but that made tests 29, 30, 35, 46, and 213 (as of #13272) to fail
52 # (Mainly because trailing "" directories didn't get stripped).
53 # Why would cygwin avoid collapsing multiple slashes into one? --jhi
54 $path =~ s|/+|/|g; # xx////xx -> xx/xx
55 $path =~ s@(/\.)+(/|\Z(?!\n))@/@g; # xx/././xx -> xx/xx
56 $path =~ s|^(\./)+||s unless $path eq "./"; # ./xx -> xx
57 $path =~ s|^/(\.\./)+|/|s; # /../../xx -> xx
58 $path =~ s|/\Z(?!\n)|| unless $path eq "/"; # xx/ -> xx
64 Concatenate two or more directory names to form a complete path ending
65 with a directory. But remove the trailing slash from the resulting
66 string, because it doesn't look good, isn't necessary and confuses
67 OS2. Of course, if this is the root directory, don't cut off the
76 # append a slash to each argument unless it has one there
77 $_ .= "/" if $_ eq '' || substr($_,-1) ne "/";
79 return $self->canonpath(join('', @args));
84 Concatenate one or more directory names and a filename to form a
85 complete path ending with a filename
91 my $file = $self->canonpath(pop @_);
92 return $file unless @_;
93 my $dir = $self->catdir(@_);
94 $dir .= "/" unless substr($dir,-1) eq "/";
100 Returns a string representation of the current directory. "." on UNIX.
110 Returns a string representation of the null device. "/dev/null" on UNIX.
120 Returns a string representation of the root directory. "/" on UNIX.
130 Returns a string representation of the first writable directory from
131 the following list or the current directory if none from the list are
137 Since perl 5.8.0, if running under taint mode, and if $ENV{TMPDIR}
138 is tainted, it is not used.
144 return $tmpdir if defined $tmpdir;
149 if (${"\cTAINT"}) { # Check for taint mode on perl >= 5.8.0
150 require Scalar::Util;
151 @dirlist = grep { ! Scalar::Util::tainted($_) } @dirlist;
155 next unless defined && -d && -w _;
159 $tmpdir = $self->curdir unless defined $tmpdir;
160 $tmpdir = defined $tmpdir && $self->canonpath($tmpdir);
165 return $tmpdir if defined $tmpdir;
167 $tmpdir = $self->_tmpdir( $ENV{TMPDIR}, "/tmp" );
172 Returns a string representation of the parent directory. ".." on UNIX.
182 Given a list of file names, strip out those that refer to a parent
183 directory. (Does not strip symlinks, only '.', '..', and equivalents.)
189 return grep(!/^\.{1,2}\Z(?!\n)/s, @_);
194 Returns a true or false value indicating, respectively, that alphabetic
195 is not or is significant when comparing file specifications.
203 =item file_name_is_absolute
205 Takes as argument a path and returns true if it is an absolute path.
207 This does not consult the local filesystem on Unix, Win32, OS/2 or Mac
208 OS (Classic). It does consult the working environment for VMS (see
209 L<File::Spec::VMS/file_name_is_absolute>).
213 sub file_name_is_absolute {
214 my ($self,$file) = @_;
215 return scalar($file =~ m:^/:s);
220 Takes no argument, returns the environment variable PATH as an array.
225 return () unless exists $ENV{PATH};
226 my @path = split(':', $ENV{PATH});
227 foreach (@path) { $_ = '.' if $_ eq '' }
233 join is the same as catfile.
239 return $self->catfile(@_);
244 ($volume,$directories,$file) = File::Spec->splitpath( $path );
245 ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );
247 Splits a path into volume, directory, and filename portions. On systems
248 with no concept of volume, returns '' for volume.
250 For systems with no syntax differentiating filenames from directories,
251 assumes that the last file is a path unless $no_file is true or a
252 trailing separator or /. or /.. is present. On Unix this means that $no_file
253 true makes this return ( '', $path, '' ).
255 The directory portion may or may not be returned with a trailing '/'.
257 The results can be passed to L</catpath()> to get back a path equivalent to
258 (usually identical to) the original path.
263 my ($self,$path, $nofile) = @_;
265 my ($volume,$directory,$file) = ('','','');
271 $path =~ m|^ ( (?: .* / (?: \.\.?\Z(?!\n) )? )? ) ([^/]*) |xs;
276 return ($volume,$directory,$file);
282 The opposite of L</catdir()>.
284 @dirs = File::Spec->splitdir( $directories );
286 $directories must be only the directory portion of the path on systems
287 that have the concept of a volume or that have path syntax that differentiates
288 files from directories.
290 Unlike just splitting the directories on the separator, empty
291 directory names (C<''>) can be returned, because these are significant
296 File::Spec->splitdir( "/a/b//c/" );
300 ( '', 'a', 'b', '', 'c', '' )
305 return split m|/|, $_[1], -1; # Preserve trailing fields
311 Takes volume, directory and file portions and returns an entire path. Under
312 Unix, $volume is ignored, and directory and file are concatenated. A '/' is
313 inserted if needed (though if the directory portion doesn't start with
314 '/' it is not added). On other OSs, $volume is significant.
319 my ($self,$volume,$directory,$file) = @_;
321 if ( $directory ne '' &&
323 substr( $directory, -1 ) ne '/' &&
324 substr( $file, 0, 1 ) ne '/'
326 $directory .= "/$file" ;
329 $directory .= $file ;
337 Takes a destination path and an optional base path returns a relative path
338 from the base path to the destination path:
340 $rel_path = File::Spec->abs2rel( $path ) ;
341 $rel_path = File::Spec->abs2rel( $path, $base ) ;
343 If $base is not present or '', then L<cwd()|Cwd> is used. If $base is relative,
344 then it is converted to absolute form using L</rel2abs()>. This means that it
345 is taken to be relative to L<cwd()|Cwd>.
347 On systems with the concept of a volume, this assumes that both paths
348 are on the $destination volume, and ignores the $base volume.
350 On systems that have a grammar that indicates filenames, this ignores the
351 $base filename as well. Otherwise all path components are assumed to be
354 If $path is relative, it is converted to absolute form using L</rel2abs()>.
355 This means that it is taken to be relative to L<cwd()|Cwd>.
357 No checks against the filesystem are made. On VMS, there is
358 interaction with the working environment, as logicals and
361 Based on code written by Shigio Yamaguchi.
366 my($self,$path,$base) = @_;
369 if ( ! $self->file_name_is_absolute( $path ) ) {
370 $path = $self->rel2abs( $path ) ;
373 $path = $self->canonpath( $path ) ;
376 # Figure out the effective $base and clean it up.
377 if ( !defined( $base ) || $base eq '' ) {
380 elsif ( ! $self->file_name_is_absolute( $base ) ) {
381 $base = $self->rel2abs( $base ) ;
384 $base = $self->canonpath( $base ) ;
387 # Now, remove all leading components that are the same
388 my @pathchunks = $self->splitdir( $path);
389 my @basechunks = $self->splitdir( $base);
391 while (@pathchunks && @basechunks && $pathchunks[0] eq $basechunks[0]) {
396 $path = CORE::join( '/', @pathchunks );
397 $base = CORE::join( '/', @basechunks );
399 # $base now contains the directories the resulting relative path
400 # must ascend out of before it can descend to $path_directory. So,
401 # replace all names with $parentDir
402 $base =~ s|[^/]+|..|g ;
404 # Glue the two together, using a separator if necessary, and preventing an
406 if ( $path ne '' && $base ne '' ) {
407 $path = "$base/$path" ;
409 $path = "$base$path" ;
412 return $self->canonpath( $path ) ;
417 Converts a relative path to an absolute path.
419 $abs_path = File::Spec->rel2abs( $path ) ;
420 $abs_path = File::Spec->rel2abs( $path, $base ) ;
422 If $base is not present or '', then L<cwd()|Cwd> is used. If $base is relative,
423 then it is converted to absolute form using L</rel2abs()>. This means that it
424 is taken to be relative to L<cwd()|Cwd>.
426 On systems with the concept of a volume, this assumes that both paths
427 are on the $base volume, and ignores the $path volume.
429 On systems that have a grammar that indicates filenames, this ignores the
430 $base filename as well. Otherwise all path components are assumed to be
433 If $path is absolute, it is cleaned up and returned using L</canonpath()>.
435 No checks against the filesystem are made. On VMS, there is
436 interaction with the working environment, as logicals and
439 Based on code written by Shigio Yamaguchi.
444 my ($self,$path,$base ) = @_;
447 if ( ! $self->file_name_is_absolute( $path ) ) {
448 # Figure out the effective $base and clean it up.
449 if ( !defined( $base ) || $base eq '' ) {
452 elsif ( ! $self->file_name_is_absolute( $base ) ) {
453 $base = $self->rel2abs( $base ) ;
456 $base = $self->canonpath( $base ) ;
460 $path = $self->catdir( $base, $path ) ;
463 return $self->canonpath( $path ) ;