C++ Directory Iterator | "디렉토리 순회" 가이드

directory_iterator란?

디렉토리 내용 순회 (C++17)

#include <filesystem>

namespace fs = std::filesystem;

for (const auto& entry : fs::directory_iterator(".")) {
    std::cout << entry.path() << std::endl;
}

재귀 순회

// 하위 디렉토리 포함
for (const auto& entry : fs::recursive_directory_iterator(".")) {
    std::cout << entry.path() << std::endl;
}

directory_iterator vs recursive_directory_iterator

구분	directory_iterator	recursive_directory_iterator
범위	해당 경로의 직계 항목만	하위 디렉터리까지 재귀 순회
기본 동작	하위 폴더 안으로 들어가지 않음	자동으로 하위 트리를 펼침
옵션	directory_options (동일 계열)	동일 + disable_recursion_pending 등
전형적 용도	한 단계 목록·즉시 자식만 스캔	전체 검색·트리 합산·백업 스캔

recursive_directory_iterator에는 표준에 최대 깊이 옵션이 없습니다. 깊이만 제한하려면 directory_iterator를 직접 재귀·큐로 돌리거나, 특정 디렉터리에서 disable_recursion_pending()으로 그 가지만 건너뛰는 방식을 씁니다.

// 이름이 "build"인 디렉터리는 들어가지 않음 (예시)
for (fs::recursive_directory_iterator it(root), end; it != end; ++it) {
    if (it->is_directory() && it->path().filename() == "build") {
        it.disable_recursion_pending();
    }
    // ...
}

실전 예시

예시 1: 파일 목록

void listFiles(const fs::path& dir) {
    for (const auto& entry : fs::directory_iterator(dir)) {
        if (entry.is_regular_file()) {
            std::cout << entry.path().filename() << std::endl;
        }
    }
}

예시 2: 특정 확장자 찾기

std::vector<fs::path> findFiles(const fs::path& dir, 
                                 const std::string& ext) {
    std::vector<fs::path> result;
    
    for (const auto& entry : fs::recursive_directory_iterator(dir)) {
        if (entry.is_regular_file() && 
            entry.path().extension() == ext) {
            result.push_back(entry.path());
        }
    }
    
    return result;
}

// 사용
auto cppFiles = findFiles(".", ".cpp");

예시 3: 디렉토리 크기

uintmax_t calculateDirSize(const fs::path& dir) {
    uintmax_t size = 0;
    
    for (const auto& entry : fs::recursive_directory_iterator(dir)) {
        if (entry.is_regular_file()) {
            size += entry.file_size();
        }
    }
    
    return size;
}

예시 4: 파일 필터링

void filterFiles(const fs::path& dir) {
    for (const auto& entry : fs::directory_iterator(dir)) {
        if (entry.is_regular_file()) {
            auto size = entry.file_size();
            
            if (size > 1024 * 1024) {  // 1MB 이상
                std::cout << entry.path() << ": " 
                          << size << " bytes" << std::endl;
            }
        }
    }
}

파일 필터링 패턴

표준에는 글로브/정규식 필터가 없습니다. 관용적으로는 다음을 조합합니다.

• 확장자: path::extension(), path::stem()과 비교 (위 예시 2·4와 같음).
• 타입: entry.is_regular_file(), is_directory()로 디렉터리·파일만 골라내기.
• 제외 디렉터리: 경로에 ".git", "node_modules" 등이 포함되는지 검사해 조기 continue.
• 정규식: 필요 시 path::string()에 std::regex 적용 (Windows에서는 경로 인코딩 유의).

C++20이면 std::ranges와 함께 쓰면 필터 체인을 짧게 쓸 수 있습니다.

순회 옵션

// 기본
fs::directory_iterator it(dir);

// 심볼릭 링크 따라가기
fs::directory_iterator it(dir, 
    fs::directory_options::follow_directory_symlink);

// 권한 에러 무시
fs::directory_iterator it(dir,
    fs::directory_options::skip_permission_denied);

심볼릭 링크 처리

• 디렉터리 심볼릭 링크: recursive_directory_iterator는 기본적으로 링크 대상 디렉터리로 들어갈 수 있습니다. 의도치 않게 큰 트리를 타거나 순환 구조에 빠질 수 있어, 정책을 정해야 합니다.
• follow_directory_symlink: 디렉터리 링크를 따라가도록 명시할 때 사용합니다. “순환 자동 탐지”를 보장하지는 않으므로, 민감한 경로에서는 절대 경로·방문 집합으로 직접 제한하는 것이 안전합니다.
• 링크 자체 vs 대상: entry.is_symlink(), fs::symlink_status(entry.path())는 링크 자체의 타입을, fs::status는 최종 타겟을 봅니다.
• 하드 링크: 동일 inode가 여러 경로에 나타나면 용량 합산 시 중복될 수 있습니다. 중복 제거가 필요하면 fs::equivalent나 플랫폼별 inode 조회를 고려합니다.

실전: 파일 검색 (심화)

이름 부분 문자열로 트리를 찾는 예입니다. 대규모 트리에서는 제외 디렉터리를 먼저 적용해 I/O를 줄입니다.

#include <filesystem>
#include <string>
#include <vector>

namespace fs = std::filesystem;

std::vector<fs::path> find_by_name(const fs::path& root, std::string_view key) {
    std::vector<fs::path> out;
    auto opts = fs::directory_options::skip_permission_denied;
    std::error_code ec;
    for (const auto& e : fs::recursive_directory_iterator(root, opts, ec)) {
        if (ec) break;
        if (!e.is_regular_file()) continue;
        auto fn = e.path().filename().string();
        if (fn.find(key) != std::string::npos)
            out.push_back(e.path());
    }
    return out;
}

