File Descriptor / I/O · Linux userspace / kernel ABI

directory 순회와 getdents64

readdir가 directory entry snapshot을 제공하지 않는다는 점과 d_type, telldir cookie, 순회 중 변경을 안전하게 다루는 법을 봅니다.

Series
15 / 38
Build
cc -std=c17 -Wall -Wextra -O2 list_dir.c -o list_dir
Run
./list_dir .
Kernel
Linux 6.18.37 LTS

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을 사용한다.

구조 그림

그림 1. getdents64 한 번에 담기는 가변 길이 record
userspace buffer
inooffreclentypealpha\0paddinginooffreclentypelong-name\0padding
record 1
<──────── d_reclen=32 ────────>
record 2
<──────────── d_reclen=40 ────────────>

각 record의 d_reclen을 따라 다음 항목을 찾는다. d_name 길이만 더하면 alignment padding을 건너뛰지 못한다.

호출 흐름

그림 2. 사용자 코드의 요청과 처리 결과
opendir directory fd/stream
getdents64 record batch
readdir 한 entry 반환
fstatat dirfd 기준 metadata
closedir fd와 buffer 해제

directory stream은 이름 목록의 immutable snapshot이 아니다. 각 entry 처리 시점에 필요한 객체를 dirfd-relative syscall로 다시 확정한다.

그림 3. 커널 내부에서 지나가는 주요 지점
iterate_dir f_pos와 lock
file->iterate_shared filesystem callback
dir_emit name/inode/type
filldir64 user record
copy_to_user batch 반환

함수 이름을 외우기 위한 그림이 아니다. 반환값, 파일 디스크립터, 메모리 매핑, 대기 큐 가운데 무엇이 다음 단계로 전달되는지 확인한다.

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

실행 예제 원본

아래 코드는 설명을 위해 중간 줄을 생략한 의사 코드가 아니다. 파일로 빌드해 실행할 수 있는 최소 예제다.

빌드cc -std=c17 -Wall -Wextra -O2 list_dir.c -o list_dir
01#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}

실행 결과

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
list_dir 수정 전 컴파일 오류와 수정 후 실행, strace 결과를 담은 터미널 캡처
빌드·실행·strace·추가 실험 기록을 정리한 이미지입니다. 호스트명·경로·계정명은 일반 표기로 바꿨으며, 생략한 출력은 이미지에 표시했습니다.

ARM64 실행 결과

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

ARM64 실행 명령과 출력 화면: directory-walk-getdents
ARM64 QEMU 실행 기록
실행 출력 원문

저장된 실행 로그를 화면에 표시한 이미지입니다.

.                        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

실행 명령·출력 원문 · 환경·해시 기록 · 전체 부팅·실행 기록

코드 조각별 설명

실제 코드 11행DIR *dir = opendir

DIR은 fd뿐 아니라 getdents buffer와 현재 위치를 가진 libc 객체다. 같은 stream을 여러 thread가 동시에 순회하는 방식은 피한다.

실제 코드 14행int dfd = dirfd

pathname join 없이 같은 directory object를 기준으로 fstatat을 호출한다. directory가 rename돼도 기준 객체는 유지된다.

실제 코드 16행errno = 0

readdir의 NULL은 EOF와 오류를 모두 뜻하므로 loop 시작 전에 errno를 0으로 만들고 종료 뒤 구분한다.

실제 코드 20행AT_SYMLINK_NOFOLLOW

entry가 symlink이면 target이 아니라 symlink inode metadata를 읽는다. d_type만 믿지 않는다.

실제 코드 21행errno == ENOENT

readdir와 fstatat 사이 다른 process가 entry를 삭제한 정상 경쟁을 허용하고 다음 항목으로 진행한다.

세부 동작

01

record 길이는 고정이 아니다

linux_dirent64의 d_reclen으로 다음 record를 찾는다. name 길이와 alignment 때문에 sizeof(struct dirent)만큼 더하는 raw parser는 잘못된다.

glibc readdir를 쓰면 ABI parsing을 직접 할 필요가 없지만 반환 pointer는 다음 readdir 호출에서 덮어쓸 수 있다.

02

directory 변경 중 결과는 중복·누락될 수 있다

filesystem은 iterator cookie와 hash/tree position을 사용한다. 순회 도중 rename이나 insertion이 있으면 이미 본 항목이 다시 보이거나 새 항목을 못 볼 수 있으며 portable snapshot 보장은 없다.

정확한 inventory가 필요하면 변경을 막는 상위 protocol, filesystem snapshot, 반복 검증 중 하나가 필요하다.

03

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로 명시한다.

객체와 수명

대상언제 생기고 없어지는가확인할 값
DIR streamopendir에서 생성되고 closedir에서 내부 fd와 buffer가 해제된다fd, buffer, position
dirent recordreaddir 반환부터 다음 stream 호출 전까지만 유효할 수 있다d_name, d_ino, d_type
directory fddirfd가 빌려 주는 번호이며 closedir가 소유한다별도 close 금지, dup 필요 여부

실패 조건과 오해하기 쉬운 부분

겉으로 보이는 현상실제 원인 후보확인 방법
항목이 가끔 사라짐순회 중 concurrent rename/unlink변경 source와 snapshot 요구 확인
파일 종류가 UNKNOWNfilesystem이 d_type 미제공fstatat으로 확인
readdir 오류를 EOF로 처리errno 구분 누락loop 전 errno=0 패턴 확인

직접 확인

  1. 큰 directory를 순회하는 동안 다른 process가 파일을 생성·rename해 결과 중복과 누락 가능성을 기록한다.
  2. strace에서 한 번의 getdents64가 여러 readdir 출력으로 분해되는지 확인한다.
  3. recursive walker를 openat/fstatat만으로 작성하고 symlink와 mount crossing policy를 option으로 분리한다.
실행./list_dir .
추적strace -e trace=openat,getdents64,newfstatat,close ./list_dir .

원문