QUESTION
readdir로 받은 이름과 metadata는 한 시점의 일관된 snapshot인가?
getdents64는 directory file position부터 여러 linux_dirent64 record를 buffer에 채운다. glibc readdir는 이 buffer를 사용자에게 한 entry씩 보여준다. 호출마다 filesystem directory iterator가 진행하지만 다른 process의 생성·삭제·rename을 잠그지 않는다.
d_type은 편의 정보이며 DT_UNKNOWN일 수 있다. 보안 또는 정확성이 필요한 코드는 이름 문자열을 다시 절대 경로로 붙이기보다 directory fd와 fstatat/openat을 사용한다.
STRUCTURE
구조 그림
각 record의 d_reclen을 따라 다음 항목을 찾는다. d_name 길이만 더하면 alignment padding을 건너뛰지 못한다.
CALL PATH
호출 흐름
directory stream은 이름 목록의 immutable snapshot이 아니다. 각 entry 처리 시점에 필요한 객체를 dirfd-relative syscall로 다시 확정한다.
함수 이름을 외우기 위한 그림이 아니다. 반환값, 파일 디스크립터, 메모리 매핑, 대기 큐 가운데 무엇이 다음 단계로 전달되는지 확인한다.
SOURCE COORDINATES
Linux 6.18.37 LTS 소스 위치
glibc 함수에서 멈추지 않고 syscall 구현과 커널 객체가 만나는 파일까지 내려간다. 링크는 동일한 태그의 원본 파일을 가리킨다.
| 파일 | 함수·구조체 | 여기서 볼 것 |
|---|---|---|
| fs/readdir.c | iterate_dir(), getdents64(), filldir64() | directory callback과 userspace record 작성 |
| fs/namei.c | vfs_statx(), filename_lookup() | entry 이름을 실제 path와 metadata로 다시 확인 |
| include/linux/dirent.h | linux_dirent64 | record length, type, offset ABI |
COMPLETE PROGRAM
실행 예제 원본
아래 코드는 설명을 위해 중간 줄을 생략한 의사 코드가 아니다. 파일로 빌드해 실행할 수 있는 최소 예제다.
cc -std=c17 -Wall -Wextra -O2 list_dir.c -o list_dir01#define _DEFAULT_SOURCE
02#include <dirent.h>
03#include <errno.h>
04#include <fcntl.h>
05#include <stdio.h>
06#include <sys/stat.h>
07
08int main(int argc, char **argv)
09{
10 const char *path = argc > 1 ? argv[1] : ".";
11 DIR *dir = opendir(path);
12 if (dir == NULL)
13 return 1;
14 int dfd = dirfd(dir);
15
16 errno = 0;
17 struct dirent *entry;
18 while ((entry = readdir(dir)) != NULL) {
19 struct stat st;
20 if (fstatat(dfd, entry->d_name, &st, AT_SYMLINK_NOFOLLOW) < 0) {
21 if (errno == ENOENT)
22 continue;
23 perror("fstatat");
24 break;
25 }
26 printf("%-24s inode=%llu mode=%o\n", entry->d_name,
27 (unsigned long long)st.st_ino, st.st_mode & 07777);
28 }
29 if (entry == NULL && errno != 0)
30 perror("readdir");
31 return closedir(dir) != 0;
32}
RUN RESULT
실행 결과
x86_64 Linux에서 예제를 실행한 결과입니다.
실행 환경
2026-11-04 x86_64 Debian 환경(Linux 6.12.94, gcc 14.2.0, glibc 2.41, -std=c17)에서 빌드하고 실행했다. 이 글의 기준 환경(ARM64, Linux 6.18.37 LTS)과 다르므로 PID, inode, 주소 값은 실행할 때마다 달라질 수 있다.
수정 전 코드는 AT_SYMLINK_NOFOLLOW가 선언되지 않아 컴파일에 실패했다. 위 코드는 #include <fcntl.h>를 추가한 것이며, 이 수정본은 getdents64가 돌려준 순서대로 항목을 출력했다(일부 줄만 발췌).
$ cc -std=c17 -Wall -Wextra -O2 list_dir.c -o list_dir # before the fix
list_dir.c:19:46: error: ‘AT_SYMLINK_NOFOLLOW’ undeclared (first use in this function)
$ ./list_dir . # after adding #include <fcntl.h>
run.log inode=538698 mode=644
.. inode=430959 mode=755
list_dir.c inode=538399 mode=644
. inode=538398 mode=755

ARM64 실행 결과
ARM64 에뮬레이터(QEMU, Cortex-A53)에서도 실행했습니다.