실전: 디스크 사용량 계산 (심화)

트리 합계는 일반 파일 크기를 더합니다. 심볼릭 링크는 file_size 동작이 정책에 따라 달라질 수 있으니, 링크는 건너뛰거나 별도 규칙을 두세요.

std::uintmax_t tree_bytes(const fs::path& p, std::error_code& ec) {
    std::uintmax_t total = 0;
    auto opts = fs::directory_options::skip_permission_denied;
    for (const auto& e : fs::recursive_directory_iterator(p, opts, ec)) {
        if (ec) break;
        if (!e.is_regular_file()) continue;
        std::error_code fe;
        auto sz = fs::file_size(e.path(), fe);
        if (!fe) total += sz;
    }
    return total;
}

에러 처리 (std::error_code)

예외를 쓰지 않을 때는 이터레이터 생성·file_size 등에 error_code 오버로드를 넘깁니다.

std::error_code ec;
for (const auto& entry : fs::directory_iterator("maybe_missing", ec)) {
    if (ec) {
        std::cerr << ec.message() << '\n';
        break;
    }
    std::cout << entry.path() << '\n';
}

recursive_directory_iterator의 생성자에 ec를 넘기면 루트 열기 실패를 잡을 수 있고, skip_permission_denied와 함께 쓰면 권한 없는 항목 때문에 전체가 끊기기 어렵습니다. 순회 중 일부 항목만 실패할 수 있으므로, 중요한 경로에서는 fs::file_size·fs::status마다 ec를 확인하는 편이 안전합니다.

성능 고려사항

1. 불필요한 재귀 줄이기: 필요한 깊이만 directory_iterator로 직접 제어하면 거대한 하위 트리를 피할 수 있습니다.
2. path 복사: 루프에서 entry.path()를 여러 번 호출하지 말고 지역 fs::path에 담습니다.
3. 시스템 호출: directory_entry::file_size() 등이 캐시되는 경우가 많지만 보장은 아닙니다. 핫 루프에서는 불필요한 메타데이터 조회를 줄입니다.
4. 병렬화: 표준 이터레이터만으로는 병렬 순회가 없습니다. 서브트리 단위로 경로 목록을 나눈 뒤 스레드 풀에 넣는 방식이 일반적입니다.
5. 네트워크 드라이브: 지연이 크므로 배치·캐시 정책을 애플리케이션 요구에 맞게 조정합니다.

자주 발생하는 문제

문제 1: 예외 처리

// ❌ 권한 에러
for (const auto& entry : fs::recursive_directory_iterator(".")) {
    // 권한 없는 디렉토리에서 예외
}

// ✅ 옵션 사용
for (const auto& entry : fs::recursive_directory_iterator(".",
    fs::directory_options::skip_permission_denied)) {
    std::cout << entry.path() << std::endl;
}

문제 2: 심볼릭 링크와 순환

// 심볼릭 링크가 디렉터리를 가리키면 재귀 순회가 그쪽으로 들어갈 수 있음
// (표준이 자동으로 “순환 탐지”를 해주지는 않음)

// ✅ 권한 문제만 완화
for (const auto& entry : fs::recursive_directory_iterator(dir,
    fs::directory_options::skip_permission_denied)) {
    std::cout << entry.path() << std::endl;
}

// 순환·중복 방문을 막으려면 방문한 경로 집합·깊이 제한 등을 애플리케이션에서 둠

문제 3: 성능

// ❌ 매번 file_size 호출
for (const auto& entry : fs::directory_iterator(dir)) {
    auto size = fs::file_size(entry.path());  // 시스템 콜
}

// ✅ entry 캐시 사용
for (const auto& entry : fs::directory_iterator(dir)) {
    auto size = entry.file_size();  // 캐시됨
}

문제 4: 수정 중 순회

// ❌ 순회 중 수정
for (const auto& entry : fs::directory_iterator(dir)) {
    fs::remove(entry.path());  // 정의되지 않은 동작
}

// ✅ 경로 수집 후 삭제
std::vector<fs::path> toDelete;
for (const auto& entry : fs::directory_iterator(dir)) {
    toDelete.push_back(entry.path());
}
for (const auto& p : toDelete) {
    fs::remove(p);
}

활용 패턴

// 1. 파일 검색
auto files = findFiles(".", ".cpp");

// 2. 디렉토리 크기
auto size = calculateDirSize(".");

// 3. 파일 백업
backupFiles("src", "backup");

// 4. 정리
cleanupOldFiles("temp", 7);  // 7일 이상

FAQ

Q1: directory_iterator는?

A: C++17. 디렉토리 순회.

Q2: 재귀 순회?

A: recursive_directory_iterator.

Q3: 예외 처리?

A: try/catch 또는 std::error_code 오버로드로 예외 없이 처리. skip_permission_denied로 권한 오류 완화.

Q4: 성능?

A: entry 캐시 사용.

Q5: 순회 중 수정?

A: 정의되지 않은 동작. 경로 수집 후 수정.

Q6: directory_iterator 학습 리소스는?

A:

• “C++17 The Complete Guide”
• “C++ Primer”
• cppreference.com

---

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

• C++ File Status | “파일 상태” 가이드
• C++ File Operations | “파일 연산” 가이드
• C++ Filesystem | “파일시스템” C++17 라이브러리 가이드

관련 글

• C++ File Operations |
• C++ File Status |
• C++ Filesystem 빠른 참조 |
• C++ Filesystem 개념 정리 |
• C++ path |