diff options
Diffstat (limited to 'man3/scandir.3')
| -rw-r--r-- | man3/scandir.3 | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/man3/scandir.3 b/man3/scandir.3 new file mode 100644 index 0000000..1abda05 --- /dev/null +++ b/man3/scandir.3 @@ -0,0 +1,311 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:26:16 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Thu Apr 11 17:11:33 1996 by Andries Brouwer (aeb@cwi.nl): +.\" Corrected type of compar routines, as suggested by +.\" Miguel Barreiro (enano@avalon.yaix.es). Added example. +.\" Modified Sun Sep 24 20:15:46 2000 by aeb, following Petter Reinholdtsen. +.\" Modified 2001-12-26 by aeb, following Joey. Added versionsort. +.\" +.\" 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 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH scandir 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +scandir, scandirat, alphasort, versionsort \- scan +a directory for matching entries +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <dirent.h> +.PP +.BI "int scandir(const char *restrict " dirp , +.BI " struct dirent ***restrict " namelist , +.BI " int (*" filter ")(const struct dirent *)," +.BI " int (*" compar ")(const struct dirent **," +.B " const struct dirent **));" +.PP +.BI "int alphasort(const struct dirent **" a ", const struct dirent **" b ); +.BI "int versionsort(const struct dirent **" a ", const struct dirent **" b ); +.PP +.BR "#include <fcntl.h>" " /* Definition of AT_* constants */" +.B #include <dirent.h> +.PP +.BI "int scandirat(int " dirfd ", const char *restrict " dirp , +.BI " struct dirent ***restrict " namelist , +.BI " int (*" filter ")(const struct dirent *)," +.BI " int (*" compar ")(const struct dirent **," +.B " const struct dirent **));" +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR scandir (), +.BR alphasort (): +.nf + /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.PP +.BR versionsort (): +.nf + _GNU_SOURCE +.fi +.PP +.BR scandirat (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR scandir () +function scans the directory \fIdirp\fP, calling +\fIfilter\fP() on each directory entry. +Entries for which +\fIfilter\fP() returns nonzero are stored in strings allocated via +.BR malloc (3), +sorted using +.BR qsort (3) +with the comparison +function \fIcompar\fP(), and collected in array \fInamelist\fP +which is allocated via +.BR malloc (3). +If \fIfilter\fP is NULL, all entries are selected. +.PP +The +.BR alphasort () +and +.BR versionsort () +functions can be used as the comparison function +.IR compar (). +The former sorts directory entries using +.BR strcoll (3), +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. +.PP +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). +.PP +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 ()). +.PP +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 () +function returns the number of directory entries +selected. +On error, \-1 is returned, with +.I errno +set to indicate the error. +.PP +The +.BR alphasort () +and +.BR versionsort () +functions return an integer less than, equal to, +or greater than zero if the first argument is considered to be +respectively less than, equal to, or greater than the second. +.SH ERRORS +.TP +.B EBADF +.RB ( scandirat ()) +.I dirp +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B ENOENT +The path in \fIdirp\fR does not exist. +.TP +.B ENOMEM +Insufficient memory to complete the operation. +.TP +.B ENOTDIR +The path in \fIdirp\fR is not a directory. +.TP +.B ENOTDIR +.RB ( scandirat ()) +.I dirp +is a relative pathname and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR scandir (), +.BR scandirat () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR alphasort (), +.BR versionsort () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH STANDARDS +.TP +.BR alphasort () +.TQ +.BR scandir () +POSIX.1-2008. +.TP +.BR versionsort () +.TQ +.BR scandirat () +GNU. +.SH HISTORY +.TP +.BR alphasort () +.TQ +.BR scandir () +4.3BSD, POSIX.1-2008. +.TP +.BR versionsort () +glibc 2.1. +.TP +.BR scandirat () +glibc 2.15. +.\" .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 strcoll (3); +earlier it used +.BR strcmp (3). +.PP +Before glibc 2.10, the two arguments of +.BR alphasort () +and +.BR versionsort () +were typed as +.IR "const void\ *" . +When +.BR alphasort () +was standardized in POSIX.1-2008, +the argument type was specified as the type-safe +.IR "const struct dirent\ **", +and glibc 2.10 changed the definition of +.BR alphasort () +(and the nonstandard +.BR versionsort ()) +to match the standard. +.SH EXAMPLES +The program below prints a list of the files in the current directory +in reverse order. +.\" +.SS Program source +\& +.\" SRC BEGIN (scandir.c) +.EX +#define _DEFAULT_SOURCE +#include <dirent.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(void) +{ + struct dirent **namelist; + int n; +\& + n = scandir(".", &namelist, NULL, alphasort); + if (n == \-1) { + perror("scandir"); + exit(EXIT_FAILURE); + } +\& + while (n\-\-) { + printf("%s\en", namelist[n]\->d_name); + free(namelist[n]); + } + free(namelist); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR closedir (3), +.BR fnmatch (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR seekdir (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strverscmp (3), +.BR telldir (3) |