.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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::Listing 3pm"
.TH File::Listing 3pm "2022-04-21" "perl v5.34.0" "User Contributed Perl Documentation"
.\" 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::Listing \- Parse directory listing
.SH "VERSION"
.IX Header "VERSION"
version 6.15
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\& use File::Listing qw(parse_dir);
\& $ENV{LANG} = "C";  # dates in non\-English locales not supported
\& foreach my $file (parse_dir(\`ls \-l\`)) {
\&     my ($name, $type, $size, $mtime, $mode) = @$file;
\&     next if $type ne \*(Aqf\*(Aq; # plain file
\&     #...
\& }
\& 
\& # directory listing can also be read from a file
\& open my $listing, "zcat ls\-lR.gz|";
\& $dir = parse_dir($listing, \*(Aq+0000\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module exports a single function called \f(CW\*(C`parse_dir\*(C'\fR, which can be
used to parse directory listings.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "parse_dir"
.IX Subsection "parse_dir"
.Vb 8
\& my $dir = parse_dir( $listing );
\& my $dir = parse_dir( $listing, $time_zone );
\& my $dir = parse_dir( $listing, $time_zone, $type );
\& my $dir = parse_dir( $listing, $time_zone, $type, $error );
\& my @files = parse_dir( $listing );
\& my @files = parse_dir( $listing, $time_zone );
\& my @files = parse_dir( $listing, $time_zone, $type );
\& my @files = parse_dir( $listing, $time_zone, $type, $error );
.Ve
.PP
The first parameter (\f(CW$listing\fR) is the directory listing to parse.
It can be a scalar, a reference to an array of directory lines or a
glob representing a filehandle to read the directory listing from.
.PP
The second parameter (\f(CW$time_zone\fR) is the time zone to use when
parsing time stamps in the listing. If this value is undefined,
then the local time zone is assumed.
.PP
The third parameter (\f(CW$type\fR) is the type of listing to assume.
Currently supported formats are \f(CW\*(Aqunix\*(Aq\fR, \f(CW\*(Aqapache\*(Aq\fR and
\&\f(CW\*(Aqdosftp\*(Aq\fR. The default value is \f(CW\*(Aqunix\*(Aq\fR. Ideally, the listing
type should be determined automatically.
.PP
The fourth parameter (\f(CW$error\fR) specifies how unparseable lines
should be treated. Values can be \f(CW\*(Aqignore\*(Aq\fR, \f(CW\*(Aqwarn\*(Aq\fR or a code reference.
Warn means that the perl \fBwarn()\fR function will be called.  If a code
reference is passed, then this routine will be called and the return
value from it will be incorporated in the listing.  The default is
\&\f(CW\*(Aqignore\*(Aq\fR.
.PP
Only the first parameter is mandatory.
.PP
.Vb 4
\& # list context
\& foreach my $file (parse_dir($listing)) {
\&     my($name, $type, $size, $mtime, $mode) = @$file;
\& }
\& 
\& # scalar context
\& my $dir = parse_dir($listing);
\& foreach my $file (@$dir) {
\&     my($name, $type, $size, $mtime, $mode) = @$file;
\& }
.Ve
.PP
The return value from \fBparse_dir()\fR is a list of directory entries.
In a scalar context the return value is a reference to the list.
The directory entries are represented by an array consisting of:
.IP "name" 4
.IX Item "name"
The name of the file.
.IP "type" 4
.IX Item "type"
One of: \f(CW\*(C`f\*(C'\fR file, \f(CW\*(C`d\*(C'\fR directory, \f(CW\*(C`l\*(C'\fR symlink, \f(CW\*(C`?\*(C'\fR unknown.
.IP "size" 4
.IX Item "size"
The size of the file.
.IP "time" 4
.IX Item "time"
The number of seconds since January 1, 1970.
.IP "mode" 4
.IX Item "mode"
Bitmask a la the mode returned by \f(CW\*(C`stat\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "File::Listing::Ftpcopy" 4
.IX Item "File::Listing::Ftpcopy"
Provides the same interface but uses \s-1XS\s0 and the parser implementation from \f(CW\*(C`ftpcopy\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Original author: Gisle Aas
.PP
Current maintainer: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Adam Kennedy
.PP
Adam Sjogren
.PP
Alex Kapranoff
.PP
Alexey Tourbin
.PP
Andreas J. Koenig
.PP
Bill Mann
.PP
Bron Gondwana
.PP
\&\s-1DAVIDRW\s0
.PP
Daniel Hedlund
.PP
David E. Wheeler
.PP
David Steinbrunner
.PP
Erik Esterer
.PP
\&\s-1FWILES\s0
.PP
Father Chrysostomos
.PP
Gavin Peters
.PP
Graeme Thompson
.PP
Hans-H. Froehlich
.PP
Ian Kilgore
.PP
Jacob J
.PP
Mark Stosberg
.PP
Mike Schilli
.PP
Ondrej Hanak
.PP
Peter John Acklam
.PP
Peter Rabbitson
.PP
Robert Stone
.PP
Rolf Grossmann
.PP
Sean M. Burke
.PP
Simon Legner
.PP
Slaven Rezic
.PP
Spiros Denaxas
.PP
Steve Hay
.PP
Todd Lipcon
.PP
Tom Hukins
.PP
Tony Finch
.PP
Toru Yamaguchi
.PP
Ville Skyttä
.PP
Yuri Karaban
.PP
Zefram
.PP
amire80
.PP
jefflee
.PP
john9art
.PP
mschilli
.PP
murphy
.PP
phrstbrn
.PP
ruff
.PP
sasao
.PP
uid39246
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 1996\-2020 by Gisle Aas.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.