.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Dirent 3pm"
.TH Dirent 3pm "2011-08-22" "perl v5.20.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"
IO::Dirent \- Access to dirent structs returned by readdir
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use IO::Dirent;
\&
\&  ## slurp\-style
\&  opendir DIR, "/usr/local/foo";
\&  my @entries = readdirent(DIR);
\&  closedir DIR;
\&
\&  print $entries[0]\->{name}, "\en";
\&  print $entries[0]\->{type}, "\en";
\&  print $entries[0]\->{inode}, "\en";
\&
\&  ## using the enumerator
\&  opendir DIR, "/etc";
\&  while( my $entry = nextdirent(DIR) ) {
\&    print $entry\->{name} . "\en";
\&  }
\&  closedir DIR;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBreaddirent\fR returns a list of hashrefs. Each hashref contains the
name of the directory entry, its inode for the filesystem it resides
on and its type (if available). If the file type or inode are not
available, it won't be there!
.PP
\&\fBnextdirent\fR returns the next dirent as a hashref, allowing you to
iterate over directory entries one by one. This may be helpful in
low-memory situations or where you have enormous directories.
.PP
\&\fBIO::Dirent\fR exports the following symbols by default:
.PP
.Vb 1
\&    readdirent
\&
\&    nextdirent
.Ve
.PP
The following tags may be exported to your namespace:
.PP
.Vb 1
\&    ALL
.Ve
.PP
which includes \fBreaddirent\fR, \fBnextdirent\fR and the following symbols:
.PP
.Vb 9
\&    DT_UNKNOWN
\&    DT_FIFO
\&    DT_CHR
\&    DT_DIR
\&    DT_BLK
\&    DT_REG
\&    DT_LNK
\&    DT_SOCK
\&    DT_WHT
.Ve
.PP
These symbols can be used to test the file type returned by
\&\fBreaddirent\fR in the following manner:
.PP
.Vb 2
\&    for my $entry ( readdirent(DIR) ) {
\&        next unless $entry\->{\*(Aqtype\*(Aq} == DT_LNK;
\&
\&        print $entry\->{\*(Aqname\*(Aq} . " is a symbolic link.\en";
\&    }
.Ve
.PP
For platforms that do not implement file type in its dirent struct,
\&\fBreaddirent\fR will return a hashref with a single key/value of 'name'
and the filename (effectively the same as readdir). This is subject
to change, if I can implement some of the to do items below.
.SH "CAVEATS"
.IX Header "CAVEATS"
This was written on FreeBSD and \s-1OS X\s0 which implement a robust (but
somewhat non-standard) dirent struct and which includes a file type
entry. I have plans to make this module more portable and useful by
doing a stat on each directory entry to find the file type and inode
number when the dirent.h does not implement it otherwise.
.PP
Improvements and additional ports are welcome.
.SH "TO DO"
.IX Header "TO DO"
.IP "\(bu" 4
For platforms that do not implement a dirent struct with file type,
do a stat on the entry and populate the structure anyway.
.IP "\(bu" 4
Do some memory profiling (I'm not sure if I have any leaks or not).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002, 2011 Scott Wiersdorf.
.PP
This library is free software; you can redistribute it and/or modify
it under the terms of the Perl Artistic License.
.SH "AUTHOR"
.IX Header "AUTHOR"
Scott Wiersdorf, <scott@perlcode.org>
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Thanks to Nick Ing-Simmons for his help on the perl-xs mailing list.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIdirent\fR\|(5), perlxstut, perlxs, perlguts, perlapi
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2007 by Scott Wiersdorf
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.1 or,
at your option, any later version of Perl 5 you may have available.