dirent

dirent 提供目录流操作功能，支持目录的打开、读取、遍历、定位与关闭，以及目录项的扫描、过滤与排序。

头文件清单

#include "open_source/musl/include/dirent.h"

接口清单

接口名称	功能简述
alphasort	比较两个目录项名称的字母顺序，用于scandir排序回调
closedir	关闭由opendir打开的目录流
dirfd	获取目录流关联的文件描述符
fdopendir	通过文件描述符创建目录流
opendir	打开指定路径的目录，返回目录流指针
readdir	从目录流中读取下一个目录项
readdir_r	线程安全地读取目录流中的下一个目录项
rewinddir	将目录流的读取位置重置到目录开头
scandir	扫描目录并根据过滤和排序函数筛选目录项
seekdir	设置目录流的读取位置到指定偏移
telldir	获取目录流当前的读取位置

Functions

alphasort

int alphasort(const struct dirent **, const struct dirent **)

头文件清单

#include "open_source/musl/include/dirent.h"

功能说明

比较两个目录项的名称，按字母顺序排序
用于scandir函数的排序比较回调
排序依据为目录项的d_name字段，使用strcoll进行区域敏感的字符串比较

入参

名称	参数类型	详细说明	约束取值范围
a	const struct dirent **	指向第一个目录项指针的指针	非NULL
b	const struct dirent **	指向第二个目录项指针的指针	非NULL

返回值

返回类型：int

返回值	文字含义	触发场景
< 0	a排在b之前	a的名称字母序小于b
0	a与b相等	a的名称与b相同
> 0	a排在b之后	a的名称字母序大于b

closedir

int closedir(DIR *)

头文件清单

#include "open_source/musl/include/dirent.h"

功能说明

前置条件

调用时序约束：当前接口必须在opendir或fdopendir成功返回后调用
依赖关系：传入的DIR指针必须为opendir或fdopendir返回的有效目录流指针

入参

名称	参数类型	详细说明	约束取值范围
dir	DIR *	指向由opendir或fdopendir返回的目录流指针	非NULL，须为有效目录流指针

返回值

返回类型：int

返回值	文字含义	触发场景
0	关闭成功	目录流正常关闭
-1	关闭失败	目录流无效或关闭出错

dirfd

int dirfd(DIR *)

头文件清单

#include "open_source/musl/include/dirent.h"

功能说明

获取与目录流关联的底层文件描述符
返回的文件描述符可用于后续的文件操作
文件描述符在目录流关闭后失效

入参

名称	参数类型	详细说明	约束取值范围
dir	DIR *	指向由opendir或fdopendir返回的目录流指针	非NULL，须为有效目录流指针

返回值

返回类型：int

返回值	文字含义	触发场景
>= 0	文件描述符	目录流有效
-1	获取失败	目录流无效

fdopendir

DIR *fdopendir(int)

头文件清单

#include "open_source/musl/include/dirent.h"

功能说明

通过已打开的文件描述符创建目录流
返回与该文件描述符关联的目录流指针
文件描述符的所有权转移给目录流，closedir时自动关闭

入参

名称	参数类型	详细说明	约束取值范围
fd	int	已打开的目录文件描述符	有效的目录文件描述符

返回值

返回类型：DIR *

返回值	文字含义	触发场景
非NULL指针	创建成功	文件描述符有效且指向目录
NULL	创建失败	文件描述符无效或不指向目录

opendir

DIR *opendir(const char *)

头文件清单

#include "open_source/musl/include/dirent.h"

功能说明

打开指定路径的目录，返回目录流指针
为后续readdir、closedir等操作建立目录流上下文
目录流指针用于遍历目录中的条目

入参

名称	参数类型	详细说明	约束取值范围
name	const char *	要打开的目录路径字符串	非NULL，有效的目录路径

返回值

返回类型：DIR *

返回值	文字含义	触发场景
非NULL指针	打开成功	目录路径有效且可访问
NULL	打开失败	路径无效、权限不足或系统资源不足

readdir

struct dirent *readdir(DIR *)

头文件清单

#include "open_source/musl/include/dirent.h"

功能说明

从目录流中读取下一个目录项
返回包含目录项信息的dirent结构体指针
每次调用返回一个目录项，反复调用可遍历整个目录

前置条件

调用时序约束：当前接口必须在opendir或fdopendir成功返回后调用
依赖关系：传入的DIR指针必须为opendir或fdopendir返回的有效目录流指针

入参

名称	参数类型	详细说明	约束取值范围
dir	DIR *	指向由opendir或fdopendir返回的目录流指针	非NULL，须为有效目录流指针

返回值

返回类型：struct dirent *

返回值	文字含义	触发场景
非NULL指针	读取成功	目录流中存在下一个目录项
NULL	到达目录末尾或出错	目录遍历结束或读取失败

readdir_r

int readdir_r(DIR *__restrict, struct dirent *__restrict, struct dirent **__restrict)

头文件清单

#include "open_source/musl/include/dirent.h"

功能说明

线程安全地从目录流中读取下一个目录项
将目录项信息写入调用方提供的dirent结构体
通过出参返回读取结果，避免使用静态内部缓冲区

前置条件

