local-lib5/man/man3/File::Spec.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "File::Spec 3"
 132 .TH File::Spec 3 "2009-11-01" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 File::Spec \- portably perform operations on file names
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&        use File::Spec;
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&        $x=File::Spec\->catfile('a', 'b', 'c');
 143 .Ve
 144 .PP
 145 which returns 'a/b/c' under Unix. Or:
 146 .PP
 147 .Vb 1
 148 \&        use File::Spec::Functions;
 149 .Ve
 150 .PP
 151 .Vb 1
 152 \&        $x = catfile('a', 'b', 'c');
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 This module is designed to support operations commonly performed on file
 157 specifications (usually called \*(L"file names\*(R", but not to be confused with the
 158 contents of a file, or Perl's file handles), such as concatenating several
 159 directory and file names into a single path, or determining whether a path
 160 is rooted. It is based on code directly taken from MakeMaker 5.17, code
 161 written by Andreas Ko\*:nig, Andy Dougherty, Charles Bailey, Ilya
 162 Zakharevich, Paul Schinder, and others.
 163 .PP
 164 Since these functions are different for most operating systems, each set of
 165 \&\s-1OS\s0 specific routines is available in a separate module, including:
 166 .PP
 167 .Vb 5
 168 \&        File::Spec::Unix
 169 \&        File::Spec::Mac
 170 \&        File::Spec::OS2
 171 \&        File::Spec::Win32
 172 \&        File::Spec::VMS
 173 .Ve
 174 .PP
 175 The module appropriate for the current \s-1OS\s0 is automatically loaded by
 176 File::Spec. Since some modules (like \s-1VMS\s0) make use of facilities available
 177 only under that \s-1OS\s0, it may not be possible to load all modules under all
 178 operating systems.
 179 .PP
 180 Since File::Spec is object oriented, subroutines should not be called directly,
 181 as in:
 182 .PP
 183 .Vb 1
 184 \&        File::Spec::catfile('a','b');
 185 .Ve
 186 .PP
 187 but rather as class methods:
 188 .PP
 189 .Vb 1
 190 \&        File::Spec\->catfile('a','b');
 191 .Ve
 192 .PP
 193 For simple uses, File::Spec::Functions provides convenient functional
 194 forms of these methods.
 195 .SH "METHODS"
 196 .IX Header "METHODS"
 197 .IP "canonpath" 2
 198 .IX Xref "canonpath"
 199 .IX Item "canonpath"
 200 No physical check on the filesystem, but a logical cleanup of a
 201 path.
 202 .Sp
 203 .Vb 1
 204 \&    $cpath = File::Spec\->canonpath( $path ) ;
 205 .Ve
 206 .Sp
 207 Note that this does *not* collapse \fIx/../y\fR sections into \fIy\fR.  This
 208 is by design.  If \fI/foo\fR on your system is a symlink to \fI/bar/baz\fR,
 209 then \fI/foo/../quux\fR is actually \fI/bar/quux\fR, not \fI/quux\fR as a naive
 210 \&\fI../\fR\-removal would give you.  If you want to do this kind of
 211 processing, you probably want \f(CW\*(C`Cwd\*(C'\fR's \f(CW\*(C`realpath()\*(C'\fR function to
 212 actually traverse the filesystem cleaning up paths like this.
 213 .IP "catdir" 2
 214 .IX Xref "catdir"
 215 .IX Item "catdir"
 216 Concatenate two or more directory names to form a complete path ending
 217 with a directory. But remove the trailing slash from the resulting
 218 string, because it doesn't look good, isn't necessary and confuses
 219 \&\s-1OS/2\s0. Of course, if this is the root directory, don't cut off the
 220 trailing slash :\-)
 221 .Sp
 222 .Vb 1
 223 \&    $path = File::Spec\->catdir( @directories );
 224 .Ve
 225 .IP "catfile" 2
 226 .IX Xref "catfile"
 227 .IX Item "catfile"
 228 Concatenate one or more directory names and a filename to form a
 229 complete path ending with a filename
 230 .Sp
 231 .Vb 1
 232 \&    $path = File::Spec\->catfile( @directories, $filename );
 233 .Ve
 234 .IP "curdir" 2
 235 .IX Xref "curdir"
 236 .IX Item "curdir"
 237 Returns a string representation of the current directory.
 238 .Sp
 239 .Vb 1
 240 \&    $curdir = File::Spec\->curdir();
 241 .Ve
 242 .IP "devnull" 2
 243 .IX Xref "devnull"
 244 .IX Item "devnull"
 245 Returns a string representation of the null device.
 246 .Sp
 247 .Vb 1
 248 \&    $devnull = File::Spec\->devnull();
 249 .Ve
 250 .IP "rootdir" 2
 251 .IX Xref "rootdir"
 252 .IX Item "rootdir"
 253 Returns a string representation of the root directory.
 254 .Sp
 255 .Vb 1
 256 \&    $rootdir = File::Spec\->rootdir();
 257 .Ve
 258 .IP "tmpdir" 2
 259 .IX Xref "tmpdir"
 260 .IX Item "tmpdir"
 261 Returns a string representation of the first writable directory from a
 262 list of possible temporary directories.  Returns the current directory
 263 if no writable temporary directories are found.  The list of directories
 264 checked depends on the platform; e.g. File::Spec::Unix checks \f(CW$ENV{TMPDIR}\fR
 265 (unless taint is on) and \fI/tmp\fR.
 266 .Sp
 267 .Vb 1
 268 \&    $tmpdir = File::Spec\->tmpdir();
 269 .Ve
 270 .IP "updir" 2
 271 .IX Xref "updir"
 272 .IX Item "updir"
 273 Returns a string representation of the parent directory.
 274 .Sp
 275 .Vb 1
 276 \&    $updir = File::Spec\->updir();
 277 .Ve
 278 .IP "no_upwards" 2
 279 .IX Item "no_upwards"
 280 Given a list of file names, strip out those that refer to a parent
 281 directory. (Does not strip symlinks, only '.', '..', and equivalents.)
 282 .Sp
 283 .Vb 1
 284 \&    @paths = File::Spec\->no_upwards( @paths );
 285 .Ve
 286 .IP "case_tolerant" 2
 287 .IX Item "case_tolerant"
 288 Returns a true or false value indicating, respectively, that alphabetic
 289 case is not or is significant when comparing file specifications.
 290 .Sp
 291 .Vb 1
 292 \&    $is_case_tolerant = File::Spec\->case_tolerant();
 293 .Ve
 294 .IP "file_name_is_absolute" 2
 295 .IX Item "file_name_is_absolute"
 296 Takes as its argument a path, and returns true if it is an absolute path.
 297 .Sp
 298 .Vb 1
 299 \&    $is_absolute = File::Spec\->file_name_is_absolute( $path );
 300 .Ve
 301 .Sp
 302 This does not consult the local filesystem on Unix, Win32, \s-1OS/2\s0, or
 303 Mac \s-1OS\s0 (Classic).  It does consult the working environment for \s-1VMS\s0
 304 (see \*(L"file_name_is_absolute\*(R" in File::Spec::VMS).
 305 .IP "path" 2
 306 .IX Xref "path"
 307 .IX Item "path"
 308 Takes no argument.  Returns the environment variable \f(CW\*(C`PATH\*(C'\fR (or the local
 309 platform's equivalent) as a list.
 310 .Sp
 311 .Vb 1
 312 \&    @PATH = File::Spec\->path();
 313 .Ve
 314 .IP "join" 2
 315 .IX Xref "join, path"
 316 .IX Item "join"
 317 join is the same as catfile.
 318 .IP "splitpath" 2
 319 .IX Xref "splitpath split, path"
 320 .IX Item "splitpath"
 321 Splits a path in to volume, directory, and filename portions. On systems
 322 with no concept of volume, returns '' for volume.
 323 .Sp
 324 .Vb 2
 325 \&    ($volume,$directories,$file) = File::Spec\->splitpath( $path );
 326 \&    ($volume,$directories,$file) = File::Spec\->splitpath( $path, $no_file );
 327 .Ve
 328 .Sp
 329 For systems with no syntax differentiating filenames from directories,
 330 assumes that the last file is a path unless \f(CW$no_file\fR is true or a
 331 trailing separator or \fI/.\fR or \fI/..\fR is present. On Unix, this means that \f(CW$no_file\fR
 332 true makes this return ( '', \f(CW$path\fR, '' ).
 333 .Sp
 334 The directory portion may or may not be returned with a trailing '/'.
 335 .Sp
 336 The results can be passed to \*(L"\fIcatpath()\fR\*(R" to get back a path equivalent to
 337 (usually identical to) the original path.
 338 .IP "splitdir" 2
 339 .IX Xref "splitdir split, dir"
 340 .IX Item "splitdir"
 341 The opposite of \*(L"\fIcatdir()\fR\*(R".
 342 .Sp
 343 .Vb 1
 344 \&    @dirs = File::Spec\->splitdir( $directories );
 345 .Ve
 346 .Sp
 347 \&\f(CW$directories\fR must 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.
 350 .Sp
 351 Unlike just splitting the directories on the separator, empty
 352 directory names (\f(CW''\fR) can be returned, because these are significant
 353 on some OSes.
 354 .IP "\fIcatpath()\fR" 2
 355 .IX Item "catpath()"
 356 Takes volume, directory and file portions and returns an entire path. Under
 357 Unix, \f(CW$volume\fR is ignored, and directory and file are concatenated.  A '/' is
 358 inserted if need be.  On other OSes, \f(CW$volume\fR is significant.
 359 .Sp
 360 .Vb 1
 361 \&    $full_path = File::Spec\->catpath( $volume, $directory, $file );
 362 .Ve
 363 .IP "abs2rel" 2
 364 .IX Xref "abs2rel absolute, path relative, path"
 365 .IX Item "abs2rel"
 366 Takes a destination path and an optional base path returns a relative path
 367 from the base path to the destination path:
 368 .Sp
 369 .Vb 2
 370 \&    $rel_path = File::Spec\->abs2rel( $path ) ;
 371 \&    $rel_path = File::Spec\->abs2rel( $path, $base ) ;
 372 .Ve
 373 .Sp
 374 If \f(CW$base\fR is not present or '', then \fICwd::cwd()\fR is used. If \f(CW$base\fR is
 375 relative, then it is converted to absolute form using
 376 \&\*(L"\fIrel2abs()\fR\*(R". This means that it is taken to be relative to
 377 \&\fICwd::cwd()\fR.
 378 .Sp
 379 On systems with the concept of volume, if \f(CW$path\fR and \f(CW$base\fR appear to be
 380 on two different volumes, we will not attempt to resolve the two
 381 paths, and we will instead simply return \f(CW$path\fR.  Note that previous
 382 versions of this module ignored the volume of \f(CW$base\fR, which resulted in
 383 garbage results part of the time.
 384 .Sp
 385 On systems that have a grammar that indicates filenames, this ignores the
 386 \&\f(CW$base\fR filename as well. Otherwise all path components are assumed to be
 387 directories.
 388 .Sp
 389 If \f(CW$path\fR is relative, it is converted to absolute form using \*(L"\fIrel2abs()\fR\*(R".
 390 This means that it is taken to be relative to \fICwd::cwd()\fR.
 391 .Sp
 392 No checks against the filesystem are made.  On \s-1VMS\s0, there is
 393 interaction with the working environment, as logicals and
 394 macros are expanded.
 395 .Sp
 396 Based on code written by Shigio Yamaguchi.
 397 .IP "\fIrel2abs()\fR" 2
 398 .IX Xref "rel2abs absolute, path relative, path"
 399 .IX Item "rel2abs()"
 400 Converts a relative path to an absolute path.
 401 .Sp
 402 .Vb 2
 403 \&    $abs_path = File::Spec\->rel2abs( $path ) ;
 404 \&    $abs_path = File::Spec\->rel2abs( $path, $base ) ;
 405 .Ve
 406 .Sp
 407 If \f(CW$base\fR is not present or '', then \fICwd::cwd()\fR is used. If \f(CW$base\fR is relative,
 408 then it is converted to absolute form using \*(L"\fIrel2abs()\fR\*(R". This means that it
 409 is taken to be relative to \fICwd::cwd()\fR.
 410 .Sp
 411 On systems with the concept of volume, if \f(CW$path\fR and \f(CW$base\fR appear to be
 412 on two different volumes, we will not attempt to resolve the two
 413 paths, and we will instead simply return \f(CW$path\fR.  Note that previous
 414 versions of this module ignored the volume of \f(CW$base\fR, which resulted in
 415 garbage results part of the time.
 416 .Sp
 417 On systems that have a grammar that indicates filenames, this ignores the
 418 \&\f(CW$base\fR filename as well. Otherwise all path components are assumed to be
 419 directories.
 420 .Sp
 421 If \f(CW$path\fR is absolute, it is cleaned up and returned using \*(L"\fIcanonpath()\fR\*(R".
 422 .Sp
 423 No checks against the filesystem are made.  On \s-1VMS\s0, there is
 424 interaction with the working environment, as logicals and
 425 macros are expanded.
 426 .Sp
 427 Based on code written by Shigio Yamaguchi.
 428 .PP
 429 For further information, please see File::Spec::Unix,
 430 File::Spec::Mac, File::Spec::OS2, File::Spec::Win32, or
 431 File::Spec::VMS.
 432 .SH "SEE ALSO"
 433 .IX Header "SEE ALSO"
 434 File::Spec::Unix, File::Spec::Mac, File::Spec::OS2,
 435 File::Spec::Win32, File::Spec::VMS, File::Spec::Functions,
 436 ExtUtils::MakeMaker
 437 .SH "AUTHOR"
 438 .IX Header "AUTHOR"
 439 Currently maintained by Ken Williams \f(CW\*(C`<KWILLIAMS@cpan.org>\*(C'\fR.
 440 .PP
 441 The vast majority of the code was written by
 442 Kenneth Albanowski \f(CW\*(C`<kjahds@kjahds.com>\*(C'\fR,
 443 Andy Dougherty \f(CW\*(C`<doughera@lafayette.edu>\*(C'\fR,
 444 Andreas Ko\*:nig \f(CW\*(C`<A.Koenig@franz.ww.TU\-Berlin.DE>\*(C'\fR,
 445 Tim Bunce \f(CW\*(C`<Tim.Bunce@ig.co.uk>\*(C'\fR.
 446 \&\s-1VMS\s0 support by Charles Bailey \f(CW\*(C`<bailey@newman.upenn.edu>\*(C'\fR.
 447 \&\s-1OS/2\s0 support by Ilya Zakharevich \f(CW\*(C`<ilya@math.ohio\-state.edu>\*(C'\fR.
 448 Mac support by Paul Schinder \f(CW\*(C`<schinder@pobox.com>\*(C'\fR, and
 449 Thomas Wegner \f(CW\*(C`<wegner_thomas@yahoo.com>\*(C'\fR.
 450 \&\fIabs2rel()\fR and \fIrel2abs()\fR written by Shigio Yamaguchi \f(CW\*(C`<shigio@tamacom.com>\*(C'\fR,
 451 modified by Barrie Slaymaker \f(CW\*(C`<barries@slaysys.com>\*(C'\fR.
 452 \&\fIsplitpath()\fR, \fIsplitdir()\fR, \fIcatpath()\fR and \fIcatdir()\fR by Barrie Slaymaker.
 453 .SH "COPYRIGHT"
 454 .IX Header "COPYRIGHT"
 455 Copyright (c) 2004 by the Perl 5 Porters.  All rights reserved.
 456 .PP
 457 This program is free software; you can redistribute it and/or modify
 458 it under the same terms as Perl itself.