CreateDirectory2A 함수(fileapi.h)

새 디렉터리를 만듭니다. 기본 파일 시스템에서 파일 및 디렉터리에 대한 보안을 지원하는 경우 함수는 지정된 보안 설명자를 새 디렉터리에 적용합니다.

템플릿 디렉터리를 지정하려면 CreateDirectoryEx 함수를 사용합니다.

이 작업을 트랜잭션 작업으로 수행하려면 CreateDirectoryTransacted 함수를 사용합니다.

문법

HANDLE CreateDirectory2A(
  LPCSTR                lpPathName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  DIRECTORY_FLAGS       DirectoryFlags,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

매개 변수

lpPathName

만들 디렉터리의 경로입니다.

기본적으로 이름은 MAX_PATH 문자로 제한됩니다. 이 제한을 32,767자로 확장하려면 경로 앞에 "\\?\"를 추가합니다. 자세한 내용은 이름 지정 파일, 경로 및 네임스페이스를 참조하세요.

팁 (조언)

"\\?\" 앞에 추가하지 않고 MAX_PATH 제한을 제거하도록 옵트인할 수 있습니다. 자세한 내용은 파일, 경로 및 네임스페이스의 "최대 경로 길이 제한" 섹션을 참조하세요.

dwDesiredAccess

호출자가 디렉터리에 필요한 액세스 유형을 나타내는 ACCESS_MASK 값입니다. 시스템 정의 dwDesiredAccess 플래그 집합은 다음과 같은 특정 액세스 권한 디렉터리 파일 개체를 결정합니다.

가치 의미
FILE_LIST_DIRECTORY 디렉터리의 파일을 나열할 수 있습니다.
FILE_TRAVERSE 디렉터리를 트래버스할 수 있습니다. 즉, 파일의 경로 이름에 속할 수 있습니다.
동기화 반환된 핸들은 I/O 작업의 완료와 동기화하기 위해 대기할 수 있습니다. 동기 I/O에 대한 핸들을 열지 않은 경우 이 값은 무시됩니다.

dwShareMode

호출자가 파일에서 0으로 사용하거나 다음 값의 조합으로 사용하려는 공유 액세스 유형입니다.

가치 의미
0
0x00000000		 삭제, 읽기 또는 쓰기 액세스를 요청하는 경우 다른 프로세스가 파일 또는 디바이스를 열 수 없도록 합니다.
FILE_SHARE_READ
0x00000001		 파일 또는 디바이스에서 후속 열기 작업을 통해 읽기 액세스를 요청할 수 있습니다. 그렇지 않으면 읽기 액세스를 요청하는 경우 다른 프로세스에서 파일 또는 디바이스를 열 수 없습니다. 이 플래그를 지정하지 않았지만 읽기 액세스를 위해 파일 또는 디바이스가 열려 있으면 함수가 실패합니다.
FILE_SHARE_WRITE
0x00000002		 파일 또는 디바이스에서 후속 열기 작업을 사용하여 쓰기 액세스를 요청할 수 있습니다. 그렇지 않은 경우 다른 프로세스는 쓰기 액세스를 요청하는 경우 파일 또는 디바이스를 열 수 없습니다. 이 플래그를 지정하지 않았지만 파일 또는 디바이스가 쓰기 액세스를 위해 열렸거나 쓰기 액세스 권한이 있는 파일 매핑이 있는 경우 함수가 실패합니다.
FILE_SHARE_DELETE
0x00000004		 파일 또는 디바이스에서 후속 열기 작업을 사용하여 삭제 액세스를 요청할 수 있습니다. 그렇지 않으면 삭제 액세스를 요청하는 경우 다른 프로세스에서 파일 또는 디바이스를 열 수 없습니다. 이 플래그를 지정하지 않았지만 삭제 액세스를 위해 파일 또는 디바이스가 열려 있으면 함수가 실패합니다.

메모: 액세스 삭제를 사용하면 삭제 및 이름 바꾸기 작업을 모두 수행할 수 있습니다.

DirectoryFlags

이 매개 변수는 DIRECTORY_FLAGS 조합을 포함할 수 있습니다.

가치 의미
DIRECTORY_FLAGS_DISALLOW_PATH_REDIRECTS
0x00000001		 재문 분석 지점 또는 기호 링크로 lpPathName 이 리디렉션되지 않도록 합니다.

lpSecurityAttributes

SECURITY_ATTRIBUTES 구조체에 대한 포인터입니다. 구조체의 lpSecurityDescriptor 멤버는 새 디렉터리에 대한 보안 설명자를 지정합니다. lpSecurityAttributes인 NULL경우 디렉터리가 기본 보안 설명자를 가져옵니다. 디렉터리에 대한 기본 보안 설명자의 ACL은 부모 디렉터리에서 상속됩니다.

대상 파일 시스템은 이 매개 변수가 적용되려면 파일 및 디렉터리에 대한 보안을 지원해야 합니다. GetVolumeInformation이 FS_PERSISTENT_ACLS 반환할 때 표시됩니다.

반환 값

함수가 성공하면 반환 값은 0이 아닌 값입니다.

함수가 실패하면 반환 값이 INVALID_HANDLE_VALUE. 확장 오류 정보를 얻으려면 GetLastError호출합니다.

가능한 오류는 다음과 같습니다.

반환 코드 설명
ERROR_ALREADY_EXISTS 지정된 디렉터리가 이미 있습니다.
ERROR_PATH_NOT_FOUND 하나 이상의 중간 디렉터리를 존재하지 않습니다. 이 함수는 경로에 최종 디렉터리만 만듭니다.
ERROR_PATH_REDIRECTED lpNewDirectory 는 재문 분석 지점 및/또는 기호 링크에 의해 리디렉션되었습니다.

비고

NTFS 파일 시스템과 같은 일부 파일 시스템은 개별 파일 및 디렉터리에 대한 압축 또는 암호화를 지원합니다. 이러한 파일 시스템에 대한 형식이 지정된 볼륨에서 새 디렉터리가 부모 디렉터리의 압축 및 암호화 특성을 상속합니다.

애플리케이션은 FILE_FLAG_BACKUP_SEMANTICS 플래그 집합으로 CreateFile을 호출하여 디렉터리에 대한 핸들을 가져올 수 있습니다. 코드 예제는 CreateFile을 참조하세요.

이 개체의 보안 설명자를 쿼리하는 상속 함수를 지원하기 위해 추론적으로 상속이 적용되는지 확인하고 보고할 수 있습니다. 자세한 내용은 상속 가능한 ACE의 자동 전파 를 참조하세요.

이 함수는 다음 기술에서 지원됩니다.

기술 지원됨
SMB(서버 메시지 블록) 3.0 프로토콜 예
SMB 3.0 TFO(투명한 장애 조치(failover) 예
SO(스케일 아웃 파일 공유)가 있는 SMB 3.0 예
CsvFS(클러스터 공유 볼륨 파일 시스템) 예
ReFS(복원 파일 시스템) 예

비고

헤더는 fileapi.hCREATEDirectory2 를 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입 대한규칙을 참조하세요.

예시

다음 예제에서는 CreateDirectory2 함수를 사용하여 새 디렉터리를 만듭니다. 새 디렉터리가 FILE_LIST_DIRECTORY 및 SYNCHRONIZE 액세스 권한으로 만들어집니다. 새 디렉터리도 FILE_SHARE_READ 공유 모드로 만들어 다른 프로세스에서 읽기 액세스를 위해 디렉터리를 열 수 있습니다.

// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF 
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO 
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 
// PARTICULAR PURPOSE. 
// 
// Copyright (C) Microsoft. All rights reserved 
#include <Windows.h>
#include <stdio.h>
#include <strsafe.h>

int main(int argc, wchar_t* argv[])
{
    WCHAR filePath[MAX_PATH] = { 0 };

    // Create a directory to put a file into, that can't be deleted
    // and redirected before this handle is closed.
    HANDLE hDirectory = CreateDirectory2(argv[1],
        FILE_LIST_DIRECTORY | SYNCHRONIZE,
        FILE_SHARE_READ,
        DIRECTORY_FLAGS_NONE,
        NULL,
        NULL);
    if (hDirectory == INVALID_HANDLE_VALUE)
    {
        // Handle the error.
        printf("CreateDirectory2 failed (%d)\n", GetLastError());
        return (1);
    }

    StringCchPrintf(filePath,
        ARRAYSIZE(filePath),
        L"%ws\\example.test",
        argv[1]);

    HANDLE hFile = CreateFile3(filePath,
        GENERIC_ALL,
        FILE_SHARE_READ,
        CREATE_ALWAYS,
        NULL);
    if (hFile == INVALID_HANDLE_VALUE)
    {
        // Handle the error.
        CloseHandle(hDirectory);
        printf("CreateFile3 failed (%d)\n", GetLastError());
        return (1);
    }

    CloseHandle(hFile);
    CloseHandle(hDirectory);
    return (0);
}

추가 예제는 파일 특성 검색 및 변경을 참조하세요.

요구 사항

요구 사항 가치
지원되는 최소 클라이언트 Windows 11 24H2 [데스크톱 앱 | UWP 앱]
지원되는 최소 서버 Windows Server 2025 [데스크톱 앱 | UWP 앱]
헤더 fileapi.h(Windows.h 포함)
라이브러리 커널32.lib
DLL Kernel32.dll

참고하십시오

CreateFile3

DeleteFile2

RemoveDirectory2

  • Last updated on