directory_iterator와 recursive_directory_iterator는 언제 쓰나요?

한 단계만 훑을 때는 directory_iterator, 하위 트리 전체를 내려갈 때는 recursive_directory_iterator가 맞습니다. 깊이 제한·심볼릭 링크 순환이 필요하면 직접 스택을 쓰는 편이 안전할 때도 있습니다.

심볼릭 링크를 따라가면 무한 루프가 나요

기본 순회는 디렉터리 엔트리만 보고 링크 해석을 반복하지 않을 수 있습니다. 정책에 따라 follow_directory_symlink 등을 켜거나 끄고, 방문 집합으로 순환을 막으세요.

권한 오류가 나는 파일은 어떻게 처리하나요?

directory_options와 error_code 오버로드를 써서 한 항목 실패가 전체 순회를 중단하지 않게 하는 패턴이 일반적입니다.

대용량 트리 순회 성능을 올리려면?

불필요한 path 복사·문자열 변환을 줄이고, 필요한 메타데이터만 조회하세요. I/O가 병목이면 배치·병렬화는 디스크 특성을 고려해 신중히 설계합니다.

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

2026년 3월 12일 · 17분 읽기 · 수정 2026년 3월 30일 중급 튜토리얼

이 글의 핵심

directory_iterator와 recursive_directory_iterator 비교, 필터링·심볼릭 링크·error_code, 파일 검색·디스크 사용량·성능까지 C++17 filesystem 순회 실전 가이드입니다.

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와 함께 쓰면 필터 체인을 짧게 쓸 수 있습니다.

순회 옵션

C/C++ 예제 코드입니다.

// 기본
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를 확인하는 편이 안전합니다.

성능 고려사항

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

자주 발생하는 문제

문제 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);
}

활용 패턴

C/C++ 예제 코드입니다.

// 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 학습 리소스는?

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

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

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

심화 부록: 구현·운영 관점

이 부록은 앞선 본문에서 다룬 주제(「C++ Directory Iterator | ‘디렉토리 순회’ 가이드」)를 구현·런타임·운영 관점에서 다시 압축합니다. 도메인별 세부 구현은 글마다 다르지만, 입력 검증 → 핵심 연산 → 부작용(I/O·네트워크·동시성) → 관측의 흐름으로 장애를 나누면 원인 추적이 빨라집니다.

내부 동작과 핵심 메커니즘

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(런타임·게이트웨이·프로세스)
  participant D as 의존성(API·DB·큐·파일)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

불변 조건(Invariant): 버퍼 경계, 프로토콜 상태, 트랜잭션 격리, FD 상한 등 단계별로 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
결정성: 순수 층과 시간·네트워크·스케줄에 의존하는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
경계 비용: 직렬화, 인코딩, syscall 횟수, 락 경합, 할당·GC, 캐시 미스를 의심 목록에 둡니다.
백프레셔: 생산자가 소비자보다 빠를 때 버퍼·큐·스트림에서 속도를 줄이는 신호를 어디에 둘지 정의합니다.

프로덕션 운영 패턴

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율·지연 p95/p99, 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션·피처 플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·FD·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 프로덕션에 가깝게 맞출수록 재현율이 올라갑니다.

확장 예시: 엔드투엔드 미니 시나리오

앞선 본문 주제(「C++ Directory Iterator | ‘디렉토리 순회’ 가이드」)를 배포·운영 흐름에 맞춰 옮긴 체크리스트입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 로그·메트릭·트레이스에서 한 흐름으로 본다.
실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지 확인한다.
부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값을 점검한다.

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)
  authorize(validated, ctx)
  result = domainCore(validated)
  persistOrEmit(result, idempotentKey)
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스, 타임아웃, 외부 의존성, DNS	최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하	N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납	상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정 불일치	프로필·시크릿·기본값, 리전	스키마 검증된 설정 단일 소스와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

배포 전에는 git add → git commit → git push 후 npm run deploy 순서를 권장합니다.

이 글에서 다루는 키워드 (관련 검색어)

C++, directory_iterator, recursive_directory_iterator, filesystem, C++17, error_code 등으로 검색하시면 이 글이 도움이 됩니다.

이 글이 도움이 되셨나요?

여러분의 피드백은 더 나은 콘텐츠를 만드는 데 도움이 됩니다

문제가 있거나 개선 제안이 있으시면 연락처로 알려주세요.

Keyboard Shortcuts

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

이 글의 핵심

directory_iterator란?

재귀 순회

directory_iterator vs recursive_directory_iterator

실전 예시

예시 1: 파일 목록

예시 2: 특정 확장자 찾기

예시 3: 디렉토리 크기

예시 4: 파일 필터링

파일 필터링 패턴

순회 옵션

심볼릭 링크 처리

실전: 파일 검색 (심화)

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

에러 처리 (`std::error_code`)

성능 고려사항

자주 발생하는 문제

문제 1: 예외 처리

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

문제 3: 성능

문제 4: 수정 중 순회

활용 패턴

FAQ

Q1: directory_iterator는?

Q2: 재귀 순회?

Q3: 예외 처리?

Q4: 성능?

Q5: 순회 중 수정?

Q6: directory_iterator 학습 리소스는?

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

관련 글

심화 부록: 구현·운영 관점

내부 동작과 핵심 메커니즘

프로덕션 운영 패턴

확장 예시: 엔드투엔드 미니 시나리오

문제 해결(Troubleshooting)

이 글에서 다루는 키워드 (관련 검색어)

이 글이 도움이 되셨나요?

Keyboard Shortcuts

이 글의 핵심

directory_iterator란?

재귀 순회

directory_iterator vs recursive_directory_iterator

실전 예시

예시 1: 파일 목록

예시 2: 특정 확장자 찾기

예시 3: 디렉토리 크기

예시 4: 파일 필터링

파일 필터링 패턴

순회 옵션

심볼릭 링크 처리

실전: 파일 검색 (심화)

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

에러 처리 (std::error_code)

성능 고려사항

자주 발생하는 문제

문제 1: 예외 처리

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

문제 3: 성능

문제 4: 수정 중 순회

활용 패턴

FAQ

Q1: directory_iterator는?

Q2: 재귀 순회?

Q3: 예외 처리?

Q4: 성능?

Q5: 순회 중 수정?

Q6: directory_iterator 학습 리소스는?

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

관련 글

심화 부록: 구현·운영 관점

내부 동작과 핵심 메커니즘

프로덕션 운영 패턴

확장 예시: 엔드투엔드 미니 시나리오

문제 해결(Troubleshooting)

이 글에서 다루는 키워드 (관련 검색어)

이 글이 도움이 되셨나요?

에러 처리 (`std::error_code`)