diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/File::Spec::Unix.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/File::Spec::Unix.3pm | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/File::Spec::Unix.3pm b/upstream/mageia-cauldron/man3pm/File::Spec::Unix.3pm new file mode 100644 index 00000000..7d93fac9 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/File::Spec::Unix.3pm @@ -0,0 +1,266 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "File::Spec::Unix 3pm" +.TH File::Spec::Unix 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +File::Spec::Unix \- File::Spec for Unix, base for other File::Spec modules +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& require File::Spec::Unix; # Done automatically by File::Spec +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Methods for manipulating file specifications. Other File::Spec +modules, such as File::Spec::Mac, inherit from File::Spec::Unix and +override specific methods. +.SH METHODS +.IX Header "METHODS" +.IP \fBcanonpath()\fR 2 +.IX Item "canonpath()" +No physical check on the filesystem, but a logical cleanup of a +path. On UNIX eliminates successive slashes and successive "/.". +.Sp +.Vb 1 +\& $cpath = File::Spec\->canonpath( $path ) ; +.Ve +.Sp +Note that this does *not* collapse \fIx/../y\fR sections into \fIy\fR. This +is by design. If \fI/foo\fR on your system is a symlink to \fI/bar/baz\fR, +then \fI/foo/../quux\fR is actually \fI/bar/quux\fR, not \fI/quux\fR as a naive +\&\fI../\fR\-removal would give you. If you want to do this kind of +processing, you probably want \f(CW\*(C`Cwd\*(C'\fR's \f(CWrealpath()\fR function to +actually traverse the filesystem cleaning up paths like this. +.IP \fBcatdir()\fR 2 +.IX Item "catdir()" +Concatenate two or more directory names to form a complete path ending +with a directory. But remove the trailing slash from the resulting +string, because it doesn't look good, isn't necessary and confuses +OS2. Of course, if this is the root directory, don't cut off the +trailing slash :\-) +.IP catfile 2 +.IX Item "catfile" +Concatenate one or more directory names and a filename to form a +complete path ending with a filename +.IP curdir 2 +.IX Item "curdir" +Returns a string representation of the current directory. "." on UNIX. +.IP devnull 2 +.IX Item "devnull" +Returns a string representation of the null device. "/dev/null" on UNIX. +.IP rootdir 2 +.IX Item "rootdir" +Returns a string representation of the root directory. "/" on UNIX. +.IP tmpdir 2 +.IX Item "tmpdir" +Returns a string representation of the first writable directory from +the following list or the current directory if none from the list are +writable: +.Sp +.Vb 2 +\& $ENV{TMPDIR} +\& /tmp +.Ve +.Sp +If running under taint mode, and if \f(CW$ENV\fR{TMPDIR} +is tainted, it is not used. +.IP updir 2 +.IX Item "updir" +Returns a string representation of the parent directory. ".." on UNIX. +.IP no_upwards 2 +.IX Item "no_upwards" +Given a list of file names, strip out those that refer to a parent +directory. (Does not strip symlinks, only '.', '..', and equivalents.) +.IP case_tolerant 2 +.IX Item "case_tolerant" +Returns a true or false value indicating, respectively, that alphabetic +is not or is significant when comparing file specifications. +.IP file_name_is_absolute 2 +.IX Item "file_name_is_absolute" +Takes as argument a path and returns true if it is an absolute path. +.Sp +This does not consult the local filesystem on Unix, Win32, OS/2 or Mac +OS (Classic). It does consult the working environment for VMS (see +"file_name_is_absolute" in File::Spec::VMS). +.IP path 2 +.IX Item "path" +Takes no argument, returns the environment variable PATH as an array. +.IP join 2 +.IX Item "join" +join is the same as catfile. +.IP splitpath 2 +.IX Item "splitpath" +.Vb 3 +\& ($volume,$directories,$file) = File::Spec\->splitpath( $path ); +\& ($volume,$directories,$file) = File::Spec\->splitpath( $path, +\& $no_file ); +.Ve +.Sp +Splits a path into volume, directory, and filename portions. On systems +with no concept of volume, returns '' for volume. +.Sp +For systems with no syntax differentiating filenames from directories, +assumes that the last file is a path unless \f(CW$no_file\fR is true or a +trailing separator or /. or /.. is present. On Unix this means that \f(CW$no_file\fR +true makes this return ( '', \f(CW$path\fR, '' ). +.Sp +The directory portion may or may not be returned with a trailing '/'. +.Sp +The results can be passed to "\fBcatpath()\fR" to get back a path equivalent to +(usually identical to) the original path. +.IP splitdir 2 +.IX Item "splitdir" +The opposite of "\fBcatdir()\fR". +.Sp +.Vb 1 +\& @dirs = File::Spec\->splitdir( $directories ); +.Ve +.Sp +\&\f(CW$directories\fR must be only the directory portion of the path on systems +that have the concept of a volume or that have path syntax that differentiates +files from directories. +.Sp +Unlike just splitting the directories on the separator, empty +directory names (\f(CW\*(Aq\*(Aq\fR) can be returned, because these are significant +on some OSs. +.Sp +On Unix, +.Sp +.Vb 1 +\& File::Spec\->splitdir( "/a/b//c/" ); +.Ve +.Sp +Yields: +.Sp +.Vb 1 +\& ( \*(Aq\*(Aq, \*(Aqa\*(Aq, \*(Aqb\*(Aq, \*(Aq\*(Aq, \*(Aqc\*(Aq, \*(Aq\*(Aq ) +.Ve +.IP \fBcatpath()\fR 2 +.IX Item "catpath()" +Takes volume, directory and file portions and returns an entire path. Under +Unix, \f(CW$volume\fR is ignored, and directory and file are concatenated. A '/' is +inserted if needed (though if the directory portion doesn't start with +\&'/' it is not added). On other OSs, \f(CW$volume\fR is significant. +.IP abs2rel 2 +.IX Item "abs2rel" +Takes a destination path and an optional base path returns a relative path +from the base path to the destination path: +.Sp +.Vb 2 +\& $rel_path = File::Spec\->abs2rel( $path ) ; +\& $rel_path = File::Spec\->abs2rel( $path, $base ) ; +.Ve +.Sp +If \f(CW$base\fR is not present or '', then \fBcwd()\fR is used. If \f(CW$base\fR is +relative, then it is converted to absolute form using +"\fBrel2abs()\fR". This means that it is taken to be relative to +\&\fBcwd()\fR. +.Sp +On systems that have a grammar that indicates filenames, this ignores the +\&\f(CW$base\fR filename. Otherwise all path components are assumed to be +directories. +.Sp +If \f(CW$path\fR is relative, it is converted to absolute form using "\fBrel2abs()\fR". +This means that it is taken to be relative to \fBcwd()\fR. +.Sp +No checks against the filesystem are made, so the result may not be correct if +\&\f(CW$base\fR contains symbolic links. (Apply +\&\fBCwd::abs_path()\fR beforehand if that +is a concern.) On VMS, there is interaction with the working environment, as +logicals and macros are expanded. +.Sp +Based on code written by Shigio Yamaguchi. +.IP \fBrel2abs()\fR 2 +.IX Item "rel2abs()" +Converts a relative path to an absolute path. +.Sp +.Vb 2 +\& $abs_path = File::Spec\->rel2abs( $path ) ; +\& $abs_path = File::Spec\->rel2abs( $path, $base ) ; +.Ve +.Sp +If \f(CW$base\fR is not present or '', then \fBcwd()\fR is used. If \f(CW$base\fR is +relative, then it is converted to absolute form using +"\fBrel2abs()\fR". This means that it is taken to be relative to +\&\fBcwd()\fR. +.Sp +On systems that have a grammar that indicates filenames, this ignores +the \f(CW$base\fR filename. Otherwise all path components are assumed to be +directories. +.Sp +If \f(CW$path\fR is absolute, it is cleaned up and returned using "\fBcanonpath()\fR". +.Sp +No checks against the filesystem are made. On VMS, there is +interaction with the working environment, as logicals and +macros are expanded. +.Sp +Based on code written by Shigio Yamaguchi. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 2004 by the Perl 5 Porters. All rights reserved. +.PP +This program is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. +.PP +Please submit bug reports at <https://github.com/Perl/perl5/issues>. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +File::Spec |