名称

scandir，scandirat，alphasort，versionsort-扫描目录以查找匹配条目

Linux程序员手册 第3部分
更新日期： 2020-06-09

属性

有关本节中使用的术语的说明，请参见attribute(7)。

返回值

scandir()函数返回所选目录条目的数量。发生错误时，将返回-1，并设置errno以指示错误原因。

如果第一个参数被认为分别小于，等于或大于第二个参数，则alphasort()和versionsort()函数将返回一个小于，等于或大于零的整数。

备注

从glibc 2.1开始，alphasort()调用strcoll(3);之前它使用strcmp(3)。

在glibc 2.10之前，alphasort()和versionsort()的两个参数键入为const void *。当在POSIX.1-2008中将alphasort()标准化时，将参数类型指定为类型安全的const struct dirent **，并且glibc 2.10更改了alphasort()的定义(以及非标准versionsort())以匹配标准。

示例

下面的程序以相反的顺序打印当前目录中的文件列表。

Program source

#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\n", namelist[n]->d_name);
        free(namelist[n]);
    }
    free(namelist);

    exit(EXIT_SUCCESS);
}

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。

版本

versionsort()已在版本2.1中添加到glibc。

scandirat()已在2.15版中添加到glibc。

另外参见

closeirir(3)，fnmatch(3)，opendir(3)，readdir(3)，rewinddir(3)，seekdir(3)，strcmp(3)，strcoll(3)，strverscmp(3)，telldir(3)

说明

scandir()函数扫描目录dirp，在每个目录条目上调用filter()。 filter()返回非零的条目存储在通过malloc(3)分配的字符串中，使用qsort(3)和比较函数compar()进行排序，并收集在通过malloc(3)分配的数组名称列表中。如果filter为NULL，则选择所有条目。

alphasort()和versionsort()函数可用作比较函数compar()。前者使用strcoll(3)对目录条目进行排序，后者使用strverscmp(3)对字符串(* a)-> d_name和(* b)-> d_name进行排序。

scandirat()

除了这里描述的差异之外，scandirat()函数的操作方式与scandir()完全相同。

如果dirp中给定的路径名​​是相对路径名，则将其相对于文件描述符dirfd所引用的目录进行解释(而不是相对于调用进程的当前工作目录，这是相对路径名的scandir()所做的) 。

如果dirp是相对的，并且dirfd是特殊值AT_FDCWD，则将dirp相对于调用进程的当前工作目录进行解释(例如scandir())。

如果dirp是绝对的，则dirfd被忽略。

有关对scandirat()的需求的说明，请参见openat(2)。

语法

#include <dirent.h>

int scandir(const char *dirp, struct dirent ***namelist,

int(* filter)(const struct dirent *)，int(* compar)(const struct dirent **，const struct dirent **));

int versionsort(const struct dirent **a, const struct dirent **b);

#include <fcntl.h>/* Definition of AT_* constants */
#include <dirent.h>

int scandirat(int dirfd, const char *dirp,

struct dirent ***namelist,

int(* filter)(const struct dirent *)，int(* compar)(const struct dirent **，const struct dirent **));

glibc的功能测试宏要求(请参阅feature_test_macros(7))：

scandir()，alphasort()：

/ *自glibc 2.10起：* / _POSIX_C_SOURCE>= 200809L || / * Glibc版本

versionsort()：_GNU_SOURCE

scandirat()：_ GNU_SOURCE

遵循规范

alphasort()，scandir()：4.3BSD，POSIX.1-2008。

versionsort()和scandirat()是GNU扩展。

错误说明

ENOENT

dirp中的路径不存在。

ENOMEM

内存不足，无法完成操作。

ENOTDIR

dirp中的路径不是目录。

scandirat()可能会发生以下其他错误：

EBADF

dirfd不是有效的文件描述符。

ENOTDIR

dirp是相对路径，而dirfd是引用目录以外的文件的文件描述符。