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 my ($self,$directories) = @_ ;
307 # split() likes to forget about trailing null fields, so here we
308 # check to be sure that there will not be any before handling the
311 if ( $directories !~ m|/\Z(?!\n)| ) {
312 return split( m|/|, $directories );
316 # since there was a trailing separator, add a file name to the end,
317 # then do the split, then replace it with ''.
319 my( @directories )= split( m|/|, "${directories}dummy" ) ;
320 $directories[ $#directories ]= '' ;
321 return @directories ;
328 Takes volume, directory and file portions and returns an entire path. Under
329 Unix, $volume is ignored, and directory and file are catenated. A '/' is
330 inserted if needed (though if the directory portion doesn't start with
331 '/' it is not added). On other OSs, $volume is significant.
336 my ($self,$volume,$directory,$file) = @_;
338 if ( $directory ne '' &&
340 substr( $directory, -1 ) ne '/' &&
341 substr( $file, 0, 1 ) ne '/'
343 $directory .= "/$file" ;
346 $directory .= $file ;
354 Takes a destination path and an optional base path returns a relative path
355 from the base path to the destination path:
357 $rel_path = File::Spec->abs2rel( $path ) ;
358 $rel_path = File::Spec->abs2rel( $path, $base ) ;
360 If $base is not present or '', then L<cwd()|Cwd> is used. If $base is relative,
361 then it is converted to absolute form using L</rel2abs()>. This means that it
362 is taken to be relative to L<cwd()|Cwd>.
364 On systems with the concept of a volume, this assumes that both paths
365 are on the $destination volume, and ignores the $base volume.
367 On systems that have a grammar that indicates filenames, this ignores the
368 $base filename as well. Otherwise all path components are assumed to be
371 If $path is relative, it is converted to absolute form using L</rel2abs()>.
372 This means that it is taken to be relative to L<cwd()|Cwd>.
374 No checks against the filesystem are made. On VMS, there is
375 interaction with the working environment, as logicals and
378 Based on code written by Shigio Yamaguchi.
383 my($self,$path,$base) = @_;
386 if ( ! $self->file_name_is_absolute( $path ) ) {
387 $path = $self->rel2abs( $path ) ;
390 $path = $self->canonpath( $path ) ;
393 # Figure out the effective $base and clean it up.
394 if ( !defined( $base ) || $base eq '' ) {
397 elsif ( ! $self->file_name_is_absolute( $base ) ) {
398 $base = $self->rel2abs( $base ) ;
401 $base = $self->canonpath( $base ) ;
404 # Now, remove all leading components that are the same
405 my @pathchunks = $self->splitdir( $path);
406 my @basechunks = $self->splitdir( $base);
408 while (@pathchunks && @basechunks && $pathchunks[0] eq $basechunks[0]) {
413 $path = CORE::join( '/', @pathchunks );
414 $base = CORE::join( '/', @basechunks );
416 # $base now contains the directories the resulting relative path
417 # must ascend out of before it can descend to $path_directory. So,
418 # replace all names with $parentDir
419 $base =~ s|[^/]+|..|g ;
421 # Glue the two together, using a separator if necessary, and preventing an
423 if ( $path ne '' && $base ne '' ) {
424 $path = "$base/$path" ;
426 $path = "$base$path" ;
429 return $self->canonpath( $path ) ;
434 Converts a relative path to an absolute path.
436 $abs_path = File::Spec->rel2abs( $path ) ;
437 $abs_path = File::Spec->rel2abs( $path, $base ) ;
439 If $base is not present or '', then L<cwd()|Cwd> is used. If $base is relative,
440 then it is converted to absolute form using L</rel2abs()>. This means that it
441 is taken to be relative to L<cwd()|Cwd>.
443 On systems with the concept of a volume, this assumes that both paths
444 are on the $base volume, and ignores the $path volume.
446 On systems that have a grammar that indicates filenames, this ignores the
447 $base filename as well. Otherwise all path components are assumed to be
450 If $path is absolute, it is cleaned up and returned using L</canonpath()>.
452 No checks against the filesystem are made. On VMS, there is
453 interaction with the working environment, as logicals and
456 Based on code written by Shigio Yamaguchi.
461 my ($self,$path,$base ) = @_;
464 if ( ! $self->file_name_is_absolute( $path ) ) {
465 # Figure out the effective $base and clean it up.
466 if ( !defined( $base ) || $base eq '' ) {
469 elsif ( ! $self->file_name_is_absolute( $base ) ) {
470 $base = $self->rel2abs( $base ) ;
473 $base = $self->canonpath( $base ) ;
477 $path = $self->catdir( $base, $path ) ;
480 return $self->canonpath( $path ) ;