local-lib5/man/man3/File::Spec::Mac.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::Mac 3"
 132 .TH File::Spec::Mac 3 "2009-05-10" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 File::Spec::Mac \- File::Spec for Mac OS (Classic)
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \& require File::Spec::Mac; # Done internally by File::Spec if needed
 139 .Ve
 140 .SH "DESCRIPTION"
 141 .IX Header "DESCRIPTION"
 142 Methods for manipulating file specifications.
 143 .SH "METHODS"
 144 .IX Header "METHODS"
 145 .IP "canonpath" 2
 146 .IX Item "canonpath"
 147 On Mac \s-1OS\s0, there's nothing to be done. Returns what it's given.
 148 .IP "\fIcatdir()\fR" 2
 149 .IX Item "catdir()"
 150 Concatenate two or more directory names to form a path separated by colons
 151 (\*(L":\*(R") ending with a directory. Resulting paths are \fBrelative\fR by default,
 152 but can be forced to be absolute (but avoid this, see below). Automatically
 153 puts a trailing \*(L":\*(R" on the end of the complete path, because that's what's
 154 done in MacPerl's environment and helps to distinguish a file path from a
 155 directory path.
 156 .Sp
 157 \&\fB\s-1IMPORTANT\s0 \s-1NOTE:\s0\fR Beginning with version 1.3 of this module, the resulting
 158 path is relative by default and \fInot\fR absolute. This decision was made due
 159 to portability reasons. Since \f(CW\*(C`File::Spec\->catdir()\*(C'\fR returns relative paths
 160 on all other operating systems, it will now also follow this convention on Mac
 161 \&\s-1OS\s0. Note that this may break some existing scripts.
 162 .Sp
 163 The intended purpose of this routine is to concatenate \fIdirectory names\fR.
 164 But because of the nature of Macintosh paths, some additional possibilities
 165 are allowed to make using this routine give reasonable results for some
 166 common situations. In other words, you are also allowed to concatenate
 167 \&\fIpaths\fR instead of directory names (strictly speaking, a string like \*(L":a\*(R"
 168 is a path, but not a name, since it contains a punctuation character \*(L":\*(R").
 169 .Sp
 170 So, beside calls like
 171 .Sp
 172 .Vb 3
 173 \&    catdir("a") = ":a:"
 174 \&    catdir("a","b") = ":a:b:"
 175 \&    catdir() = ""                    (special case)
 176 .Ve
 177 .Sp
 178 calls like the following
 179 .Sp
 180 .Vb 5
 181 \&    catdir(":a:") = ":a:"
 182 \&    catdir(":a","b") = ":a:b:"
 183 \&    catdir(":a:","b") = ":a:b:"
 184 \&    catdir(":a:",":b:") = ":a:b:"
 185 \&    catdir(":") = ":"
 186 .Ve
 187 .Sp
 188 are allowed.
 189 .Sp
 190 Here are the rules that are used in \f(CW\*(C`catdir()\*(C'\fR; note that we try to be as
 191 compatible as possible to Unix:
 192 .RS 2
 193 .IP "1." 2
 194 The resulting path is relative by default, i.e. the resulting path will have a
 195 leading colon.
 196 .IP "2." 2
 197 A trailing colon is added automatically to the resulting path, to denote a
 198 directory.
 199 .IP "3." 2
 200 Generally, each argument has one leading \*(L":\*(R" and one trailing \*(L":\*(R"
 201 removed (if any). They are then joined together by a \*(L":\*(R". Special
 202 treatment applies for arguments denoting updir paths like \*(L"::lib:\*(R",
 203 see (4), or arguments consisting solely of colons (\*(L"colon paths\*(R"),
 204 see (5).
 205 .IP "4." 2
 206 When an updir path like \*(L":::lib::\*(R" is passed as argument, the number
 207 of directories to climb up is handled correctly, not removing leading
 208 or trailing colons when necessary. E.g.
 209 .Sp
 210 .Vb 2
 211 \&    catdir(":::a","::b","c")    = ":::a::b:c:"
 212 \&    catdir(":::a::","::b","c")  = ":::a:::b:c:"
 213 .Ve
 214 .IP "5." 2
 215 Adding a colon \*(L":\*(R" or empty string "" to a path at \fIany\fR position
 216 doesn't alter the path, i.e. these arguments are ignored. (When a "\*(L"
 217 is passed as the first argument, it has a special meaning, see
 218 (6)). This way, a colon \*(R":\*(L" is handled like a \*(R".\*(L" (curdir) on Unix,
 219 while an empty string \*(R"" is generally ignored (see
 220 \&\f(CW\*(C`Unix\->canonpath()\*(C'\fR ). Likewise, a \*(L"::\*(R" is handled like a \*(L"..\*(R"
 221 (updir), and a \*(L":::\*(R" is handled like a \*(L"../..\*(R" etc.  E.g.
 222 .Sp
 223 .Vb 2
 224 \&    catdir("a",":",":","b")   = ":a:b:"
 225 \&    catdir("a",":","::",":b") = ":a::b:"
 226 .Ve
 227 .IP "6." 2
 228 If the first argument is an empty string "" or is a volume name, i.e. matches
 229 the pattern /^[^:]+:/, the resulting path is \fBabsolute\fR.
 230 .IP "7." 2
 231 Passing an empty string "" as the first argument to \f(CW\*(C`catdir()\*(C'\fR is
 232 like passing\f(CW\*(C`File::Spec\->rootdir()\*(C'\fR as the first argument, i.e.
 233 .Sp
 234 .Vb 1
 235 \&    catdir("","a","b")          is the same as
 236 .Ve
 237 .Sp
 238 .Vb 1
 239 \&    catdir(rootdir(),"a","b").
 240 .Ve
 241 .Sp
 242 This is true on Unix, where \f(CW\*(C`catdir("","a","b")\*(C'\fR yields \*(L"/a/b\*(R" and
 243 \&\f(CW\*(C`rootdir()\*(C'\fR is \*(L"/\*(R". Note that \f(CW\*(C`rootdir()\*(C'\fR on Mac \s-1OS\s0 is the startup
 244 volume, which is the closest in concept to Unix' \*(L"/\*(R". This should help
 245 to run existing scripts originally written for Unix.
 246 .IP "8." 2
 247 For absolute paths, some cleanup is done, to ensure that the volume
 248 name isn't immediately followed by updirs. This is invalid, because
 249 this would go beyond \*(L"root\*(R". Generally, these cases are handled like
 250 their Unix counterparts:
 251 .Sp
 252 .Vb 10
 253 \& Unix:
 254 \&    Unix\->catdir("","")                 =  "/"
 255 \&    Unix\->catdir("",".")                =  "/"
 256 \&    Unix\->catdir("","..")               =  "/"              # can't go beyond root
 257 \&    Unix\->catdir("",".","..","..","a")  =  "/a"
 258 \& Mac:
 259 \&    Mac\->catdir("","")                  =  rootdir()         # (e.g. "HD:")
 260 \&    Mac\->catdir("",":")                 =  rootdir()
 261 \&    Mac\->catdir("","::")                =  rootdir()         # can't go beyond root
 262 \&    Mac\->catdir("",":","::","::","a")   =  rootdir() . "a:"  # (e.g. "HD:a:")
 263 .Ve
 264 .Sp
 265 However, this approach is limited to the first arguments following
 266 \&\*(L"root\*(R" (again, see \f(CW\*(C`Unix\->canonpath()\*(C'\fR ). If there are more
 267 arguments that move up the directory tree, an invalid path going
 268 beyond root can be created.
 269 .RE
 270 .RS 2
 271 .Sp
 272 As you've seen, you can force \f(CW\*(C`catdir()\*(C'\fR to create an absolute path
 273 by passing either an empty string or a path that begins with a volume
 274 name as the first argument. However, you are strongly encouraged not
 275 to do so, since this is done only for backward compatibility. Newer
 276 versions of File::Spec come with a method called \f(CW\*(C`catpath()\*(C'\fR (see
 277 below), that is designed to offer a portable solution for the creation
 278 of absolute paths.  It takes volume, directory and file portions and
 279 returns an entire path. While \f(CW\*(C`catdir()\*(C'\fR is still suitable for the
 280 concatenation of \fIdirectory names\fR, you are encouraged to use
 281 \&\f(CW\*(C`catpath()\*(C'\fR to concatenate \fIvolume names\fR and \fIdirectory
 282 paths\fR. E.g.
 283 .Sp
 284 .Vb 2
 285 \&    $dir      = File::Spec\->catdir("tmp","sources");
 286 \&    $abs_path = File::Spec\->catpath("MacintoshHD:", $dir,"");
 287 .Ve
 288 .Sp
 289 yields
 290 .Sp
 291 .Vb 1
 292 \&    "MacintoshHD:tmp:sources:" .
 293 .Ve
 294 .RE
 295 .IP "catfile" 2
 296 .IX Item "catfile"
 297 Concatenate one or more directory names and a filename to form a
 298 complete path ending with a filename. Resulting paths are \fBrelative\fR
 299 by default, but can be forced to be absolute (but avoid this).
 300 .Sp
 301 \&\fB\s-1IMPORTANT\s0 \s-1NOTE:\s0\fR Beginning with version 1.3 of this module, the
 302 resulting path is relative by default and \fInot\fR absolute. This
 303 decision was made due to portability reasons. Since
 304 \&\f(CW\*(C`File::Spec\->catfile()\*(C'\fR returns relative paths on all other
 305 operating systems, it will now also follow this convention on Mac \s-1OS\s0.
 306 Note that this may break some existing scripts.
 307 .Sp
 308 The last argument is always considered to be the file portion. Since
 309 \&\f(CW\*(C`catfile()\*(C'\fR uses \f(CW\*(C`catdir()\*(C'\fR (see above) for the concatenation of the
 310 directory portions (if any), the following with regard to relative and
 311 absolute paths is true:
 312 .Sp
 313 .Vb 2
 314 \&    catfile("")     = ""
 315 \&    catfile("file") = "file"
 316 .Ve
 317 .Sp
 318 but
 319 .Sp
 320 .Vb 3
 321 \&    catfile("","")        = rootdir()         # (e.g. "HD:")
 322 \&    catfile("","file")    = rootdir() . file  # (e.g. "HD:file")
 323 \&    catfile("HD:","file") = "HD:file"
 324 .Ve
 325 .Sp
 326 This means that \f(CW\*(C`catdir()\*(C'\fR is called only when there are two or more
 327 arguments, as one might expect.
 328 .Sp
 329 Note that the leading \*(L":\*(R" is removed from the filename, so that
 330 .Sp
 331 .Vb 1
 332 \&    catfile("a","b","file")  = ":a:b:file"    and
 333 .Ve
 334 .Sp
 335 .Vb 1
 336 \&    catfile("a","b",":file") = ":a:b:file"
 337 .Ve
 338 .Sp
 339 give the same answer.
 340 .Sp
 341 To concatenate \fIvolume names\fR, \fIdirectory paths\fR and \fIfilenames\fR,
 342 you are encouraged to use \f(CW\*(C`catpath()\*(C'\fR (see below).
 343 .IP "curdir" 2
 344 .IX Item "curdir"
 345 Returns a string representing the current directory. On Mac \s-1OS\s0, this is \*(L":\*(R".
 346 .IP "devnull" 2
 347 .IX Item "devnull"
 348 Returns a string representing the null device. On Mac \s-1OS\s0, this is \*(L"Dev:Null\*(R".
 349 .IP "rootdir" 2
 350 .IX Item "rootdir"
 351 Returns a string representing the root directory.  Under MacPerl,
 352 returns the name of the startup volume, since that's the closest in
 353 concept, although other volumes aren't rooted there. The name has a
 354 trailing \*(L":\*(R", because that's the correct specification for a volume
 355 name on Mac \s-1OS\s0.
 356 .Sp
 357 If Mac::Files could not be loaded, the empty string is returned.
 358 .IP "tmpdir" 2
 359 .IX Item "tmpdir"
 360 Returns the contents of \f(CW$ENV\fR{\s-1TMPDIR\s0}, if that directory exits or the
 361 current working directory otherwise. Under MacPerl, \f(CW$ENV\fR{\s-1TMPDIR\s0} will
 362 contain a path like \*(L"MacintoshHD:Temporary Items:\*(R", which is a hidden
 363 directory on your startup volume.
 364 .IP "updir" 2
 365 .IX Item "updir"
 366 Returns a string representing the parent directory. On Mac \s-1OS\s0, this is \*(L"::\*(R".
 367 .IP "file_name_is_absolute" 2
 368 .IX Item "file_name_is_absolute"
 369 Takes as argument a path and returns true, if it is an absolute path.
 370 If the path has a leading \*(L":\*(R", it's a relative path. Otherwise, it's an
 371 absolute path, unless the path doesn't contain any colons, i.e. it's a name
 372 like \*(L"a\*(R". In this particular case, the path is considered to be relative
 373 (i.e. it is considered to be a filename). Use \*(L":\*(R" in the appropriate place
 374 in the path if you want to distinguish unambiguously. As a special case,
 375 the filename '' is always considered to be absolute. Note that with version
 376 1.2 of File::Spec::Mac, this does no longer consult the local filesystem.
 377 .Sp
 378 E.g.
 379 .Sp
 380 .Vb 4
 381 \&    File::Spec\->file_name_is_absolute("a");             # false (relative)
 382 \&    File::Spec\->file_name_is_absolute(":a:b:");         # false (relative)
 383 \&    File::Spec\->file_name_is_absolute("MacintoshHD:");  # true (absolute)
 384 \&    File::Spec\->file_name_is_absolute("");              # true (absolute)
 385 .Ve
 386 .IP "path" 2
 387 .IX Item "path"
 388 Returns the null list for the MacPerl application, since the concept is
 389 usually meaningless under Mac \s-1OS\s0. But if you're using the MacPerl tool under
 390 \&\s-1MPW\s0, it gives back \f(CW$ENV\fR{Commands} suitably split, as is done in
 391 :lib:ExtUtils:MM_Mac.pm.
 392 .IP "splitpath" 2
 393 .IX Item "splitpath"
 394 .Vb 2
 395 \&    ($volume,$directories,$file) = File::Spec\->splitpath( $path );
 396 \&    ($volume,$directories,$file) = File::Spec\->splitpath( $path, $no_file );
 397 .Ve
 398 .Sp
 399 Splits a path into volume, directory, and filename portions.
 400 .Sp
 401 On Mac \s-1OS\s0, assumes that the last part of the path is a filename unless
 402 \&\f(CW$no_file\fR is true or a trailing separator \*(L":\*(R" is present.
 403 .Sp
 404 The volume portion is always returned with a trailing \*(L":\*(R". The directory portion
 405 is always returned with a leading (to denote a relative path) and a trailing \*(L":\*(R"
 406 (to denote a directory). The file portion is always returned \fIwithout\fR a leading \*(L":\*(R".
 407 Empty portions are returned as empty string ''.
 408 .Sp
 409 The results can be passed to \f(CW\*(C`catpath()\*(C'\fR to get back a path equivalent to
 410 (usually identical to) the original path.
 411 .IP "splitdir" 2
 412 .IX Item "splitdir"
 413 The opposite of \f(CW\*(C`catdir()\*(C'\fR.
 414 .Sp
 415 .Vb 1
 416 \&    @dirs = File::Spec\->splitdir( $directories );
 417 .Ve
 418 .Sp
 419 $directories should be only the directory portion of the path on systems
 420 that have the concept of a volume or that have path syntax that differentiates
 421 files from directories. Consider using \f(CW\*(C`splitpath()\*(C'\fR otherwise.
 422 .Sp
 423 Unlike just splitting the directories on the separator, empty directory names
 424 (\f(CW""\fR) can be returned. Since \f(CW\*(C`catdir()\*(C'\fR on Mac \s-1OS\s0 always appends a trailing
 425 colon to distinguish a directory path from a file path, a single trailing colon
 426 will be ignored, i.e. there's no empty directory name after it.
 427 .Sp
 428 Hence, on Mac \s-1OS\s0, both
 429 .Sp
 430 .Vb 2
 431 \&    File::Spec\->splitdir( ":a:b::c:" );    and
 432 \&    File::Spec\->splitdir( ":a:b::c" );
 433 .Ve
 434 .Sp
 435 yield:
 436 .Sp
 437 .Vb 1
 438 \&    ( "a", "b", "::", "c")
 439 .Ve
 440 .Sp
 441 while
 442 .Sp
 443 .Vb 1
 444 \&    File::Spec\->splitdir( ":a:b::c::" );
 445 .Ve
 446 .Sp
 447 yields:
 448 .Sp
 449 .Vb 1
 450 \&    ( "a", "b", "::", "c", "::")
 451 .Ve
 452 .IP "catpath" 2
 453 .IX Item "catpath"
 454 .Vb 1
 455 \&    $path = File::Spec\->catpath($volume,$directory,$file);
 456 .Ve
 457 .Sp
 458 Takes volume, directory and file portions and returns an entire path. On Mac \s-1OS\s0,
 459 \&\f(CW$volume\fR, \f(CW$directory\fR and \f(CW$file\fR are concatenated.  A ':' is inserted if need be. You
 460 may pass an empty string for each portion. If all portions are empty, the empty
 461 string is returned. If \f(CW$volume\fR is empty, the result will be a relative path,
 462 beginning with a ':'. If \f(CW$volume\fR and \f(CW$directory\fR are empty, a leading \*(L":\*(R" (if any)
 463 is removed form \f(CW$file\fR and the remainder is returned. If \f(CW$file\fR is empty, the
 464 resulting path will have a trailing ':'.
 465 .IP "abs2rel" 2
 466 .IX Item "abs2rel"
 467 Takes a destination path and an optional base path and returns a relative path
 468 from the base path to the destination path:
 469 .Sp
 470 .Vb 2
 471 \&    $rel_path = File::Spec\->abs2rel( $path ) ;
 472 \&    $rel_path = File::Spec\->abs2rel( $path, $base ) ;
 473 .Ve
 474 .Sp
 475 Note that both paths are assumed to have a notation that distinguishes a
 476 directory path (with trailing ':') from a file path (without trailing ':').
 477 .Sp
 478 If \f(CW$base\fR is not present or '', then the current working directory is used.
 479 If \f(CW$base\fR is relative, then it is converted to absolute form using \f(CW\*(C`rel2abs()\*(C'\fR.
 480 This means that it is taken to be relative to the current working directory.
 481 .Sp
 482 If \f(CW$path\fR and \f(CW$base\fR appear to be on two different volumes, we will not
 483 attempt to resolve the two paths, and we will instead simply return
 484 \&\f(CW$path\fR.  Note that previous versions of this module ignored the volume
 485 of \f(CW$base\fR, which resulted in garbage results part of the time.
 486 .Sp
 487 If \f(CW$base\fR doesn't have a trailing colon, the last element of \f(CW$base\fR is
 488 assumed to be a filename.  This filename is ignored.  Otherwise all path
 489 components are assumed to be directories.
 490 .Sp
 491 If \f(CW$path\fR is relative, it is converted to absolute form using \f(CW\*(C`rel2abs()\*(C'\fR.
 492 This means that it is taken to be relative to the current working directory.
 493 .Sp
 494 Based on code written by Shigio Yamaguchi.
 495 .IP "rel2abs" 2
 496 .IX Item "rel2abs"
 497 Converts a relative path to an absolute path:
 498 .Sp
 499 .Vb 2
 500 \&    $abs_path = File::Spec\->rel2abs( $path ) ;
 501 \&    $abs_path = File::Spec\->rel2abs( $path, $base ) ;
 502 .Ve
 503 .Sp
 504 Note that both paths are assumed to have a notation that distinguishes a
 505 directory path (with trailing ':') from a file path (without trailing ':').
 506 .Sp
 507 If \f(CW$base\fR is not present or '', then \f(CW$base\fR is set to the current working
 508 directory. If \f(CW$base\fR is relative, then it is converted to absolute form
 509 using \f(CW\*(C`rel2abs()\*(C'\fR. This means that it is taken to be relative to the
 510 current working directory.
 511 .Sp
 512 If \f(CW$base\fR doesn't have a trailing colon, the last element of \f(CW$base\fR is
 513 assumed to be a filename.  This filename is ignored.  Otherwise all path
 514 components are assumed to be directories.
 515 .Sp
 516 If \f(CW$path\fR is already absolute, it is returned and \f(CW$base\fR is ignored.
 517 .Sp
 518 Based on code written by Shigio Yamaguchi.
 519 .SH "AUTHORS"
 520 .IX Header "AUTHORS"
 521 See the authors list in \fIFile::Spec\fR. Mac \s-1OS\s0 support by Paul Schinder
 522 <schinder@pobox.com> and Thomas Wegner <wegner_thomas@yahoo.com>.
 523 .SH "COPYRIGHT"
 524 .IX Header "COPYRIGHT"
 525 Copyright (c) 2004 by the Perl 5 Porters.  All rights reserved.
 526 .PP
 527 This program is free software; you can redistribute it and/or modify
 528 it under the same terms as Perl itself.
 529 .SH "SEE ALSO"
 530 .IX Header "SEE ALSO"
 531 See File::Spec and File::Spec::Unix.  This package overrides the
 532 implementation of these methods, not the semantics.