.\" Modified Sun Sep 24 20:15:46 2000 by aeb, following Petter Reinholdtsen.
.\" Modified 2001-12-26 by aeb, following Joey. Added versionsort.
.\"
-.TH SCANDIR 3 2013-04-19 "GNU" "Linux Programmer's Manual"
+.\" The pieces on scandirat(3) were copyright and licensed as follows.
+.\"
+.\" Copyright (c) 2012, Mark R. Bannister <cambridge@users.sourceforge.net>
+.\" based on text in mkfifoat.3 Copyright (c) 2006, Michael Kerrisk
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
+.\"
+.TH SCANDIR 3 2014-02-21 "GNU" "Linux Programmer's Manual"
.SH NAME
-scandir, alphasort, versionsort \- scan a directory for matching entries
+scandir, scandirat, alphasort, versionsort \- scan
+a directory for matching entries
.SH SYNOPSIS
.nf
.B #include <dirent.h>
.BI "int alphasort(const void *" a ", const void *" b );
.sp
.BI "int versionsort(const void *" a ", const void *" b );
+
+.BR "#include <fcntl.h>" " /* Definition of AT_* constants */"
+.B #include <dirent.h>
+.sp
+.fi
+.BI "int scandirat(int " dirfd ", const char *" dirp ","
+.BI "struct dirent ***" namelist ,
+.nf
+.RS
+.BI "int (*" filter ")(const struct dirent *),"
+.BI "int (*" compar ")(const struct dirent **, const struct dirent **));"
+.RE
.fi
.sp
.in -4n
.sp
.BR scandir (),
.BR alphasort ():
+.br
+.RS 4
+.PD 0
+.ad b
_BSD_SOURCE || _SVID_SOURCE
.br
+|| /* Since glibc 2.10: */
+.RS 4
+(_POSIX_C_SOURCE\ >=\ 200809L || _XOPEN_SOURCE\ >=\ 700)
+.RE
+.PD
+.RE
+.sp
.BR versionsort ():
_GNU_SOURCE
+.sp
+.BR scandirat ():
+_GNU_SOURCE
.SH DESCRIPTION
The
.BR scandir ()
the latter using
.BR strverscmp (3)
on the strings \fI(*a)\->d_name\fP and \fI(*b)\->d_name\fP.
+.SS scandirat()
+The
+.BR scandirat ()
+function operates in exactly the same way as
+.BR scandir (),
+except for the differences described here.
+
+If the pathname given in
+.I dirp
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.I dirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR scandir ()
+for a relative pathname).
+
+If
+.I dirp
+is relative and
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I dirp
+is interpreted relative to the current working
+directory of the calling process (like
+.BR scandir ()).
+
+If
+.I dirp
+is absolute, then
+.I dirfd
+is ignored.
+.PP
+See
+.BR openat (2)
+for an explanation of the need for
+.BR scandirat ().
.SH RETURN VALUE
The
.BR scandir ()
.TP
.B ENOTDIR
The path in \fIdirp\fR is not a directory.
+.PP
+The following additional errors can occur for
+.BR scandirat ():
+.TP
+.B EBADF
+.I dirfd
+is not a valid file descriptor.
+.TP
+.B ENOTDIR
+.I dirp
+is a relative path and
+.I dirfd
+is a file descriptor referring to a file other than a directory.
.SH VERSIONS
.BR versionsort ()
was added to glibc in version 2.1.
+
+.BR scandirat ()
+was added to glibc in version 2.15.
.SH CONFORMING TO
-.BR alphasort ()
-and
-.BR scandir ()
-are specified in POSIX.1-2008, and are widely available.
+.BR alphasort (),
+.BR scandir ():
+4.3BSD, POSIX.1-2008.
+
.BR versionsort ()
-is a GNU extension.
-.LP
-The functions
-.BR scandir ()
and
-.BR alphasort ()
-are from 4.3BSD, and have been available under Linux since libc4.
-Libc4 and libc5 use the more precise prototype
-.sp
-.nf
- int alphasort(const struct dirent ** a,
- const struct dirent **b);
-.fi
-.sp
-but glibc 2.0 returns to the imprecise BSD prototype.
-.LP
-The function
-.BR versionsort ()
-is a GNU extension, available since glibc 2.1.
-.LP
+.BR scandirat ()
+are GNU extensions.
+.\" .LP
+.\" The functions
+.\" .BR scandir ()
+.\" and
+.\" .BR alphasort ()
+.\" are from 4.3BSD, and have been available under Linux since libc4.
+.\" Libc4 and libc5 use the more precise prototype
+.\" .sp
+.\" .nf
+.\" int alphasort(const struct dirent ** a,
+.\" const struct dirent **b);
+.\" .fi
+.\" .sp
+.\" but glibc 2.0 returns to the imprecise BSD prototype.
+.SH NOTES
Since glibc 2.1,
.BR alphasort ()
calls
.BR opendir (3),
.BR readdir (3),
.BR rewinddir (3),
-.BR scandirat (3),
.BR seekdir (3),
.BR strcmp (3),
.BR strcoll (3),
.BR strverscmp (3),
.BR telldir (3)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.