调用时序约束：当前接口必须在opendir或fdopendir成功返回后调用
依赖关系：传入的DIR指针必须为opendir或fdopendir返回的有效目录流指针

入参

名称	参数类型	详细说明	约束取值范围
dir	DIR *__restrict	指向由opendir或fdopendir返回的目录流指针	非NULL，须为有效目录流指针
entry	struct dirent *__restrict	调用方提供的dirent结构体缓冲区	非NULL，由调用方分配

出参

名称	数据类型	输出说明
result	struct dirent **__restrict	指向读取到的目录项指针，到达末尾时为NULL

返回值

返回类型：int

返回值	文字含义	触发场景
0	读取成功	目录流中存在下一个目录项或到达末尾
非零错误码	读取失败	目录流无效或读取出错

rewinddir

void rewinddir(DIR *)

头文件清单

#include "open_source/musl/include/dirent.h"

功能说明

将目录流的读取位置重置为目录开头
重置后再次调用readdir将从目录第一个条目开始读取
使目录遍历可以重新开始

前置条件

调用时序约束：当前接口必须在opendir或fdopendir成功返回后调用
依赖关系：传入的DIR指针必须为opendir或fdopendir返回的有效目录流指针

入参

名称	参数类型	详细说明	约束取值范围
dir	DIR *	指向由opendir或fdopendir返回的目录流指针	非NULL，须为有效目录流指针

scandir

int scandir(const char *, struct dirent ***, int (*)(const struct dirent *), int (*)(const struct dirent **, const struct dirent **))

头文件清单

#include "open_source/musl/include/dirent.h"

功能说明

入参

名称	参数类型	详细说明	约束取值范围
dir	const char *	要扫描的目录路径	非NULL，有效的目录路径
filter	int ()(const struct dirent )	过滤函数指针，返回非0表示保留该目录项	NULL表示不过滤，非NULL为有效的函数指针
compar	int ()(const struct dirent , const struct dirent *)	排序函数指针，用于对筛选后的目录项排序	NULL表示不排序，非NULL为有效的函数指针

出参

名称	数据类型	输出说明
namelist	struct dirent ***	指向排序后的目录项指针数组，需由调用者释放

返回值

返回类型：int

返回值	文字含义	触发场景
>= 0	扫描成功	返回筛选后的目录项数量
-1	扫描失败	目录路径无效、内存分配失败或参数为NULL

seekdir

void seekdir(DIR *, long)

头文件清单

#include "open_source/musl/include/dirent.h"

功能说明

设置目录流的读取位置到指定偏移
偏移值应为由telldir返回的位置值
设置后下次调用readdir将从该位置开始读取

前置条件

调用时序约束：当前接口必须在opendir或fdopendir成功返回后调用
依赖关系：传入的DIR指针必须为有效目录流指针；offset参数应使用telldir返回的值

入参

名称	参数类型	详细说明	约束取值范围
dir	DIR *	指向由opendir或fdopendir返回的目录流指针	非NULL，须为有效目录流指针
offset	long	目标位置偏移量	由telldir返回的合法偏移值

telldir

long telldir(DIR *)

头文件清单

#include "open_source/musl/include/dirent.h"

功能说明

获取目录流当前的读取位置
返回值可用于后续seekdir调用以恢复该位置
配合seekdir实现目录流的随机访问

前置条件

调用时序约束：当前接口必须在opendir或fdopendir成功返回后调用
依赖关系：传入的DIR指针必须为opendir或fdopendir返回的有效目录流指针

入参

名称	参数类型	详细说明	约束取值范围
dir	DIR *	指向由opendir或fdopendir返回的目录流指针	非NULL，须为有效目录流指针

返回值

返回类型：long

返回值	文字含义	触发场景
>= 0	当前位置偏移量	目录流有效且获取位置成功
-1	获取失败	目录流无效

Type definitions

DIR

typedef struct __dirstream DIR;

使用说明

不透明类型，实现细节不公开，仅通过对外接口操作。用作目录流的句柄，由opendir或fdopendir创建，传递给readdir、closedir等接口使用。

Structures

dirent

struct dirent {
    ino_t d_ino;
    off_t d_off;
    unsigned short d_reclen;
    unsigned char d_type;
    char d_name[256];
};

成员说明

成员名称	数据类型	描述
d_ino	ino_t	文件inode编号
d_off	off_t	目录项在目录流中的偏移量
d_reclen	unsigned short	目录项记录长度
d_type	unsigned char	文件类型，取值见DT_*宏（DT_UNKNOWN(0) / DT_FIFO(1) / DT_CHR(2) / DT_DIR(4) / DT_BLK(6) / DT_REG(8) / DT_LNK(10) / DT_SOCK(12) / DT_WHT(14)）
d_name	char[256]	文件名称字符串

Macros

DT_UNKNOWN

#define DT_UNKNOWN 0

DT_FIFO

#define DT_FIFO 1

DT_CHR

#define DT_CHR 2

DT_DIR

#define DT_DIR 4

DT_BLK

#define DT_BLK 6

DT_REG

#define DT_REG 8

DT_LNK

#define DT_LNK 10

DT_SOCK

#define DT_SOCK 12

DT_WHT

#define DT_WHT 14