실행 출력 원문
저장된 실행 로그를 화면에 표시한 이미지입니다.
. inode=560 mode=755
.. inode=559 mode=755
example-link inode=562 mode=777
example.txt inode=561 mode=644
검증 절차 종료 값: 0실행 환경
위 C 예제를 ARM64용으로 교차 컴파일한 뒤, 2026-11-04에 Linux 6.18.58-0-virt에서 실행했습니다. QEMU virt의 Cortex-A53 에뮬레이션(TCG, CPU 2개, 메모리 512 MiB)을 사용했으며, 실물 ARM 보드에서 측정한 결과는 아닙니다. GCC 15.2.0과 glibc 2.43으로 정적 링크했고, 게스트의 셸과 기본 명령은 Alpine 3.23.7을 사용했습니다. 이 글의 기준 버전인 Linux 6.18.37과는 패치 버전이 다릅니다.
게스트 안에서 root로 실행했고, 네트워크는 내부 루프백만 사용했습니다. 호스트 디스크는 연결하지 않았습니다. 여기서 확인한 것은 예제의 실행 결과이며, 실제 보드의 성능·타이밍이나 커널 내부 경로 전체를 검증한 것은 아닙니다.
위 예제 소스는 바꾸지 않았습니다. x86_64 호스트에서 ARM64용으로 교차 컴파일한 뒤 게스트 안에서 실행했으며, 격리된 실행 환경을 위해 정적 링크 옵션을 추가했습니다. 빌드에 사용한 UAPI 헤더는 7.0.0이며, 실행 중인 커널 버전과는 별개입니다.
aarch64-linux-gnu-gcc-15 -static -std=c17 -Wall -Wextra -O2 list_dir.c -o list_dir
mkdir entries
printf 'sample\n' > entries/example.txt
chmod 644 entries/example.txt
ln -s example.txt entries/example-link
/examples/list_dir entries
CODE NOTES
코드 조각별 설명
DIR *dir = opendirDIR은 fd뿐 아니라 getdents buffer와 현재 위치를 가진 libc 객체다. 같은 stream을 여러 thread가 동시에 순회하는 방식은 피한다.
int dfd = dirfdpathname join 없이 같은 directory object를 기준으로 fstatat을 호출한다. directory가 rename돼도 기준 객체는 유지된다.
errno = 0readdir의 NULL은 EOF와 오류를 모두 뜻하므로 loop 시작 전에 errno를 0으로 만들고 종료 뒤 구분한다.
AT_SYMLINK_NOFOLLOWentry가 symlink이면 target이 아니라 symlink inode metadata를 읽는다. d_type만 믿지 않는다.
errno == ENOENTreaddir와 fstatat 사이 다른 process가 entry를 삭제한 정상 경쟁을 허용하고 다음 항목으로 진행한다.
DETAILS
세부 동작
record 길이는 고정이 아니다
linux_dirent64의 d_reclen으로 다음 record를 찾는다. name 길이와 alignment 때문에 sizeof(struct dirent)만큼 더하는 raw parser는 잘못된다.
glibc readdir를 쓰면 ABI parsing을 직접 할 필요가 없지만 반환 pointer는 다음 readdir 호출에서 덮어쓸 수 있다.
directory 변경 중 결과는 중복·누락될 수 있다
filesystem은 iterator cookie와 hash/tree position을 사용한다. 순회 도중 rename이나 insertion이 있으면 이미 본 항목이 다시 보이거나 새 항목을 못 볼 수 있으며 portable snapshot 보장은 없다.
정확한 inventory가 필요하면 변경을 막는 상위 protocol, filesystem snapshot, 반복 검증 중 하나가 필요하다.
recursive walk는 fd 수와 symlink policy를 관리한다
각 하위 directory를 openat한 뒤 stack/queue에 넣으면 cwd를 바꾸지 않고 순회할 수 있다. 너무 많은 directory fd를 동시에 유지하면 RLIMIT_NOFILE에 닿으므로 depth-first close 정책을 정한다.
mount crossing, symlink follow, bind mount cycle 정책을 dev/inode pair와 openat2 resolve flag로 명시한다.
OBJECTS
객체와 수명
| 대상 | 언제 생기고 없어지는가 | 확인할 값 |
|---|---|---|
DIR stream | opendir에서 생성되고 closedir에서 내부 fd와 buffer가 해제된다 | fd, buffer, position |
dirent record | readdir 반환부터 다음 stream 호출 전까지만 유효할 수 있다 | d_name, d_ino, d_type |
directory fd | dirfd가 빌려 주는 번호이며 closedir가 소유한다 | 별도 close 금지, dup 필요 여부 |
FAILURE PATH
실패 조건과 오해하기 쉬운 부분
| 겉으로 보이는 현상 | 실제 원인 후보 | 확인 방법 |
|---|---|---|
| 항목이 가끔 사라짐 | 순회 중 concurrent rename/unlink | 변경 source와 snapshot 요구 확인 |
| 파일 종류가 UNKNOWN | filesystem이 d_type 미제공 | fstatat으로 확인 |
| readdir 오류를 EOF로 처리 | errno 구분 누락 | loop 전 errno=0 패턴 확인 |
LAB
직접 확인
- 큰 directory를 순회하는 동안 다른 process가 파일을 생성·rename해 결과 중복과 누락 가능성을 기록한다.
- strace에서 한 번의 getdents64가 여러 readdir 출력으로 분해되는지 확인한다.
- recursive walker를 openat/fstatat만으로 작성하고 symlink와 mount crossing policy를 option으로 분리한다.
./list_dir .strace -e trace=openat,getdents64,newfstatat,close ./list_dir .PRIMARY REFERENCES