1*0Sstevel@tonic-gatepackage File::Spec; 2*0Sstevel@tonic-gate 3*0Sstevel@tonic-gateuse strict; 4*0Sstevel@tonic-gateuse vars qw(@ISA $VERSION); 5*0Sstevel@tonic-gate 6*0Sstevel@tonic-gate$VERSION = '0.87'; 7*0Sstevel@tonic-gate 8*0Sstevel@tonic-gatemy %module = (MacOS => 'Mac', 9*0Sstevel@tonic-gate MSWin32 => 'Win32', 10*0Sstevel@tonic-gate os2 => 'OS2', 11*0Sstevel@tonic-gate VMS => 'VMS', 12*0Sstevel@tonic-gate epoc => 'Epoc', 13*0Sstevel@tonic-gate NetWare => 'Win32', # Yes, File::Spec::Win32 works on NetWare. 14*0Sstevel@tonic-gate dos => 'OS2', # Yes, File::Spec::OS2 works on DJGPP. 15*0Sstevel@tonic-gate cygwin => 'Cygwin'); 16*0Sstevel@tonic-gate 17*0Sstevel@tonic-gate 18*0Sstevel@tonic-gatemy $module = $module{$^O} || 'Unix'; 19*0Sstevel@tonic-gate 20*0Sstevel@tonic-gaterequire "File/Spec/$module.pm"; 21*0Sstevel@tonic-gate@ISA = ("File::Spec::$module"); 22*0Sstevel@tonic-gate 23*0Sstevel@tonic-gate1; 24*0Sstevel@tonic-gate 25*0Sstevel@tonic-gate__END__ 26*0Sstevel@tonic-gate 27*0Sstevel@tonic-gate=head1 NAME 28*0Sstevel@tonic-gate 29*0Sstevel@tonic-gateFile::Spec - portably perform operations on file names 30*0Sstevel@tonic-gate 31*0Sstevel@tonic-gate=head1 SYNOPSIS 32*0Sstevel@tonic-gate 33*0Sstevel@tonic-gate use File::Spec; 34*0Sstevel@tonic-gate 35*0Sstevel@tonic-gate $x=File::Spec->catfile('a', 'b', 'c'); 36*0Sstevel@tonic-gate 37*0Sstevel@tonic-gatewhich returns 'a/b/c' under Unix. Or: 38*0Sstevel@tonic-gate 39*0Sstevel@tonic-gate use File::Spec::Functions; 40*0Sstevel@tonic-gate 41*0Sstevel@tonic-gate $x = catfile('a', 'b', 'c'); 42*0Sstevel@tonic-gate 43*0Sstevel@tonic-gate=head1 DESCRIPTION 44*0Sstevel@tonic-gate 45*0Sstevel@tonic-gateThis module is designed to support operations commonly performed on file 46*0Sstevel@tonic-gatespecifications (usually called "file names", but not to be confused with the 47*0Sstevel@tonic-gatecontents of a file, or Perl's file handles), such as concatenating several 48*0Sstevel@tonic-gatedirectory and file names into a single path, or determining whether a path 49*0Sstevel@tonic-gateis rooted. It is based on code directly taken from MakeMaker 5.17, code 50*0Sstevel@tonic-gatewritten by Andreas KE<ouml>nig, Andy Dougherty, Charles Bailey, Ilya 51*0Sstevel@tonic-gateZakharevich, Paul Schinder, and others. 52*0Sstevel@tonic-gate 53*0Sstevel@tonic-gateSince these functions are different for most operating systems, each set of 54*0Sstevel@tonic-gateOS specific routines is available in a separate module, including: 55*0Sstevel@tonic-gate 56*0Sstevel@tonic-gate File::Spec::Unix 57*0Sstevel@tonic-gate File::Spec::Mac 58*0Sstevel@tonic-gate File::Spec::OS2 59*0Sstevel@tonic-gate File::Spec::Win32 60*0Sstevel@tonic-gate File::Spec::VMS 61*0Sstevel@tonic-gate 62*0Sstevel@tonic-gateThe module appropriate for the current OS is automatically loaded by 63*0Sstevel@tonic-gateFile::Spec. Since some modules (like VMS) make use of facilities available 64*0Sstevel@tonic-gateonly under that OS, it may not be possible to load all modules under all 65*0Sstevel@tonic-gateoperating systems. 66*0Sstevel@tonic-gate 67*0Sstevel@tonic-gateSince File::Spec is object oriented, subroutines should not be called directly, 68*0Sstevel@tonic-gateas in: 69*0Sstevel@tonic-gate 70*0Sstevel@tonic-gate File::Spec::catfile('a','b'); 71*0Sstevel@tonic-gate 72*0Sstevel@tonic-gatebut rather as class methods: 73*0Sstevel@tonic-gate 74*0Sstevel@tonic-gate File::Spec->catfile('a','b'); 75*0Sstevel@tonic-gate 76*0Sstevel@tonic-gateFor simple uses, L<File::Spec::Functions> provides convenient functional 77*0Sstevel@tonic-gateforms of these methods. 78*0Sstevel@tonic-gate 79*0Sstevel@tonic-gate=head1 METHODS 80*0Sstevel@tonic-gate 81*0Sstevel@tonic-gate=over 2 82*0Sstevel@tonic-gate 83*0Sstevel@tonic-gate=item canonpath 84*0Sstevel@tonic-gate 85*0Sstevel@tonic-gateNo physical check on the filesystem, but a logical cleanup of a 86*0Sstevel@tonic-gatepath. 87*0Sstevel@tonic-gate 88*0Sstevel@tonic-gate $cpath = File::Spec->canonpath( $path ) ; 89*0Sstevel@tonic-gate 90*0Sstevel@tonic-gate=item catdir 91*0Sstevel@tonic-gate 92*0Sstevel@tonic-gateConcatenate two or more directory names to form a complete path ending 93*0Sstevel@tonic-gatewith a directory. But remove the trailing slash from the resulting 94*0Sstevel@tonic-gatestring, because it doesn't look good, isn't necessary and confuses 95*0Sstevel@tonic-gateOS2. Of course, if this is the root directory, don't cut off the 96*0Sstevel@tonic-gatetrailing slash :-) 97*0Sstevel@tonic-gate 98*0Sstevel@tonic-gate $path = File::Spec->catdir( @directories ); 99*0Sstevel@tonic-gate 100*0Sstevel@tonic-gate=item catfile 101*0Sstevel@tonic-gate 102*0Sstevel@tonic-gateConcatenate one or more directory names and a filename to form a 103*0Sstevel@tonic-gatecomplete path ending with a filename 104*0Sstevel@tonic-gate 105*0Sstevel@tonic-gate $path = File::Spec->catfile( @directories, $filename ); 106*0Sstevel@tonic-gate 107*0Sstevel@tonic-gate=item curdir 108*0Sstevel@tonic-gate 109*0Sstevel@tonic-gateReturns a string representation of the current directory. 110*0Sstevel@tonic-gate 111*0Sstevel@tonic-gate $curdir = File::Spec->curdir(); 112*0Sstevel@tonic-gate 113*0Sstevel@tonic-gate=item devnull 114*0Sstevel@tonic-gate 115*0Sstevel@tonic-gateReturns a string representation of the null device. 116*0Sstevel@tonic-gate 117*0Sstevel@tonic-gate $devnull = File::Spec->devnull(); 118*0Sstevel@tonic-gate 119*0Sstevel@tonic-gate=item rootdir 120*0Sstevel@tonic-gate 121*0Sstevel@tonic-gateReturns a string representation of the root directory. 122*0Sstevel@tonic-gate 123*0Sstevel@tonic-gate $rootdir = File::Spec->rootdir(); 124*0Sstevel@tonic-gate 125*0Sstevel@tonic-gate=item tmpdir 126*0Sstevel@tonic-gate 127*0Sstevel@tonic-gateReturns a string representation of the first writable directory from a 128*0Sstevel@tonic-gatelist of possible temporary directories. Returns the current directory 129*0Sstevel@tonic-gateif no writable temporary directories are found. The list of directories 130*0Sstevel@tonic-gatechecked depends on the platform; e.g. File::Spec::Unix checks $ENV{TMPDIR} 131*0Sstevel@tonic-gate(unless taint is on) and /tmp. 132*0Sstevel@tonic-gate 133*0Sstevel@tonic-gate $tmpdir = File::Spec->tmpdir(); 134*0Sstevel@tonic-gate 135*0Sstevel@tonic-gate=item updir 136*0Sstevel@tonic-gate 137*0Sstevel@tonic-gateReturns a string representation of the parent directory. 138*0Sstevel@tonic-gate 139*0Sstevel@tonic-gate $updir = File::Spec->updir(); 140*0Sstevel@tonic-gate 141*0Sstevel@tonic-gate=item no_upwards 142*0Sstevel@tonic-gate 143*0Sstevel@tonic-gateGiven a list of file names, strip out those that refer to a parent 144*0Sstevel@tonic-gatedirectory. (Does not strip symlinks, only '.', '..', and equivalents.) 145*0Sstevel@tonic-gate 146*0Sstevel@tonic-gate @paths = File::Spec->no_upwards( @paths ); 147*0Sstevel@tonic-gate 148*0Sstevel@tonic-gate=item case_tolerant 149*0Sstevel@tonic-gate 150*0Sstevel@tonic-gateReturns a true or false value indicating, respectively, that alphabetic 151*0Sstevel@tonic-gateis not or is significant when comparing file specifications. 152*0Sstevel@tonic-gate 153*0Sstevel@tonic-gate $is_case_tolerant = File::Spec->case_tolerant(); 154*0Sstevel@tonic-gate 155*0Sstevel@tonic-gate=item file_name_is_absolute 156*0Sstevel@tonic-gate 157*0Sstevel@tonic-gateTakes as argument a path and returns true if it is an absolute path. 158*0Sstevel@tonic-gate 159*0Sstevel@tonic-gate $is_absolute = File::Spec->file_name_is_absolute( $path ); 160*0Sstevel@tonic-gate 161*0Sstevel@tonic-gateThis does not consult the local filesystem on Unix, Win32, OS/2, or 162*0Sstevel@tonic-gateMac OS (Classic). It does consult the working environment for VMS 163*0Sstevel@tonic-gate(see L<File::Spec::VMS/file_name_is_absolute>). 164*0Sstevel@tonic-gate 165*0Sstevel@tonic-gate=item path 166*0Sstevel@tonic-gate 167*0Sstevel@tonic-gateTakes no argument, returns the environment variable PATH (or the local 168*0Sstevel@tonic-gateplatform's equivalent) as a list. 169*0Sstevel@tonic-gate 170*0Sstevel@tonic-gate @PATH = File::Spec->path(); 171*0Sstevel@tonic-gate 172*0Sstevel@tonic-gate=item join 173*0Sstevel@tonic-gate 174*0Sstevel@tonic-gatejoin is the same as catfile. 175*0Sstevel@tonic-gate 176*0Sstevel@tonic-gate=item splitpath 177*0Sstevel@tonic-gate 178*0Sstevel@tonic-gateSplits a path in to volume, directory, and filename portions. On systems 179*0Sstevel@tonic-gatewith no concept of volume, returns '' for volume. 180*0Sstevel@tonic-gate 181*0Sstevel@tonic-gate ($volume,$directories,$file) = File::Spec->splitpath( $path ); 182*0Sstevel@tonic-gate ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file ); 183*0Sstevel@tonic-gate 184*0Sstevel@tonic-gateFor systems with no syntax differentiating filenames from directories, 185*0Sstevel@tonic-gateassumes that the last file is a path unless $no_file is true or a 186*0Sstevel@tonic-gatetrailing separator or /. or /.. is present. On Unix this means that $no_file 187*0Sstevel@tonic-gatetrue makes this return ( '', $path, '' ). 188*0Sstevel@tonic-gate 189*0Sstevel@tonic-gateThe directory portion may or may not be returned with a trailing '/'. 190*0Sstevel@tonic-gate 191*0Sstevel@tonic-gateThe results can be passed to L</catpath()> to get back a path equivalent to 192*0Sstevel@tonic-gate(usually identical to) the original path. 193*0Sstevel@tonic-gate 194*0Sstevel@tonic-gate=item splitdir 195*0Sstevel@tonic-gate 196*0Sstevel@tonic-gateThe opposite of L</catdir()>. 197*0Sstevel@tonic-gate 198*0Sstevel@tonic-gate @dirs = File::Spec->splitdir( $directories ); 199*0Sstevel@tonic-gate 200*0Sstevel@tonic-gate$directories must be only the directory portion of the path on systems 201*0Sstevel@tonic-gatethat have the concept of a volume or that have path syntax that differentiates 202*0Sstevel@tonic-gatefiles from directories. 203*0Sstevel@tonic-gate 204*0Sstevel@tonic-gateUnlike just splitting the directories on the separator, empty 205*0Sstevel@tonic-gatedirectory names (C<''>) can be returned, because these are significant 206*0Sstevel@tonic-gateon some OSs. 207*0Sstevel@tonic-gate 208*0Sstevel@tonic-gate=item catpath() 209*0Sstevel@tonic-gate 210*0Sstevel@tonic-gateTakes volume, directory and file portions and returns an entire path. Under 211*0Sstevel@tonic-gateUnix, $volume is ignored, and directory and file are concatenated. A '/' is 212*0Sstevel@tonic-gateinserted if need be. On other OSs, $volume is significant. 213*0Sstevel@tonic-gate 214*0Sstevel@tonic-gate $full_path = File::Spec->catpath( $volume, $directory, $file ); 215*0Sstevel@tonic-gate 216*0Sstevel@tonic-gate=item abs2rel 217*0Sstevel@tonic-gate 218*0Sstevel@tonic-gateTakes a destination path and an optional base path returns a relative path 219*0Sstevel@tonic-gatefrom the base path to the destination path: 220*0Sstevel@tonic-gate 221*0Sstevel@tonic-gate $rel_path = File::Spec->abs2rel( $path ) ; 222*0Sstevel@tonic-gate $rel_path = File::Spec->abs2rel( $path, $base ) ; 223*0Sstevel@tonic-gate 224*0Sstevel@tonic-gateIf $base is not present or '', then L<cwd()|Cwd> is used. If $base is 225*0Sstevel@tonic-gaterelative, then it is converted to absolute form using 226*0Sstevel@tonic-gateL</rel2abs()>. This means that it is taken to be relative to 227*0Sstevel@tonic-gateL<cwd()|Cwd>. 228*0Sstevel@tonic-gate 229*0Sstevel@tonic-gateOn systems with the concept of volume, if $path and $base appear to be 230*0Sstevel@tonic-gateon two different volumes, we will not attempt to resolve the two 231*0Sstevel@tonic-gatepaths, and we will instead simply return $path. Note that previous 232*0Sstevel@tonic-gateversions of this module ignored the volume of $base, which resulted in 233*0Sstevel@tonic-gategarbage results part of the time. 234*0Sstevel@tonic-gate 235*0Sstevel@tonic-gateOn systems that have a grammar that indicates filenames, this ignores the 236*0Sstevel@tonic-gate$base filename as well. Otherwise all path components are assumed to be 237*0Sstevel@tonic-gatedirectories. 238*0Sstevel@tonic-gate 239*0Sstevel@tonic-gateIf $path is relative, it is converted to absolute form using L</rel2abs()>. 240*0Sstevel@tonic-gateThis means that it is taken to be relative to L<cwd()|Cwd>. 241*0Sstevel@tonic-gate 242*0Sstevel@tonic-gateNo checks against the filesystem are made. On VMS, there is 243*0Sstevel@tonic-gateinteraction with the working environment, as logicals and 244*0Sstevel@tonic-gatemacros are expanded. 245*0Sstevel@tonic-gate 246*0Sstevel@tonic-gateBased on code written by Shigio Yamaguchi. 247*0Sstevel@tonic-gate 248*0Sstevel@tonic-gate=item rel2abs() 249*0Sstevel@tonic-gate 250*0Sstevel@tonic-gateConverts a relative path to an absolute path. 251*0Sstevel@tonic-gate 252*0Sstevel@tonic-gate $abs_path = File::Spec->rel2abs( $path ) ; 253*0Sstevel@tonic-gate $abs_path = File::Spec->rel2abs( $path, $base ) ; 254*0Sstevel@tonic-gate 255*0Sstevel@tonic-gateIf $base is not present or '', then L<cwd()|Cwd> is used. If $base is relative, 256*0Sstevel@tonic-gatethen it is converted to absolute form using L</rel2abs()>. This means that it 257*0Sstevel@tonic-gateis taken to be relative to L<cwd()|Cwd>. 258*0Sstevel@tonic-gate 259*0Sstevel@tonic-gateOn systems with the concept of volume, if $path and $base appear to be 260*0Sstevel@tonic-gateon two different volumes, we will not attempt to resolve the two 261*0Sstevel@tonic-gatepaths, and we will instead simply return $path. Note that previous 262*0Sstevel@tonic-gateversions of this module ignored the volume of $base, which resulted in 263*0Sstevel@tonic-gategarbage results part of the time. 264*0Sstevel@tonic-gate 265*0Sstevel@tonic-gateOn systems that have a grammar that indicates filenames, this ignores the 266*0Sstevel@tonic-gate$base filename as well. Otherwise all path components are assumed to be 267*0Sstevel@tonic-gatedirectories. 268*0Sstevel@tonic-gate 269*0Sstevel@tonic-gateIf $path is absolute, it is cleaned up and returned using L</canonpath()>. 270*0Sstevel@tonic-gate 271*0Sstevel@tonic-gateNo checks against the filesystem are made. On VMS, there is 272*0Sstevel@tonic-gateinteraction with the working environment, as logicals and 273*0Sstevel@tonic-gatemacros are expanded. 274*0Sstevel@tonic-gate 275*0Sstevel@tonic-gateBased on code written by Shigio Yamaguchi. 276*0Sstevel@tonic-gate 277*0Sstevel@tonic-gate=back 278*0Sstevel@tonic-gate 279*0Sstevel@tonic-gateFor further information, please see L<File::Spec::Unix>, 280*0Sstevel@tonic-gateL<File::Spec::Mac>, L<File::Spec::OS2>, L<File::Spec::Win32>, or 281*0Sstevel@tonic-gateL<File::Spec::VMS>. 282*0Sstevel@tonic-gate 283*0Sstevel@tonic-gate=head1 SEE ALSO 284*0Sstevel@tonic-gate 285*0Sstevel@tonic-gateL<File::Spec::Unix>, L<File::Spec::Mac>, L<File::Spec::OS2>, 286*0Sstevel@tonic-gateL<File::Spec::Win32>, L<File::Spec::VMS>, L<File::Spec::Functions>, 287*0Sstevel@tonic-gateL<ExtUtils::MakeMaker> 288*0Sstevel@tonic-gate 289*0Sstevel@tonic-gate=head1 AUTHORS 290*0Sstevel@tonic-gate 291*0Sstevel@tonic-gateKenneth Albanowski <kjahds@kjahds.com>, Andy Dougherty 292*0Sstevel@tonic-gate<doughera@lafayette.edu>, Andreas KE<ouml>nig 293*0Sstevel@tonic-gate<A.Koenig@franz.ww.TU-Berlin.DE>, Tim Bunce <Tim.Bunce@ig.co.uk. 294*0Sstevel@tonic-gateVMS support by Charles Bailey <bailey@newman.upenn.edu>. 295*0Sstevel@tonic-gateOS/2 support by Ilya Zakharevich <ilya@math.ohio-state.edu>. 296*0Sstevel@tonic-gateMac support by Paul Schinder <schinder@pobox.com>, and Thomas Wegner 297*0Sstevel@tonic-gate<wegner_thomas@yahoo.com>. abs2rel() and rel2abs() written by Shigio 298*0Sstevel@tonic-gateYamaguchi <shigio@tamacom.com>, modified by Barrie Slaymaker 299*0Sstevel@tonic-gate<barries@slaysys.com>. splitpath(), splitdir(), catpath() and 300*0Sstevel@tonic-gatecatdir() by Barrie Slaymaker. 301*0Sstevel@tonic-gate 302*0Sstevel@tonic-gate=cut 303