CreateFile2 함수(fileapi.h)
파일 또는 I/O 디바이스를 만들거나 엽니다. 가장 일반적으로 사용되는 I/O 디바이스는 파일, 파일 스트림, 디렉터리, 실제 디스크, 볼륨, 콘솔 버퍼, 테이프 드라이브, 통신 리소스, mailslot 및 파이프입니다. 이 함수는 파일 또는 디바이스 및 지정된 플래그 및 특성에 따라 다양한 형식의 I/O에 대한 파일 또는 디바이스에 액세스하는 데 사용할 수 있는 핸들을 반환합니다.
Windows 스토어 앱에서 호출되면 CreateFile2 간소화됩니다. ApplicationData.LocalFolder 또는 Package.InstalledLocation 디렉터리 내에서 파일 또는 디렉터리만 열 수 있습니다. 명명된 파이프 또는 mailslot을 열거나 암호화된 파일(FILE_ATTRIBUTE_ENCRYPTED)을 만들 수 없습니다.
통사론
HANDLE CreateFile2(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in] DWORD dwCreationDisposition,
[in, optional] LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
);
매개 변수
[in] lpFileName
만들거나 열 파일 또는 디바이스의 이름입니다.
특수 디바이스 이름에 대한 자세한 내용은 MS-DOS 디바이스 이름정의를 참조하세요.
파일 스트림을 만들려면 파일 이름, 콜론 및 스트림의 이름을 지정합니다. 자세한 내용은 파일 스트림참조하세요.
[in] dwDesiredAccess
파일 또는 디바이스에 대한 요청된 액세스이며 읽기, 쓰기, 둘 다 또는 0으로 요약할 수 있습니다.
가장 일반적으로 사용되는 값은 GENERIC_READ, GENERIC_WRITE또는 둘 다(GENERIC_READ | GENERIC_WRITE)입니다. 자세한 내용은 일반 액세스 권한, 파일 보안 및 액세스 권한, 파일 액세스 권한 상수및 ACCESS_MASK참조하세요.
이 매개 변수가 0인 경우 애플리케이션은 GENERIC_READ 액세스가 거부된 경우에도 해당 파일 또는 디바이스에 액세스하지 않고 파일, 디렉터리 또는 디바이스 특성과 같은 특정 메타데이터를 쿼리할 수 있습니다.
열려 있는 핸들이 이미 있는 열린 요청에서 dwShareMode 매개 변수로 지정된 공유 모드와 충돌하는 액세스 모드를 요청할 수 없습니다.
자세한 내용은 이 항목의 설명 섹션을 참조하고 파일 만들기 및 열기
[in] dwShareMode
파일 또는 디바이스의 요청된 공유 모드로, 읽기, 쓰기, 모두 삭제, 이러한 모든 항목 또는 없음(다음 표 참조)입니다. 특성 또는 확장 특성에 대한 액세스 요청은 이 플래그의 영향을 받지 않습니다.
이 매개 변수가 0이고 CreateFile2
열린 핸들이 있는 기존 요청에 지정된 액세스 모드와 충돌하는 공유 모드를 요청할 수 없습니다. CreateFile2 실패하고 GetLastError 함수가 ERROR_SHARING_VIOLATION반환합니다.
다른 프로세스에 파일 또는 디바이스가 열려 있는 동안 프로세스에서 파일 또는 디바이스를 공유할 수 있도록 하려면 다음 값 중 하나 이상의 호환 가능한 조합을 사용합니다. 이 매개 변수와
[in] dwCreationDisposition
존재하거나 존재하지 않는 파일 또는 디바이스에서 수행할 작업입니다.
파일 이외의 디바이스의 경우 이 매개 변수는 일반적으로 OPEN_EXISTING.
자세한 내용은 설명 섹션을 참조하세요.
이 매개 변수는 결합할 수 없는 다음 값 중 하나여야 합니다.
[in, optional] pCreateExParams
선택적 CREATEFILE2_EXTENDED_PARAMETERS 구조체에 대한 포인터입니다.
반환 값
함수가 성공하면 반환 값은 지정된 파일, 디바이스, 명명된 파이프 또는 메일 슬롯에 대한 열린 핸들입니다.
함수가 실패하면 반환 값이 INVALID_HANDLE_VALUE. 확장 오류 정보를 얻으려면 GetLastError호출합니다.
발언
CreateFile2 함수를 사용하는 애플리케이션을 컴파일하려면 _WIN32_WINNT 매크로를 0x0602 이상으로 정의합니다. 자세한 내용은 Windows 헤더사용하는
CreateFile2 파일 상호 작용 및 Windows 개발자가 사용할 수 있는 대부분의 다른 유형의 I/O 디바이스 및 메커니즘을 지원합니다. 이 섹션에서는 다양한 컨텍스트 및 다른 I/O 형식으로 CreateFile2 사용할 때 개발자가 경험할 수 있는 다양한 문제를 다룹니다. 텍스트는 파일 시스템의 실제 파일에 저장된 데이터를 구체적으로 참조할 때만
CreateFile2반환된 개체 핸들을 사용하여 애플리케이션이 완료되면 CloseHandle 함수를 사용하여 핸들을 닫습니다. 이렇게 하면 시스템 리소스를 확보할 수 있을 뿐만 아니라 파일 또는 디바이스 공유 및 디스크에 데이터 커밋과 같은 항목에 더 큰 영향을 줄 수 있습니다. 세부 정보는 이 항목 내에서 적절하게 설명됩니다.
NTFS 파일 시스템과 같은 일부 파일 시스템은 개별 파일 및 디렉터리에 대한 압축 또는 암호화를 지원합니다. 이 지원을 통해 탑재된 파일 시스템이 있는 볼륨에서 새 파일은 해당 디렉터리의 압축 및 암호화 특성을 상속합니다.
CreateFile2 사용하여 파일 또는 디렉터리에 대한 압축, 압축 해제 또는 암호 해독을 제어할 수 없습니다. 자세한 내용은 파일만들기 및 열기, 파일 압축 및 압축 해제
bInheritHandle 멤버 변수가 0이 아닌 값인 FALSE않으면 핸들을 상속할 수 있습니다. 따라서 핸들을 상속할 수 없도록 하려면 이 구조체 멤버를 올바르게 초기화하여 FALSE 것이 중요합니다. - 파일 또는 디렉터리에 대한 기본 보안 설명자의 ACL(액세스 제어 목록)은 부모 디렉터리에서 상속됩니다.
- 대상 파일 시스템은 lpSecurityDescriptor 멤버에 대한 파일 및 디렉터리에 대한 보안을 지원해야 하며, 이는 GetVolumeInformation사용하여 확인할 수 있습니다.
| 기술 | 지원 |
|---|---|
| SMB(서버 메시지 블록) 3.0 프로토콜 | 예 |
| SMB 3.0 TFO(투명한 장애 조치(failover) | 아니요 |
| SO(스케일 아웃 파일 공유)가 있는 SMB 3.0 | 아니요 |
| CsvFS(클러스터 공유 볼륨 파일 시스템) | 예 |
| ReFS(복원 파일 시스템) | 예 |
바로 가기 링크 동작
이 함수를 호출하면 파일이 만들어지면 동작이 변경되지 않습니다. 또한 pCreateExParams 매개 변수에 전달된 CREATEFILE2_EXTENDED_PARAMETERS 구조체의 dwFileFlags 멤버에 대한 FILE_FLAG_OPEN_REPARSE_POINT 플래그에 대한 다음 정보를 고려합니다.-
FILE_FLAG_OPEN_REPARSE_POINT 지정된 경우:
- 기존 파일이 열리고 기호 링크인 경우 반환되는 핸들은 기호 링크에 대한 핸들입니다.
- TRUNCATE_EXISTING 또는 FILE_FLAG_DELETE_ON_CLOSE 지정된 경우 영향을 받는 파일은 기호 링크입니다.
-
FILE_FLAG_OPEN_REPARSE_POINT 지정되지 않은 경우:
- 기존 파일이 열리고 기호 링크인 경우 반환되는 핸들은 대상에 대한 핸들입니다.
- CREATE_ALWAYS, TRUNCATE_EXISTING또는 FILE_FLAG_DELETE_ON_CLOSE 지정하면 영향을 받는 파일이 대상입니다.
파일
파일 이름을 바꾸거나 삭제한 후 잠시 후에 복원하면 시스템에서 캐시에서 복원할 파일 정보를 검색합니다. 캐시된 정보에는 짧은/긴 이름 쌍 및 생성 시간이 포함됩니다.DeleteFile대한 이전 호출의 결과로 삭제 보류 중인 파일에서 CreateFile2 호출하면 함수가 실패합니다. 운영 체제는 파일에 대한 모든 핸들을 닫을 때까지 파일 삭제를 지연합니다. GetLastErrorERROR_ACCESS_DENIED반환합니다.
dwDesiredAccess 매개 변수는 0일 수 있으므로 애플리케이션이 적절한 보안 설정으로 실행 중인 경우 파일에 액세스하지 않고 파일 특성을 쿼리할 수 있습니다. 읽기 및/또는 쓰기 액세스를 위해 파일을 열지 않고 파일이 있는지 테스트하거나 파일 또는 디렉터리에 대한 다른 통계를 가져오는 데 유용합니다. 파일 정보 가져오기 및 설정 및 GetFileInformationByHandle
애플리케이션이 네트워크를 통해 파일을 만드는 경우 GENERIC_WRITE 단독으로 사용하는 것보다 dwDesiredAccessGENERIC_READ | GENERIC_WRITE 사용하는 것이 좋습니다. 리다이렉터에서 캐시 관리자를 사용하고 더 많은 데이터로 더 적은 SMB를 보낼 수 있으므로 결과 코드는 더 빠릅니다.
또한 이 조합은 네트워크에서 파일에 쓰는 경우 때때로 ERROR_ACCESS_DENIED반환할 수 있는 문제를 방지합니다.
자세한 내용은 파일 만들기 및 열기
파일 스트림
NTFS 파일 시스템에서 CreateFile2 사용하여 파일 내에 별도의 스트림을 만들 수 있습니다. 자세한 내용은 파일 스트림참조하세요.디렉터리
애플리케이션은 CreateFile2사용하여 디렉터리를 만들 수 없으므로 이 사용 사례의 dwCreationDispositionOPEN_EXISTING 값만 유효합니다. 디렉터리를 만들려면 애플리케이션에서CreateFile2사용하여 디렉터리를 열려면 pCreateExParams 매개 변수에 전달된 CREATEFILE2_EXTENDED_PARAMETERS 구조체의 dwFileFlags 멤버의 일부로 FILE_FLAG_BACKUP_SEMANTICS 플래그를 지정합니다. SE_BACKUP_NAME 및 SE_RESTORE_NAME 권한 없이 이 플래그를 사용하는 경우에도 적절한 보안 검사가 적용됩니다.
CreateFile2 사용하여 FAT 또는 FAT32 파일 시스템 볼륨을 조각 모음하는 동안 디렉터리를 여는 경우 MAXIMUM_ALLOWED 액세스 권한을 지정하지 마세요. 이 작업이 수행되면 디렉터리에 대한 액세스가 거부됩니다. 대신 GENERIC_READ 액세스를 지정합니다.
자세한 내용은 디렉터리 관리
실제 디스크 및 볼륨
디스크 또는 볼륨에 대한 직접 액세스가 제한됩니다.CreateFile2 함수를 사용하여 실제 디스크 드라이브 또는 볼륨을 열 수 있습니다. 이 드라이브는 DeviceIoControl 함수와 함께 사용할 수 있는 DASD(직접 액세스 스토리지 디바이스) 핸들을 반환합니다. 이렇게 하면 디스크 또는 볼륨에 직접 액세스할 수 있습니다(예: 파티션 테이블과 같은 디스크 메타데이터). 그러나 이 유형의 액세스는 디스크 드라이브 또는 볼륨을 잠재적인 데이터 손실에 노출합니다. 이 메커니즘을 사용하는 디스크에 대한 잘못된 쓰기로 인해 운영 체제에서 해당 내용에 액세스할 수 없게 될 수 있기 때문입니다. 데이터 무결성을 보장하려면 DeviceIoControl 및 파일 시스템 핸들이 아닌 직접 액세스 핸들을 사용하여 다른 API가 다르게 동작하는 방식을 숙지해야 합니다.
이러한 호출이 성공하려면 다음 요구 사항을 충족해야 합니다.
- 호출자에게는 관리 권한이 있어야 합니다. 자세한 내용은 특수 권한
실행을 참조하세요. - dwCreationDisposition 매개 변수에는 OPEN_EXISTING 플래그가 있어야 합니다.
- 볼륨 또는 플로피 디스크를 열 때 dwShareMode 매개 변수에는 FILE_SHARE_WRITE 플래그가 있어야 합니다.
| 문자열 | 의미 |
|---|---|
| "\\.\PhysicalDrive0" | 첫 번째 실제 드라이브를 엽니다. |
| "\\.\PhysicalDrive2" | 세 번째 실제 드라이브를 엽니다. |
볼륨에 대한 실제 드라이브 식별자를 가져오려면 볼륨에 대한 핸들을 열고 IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS사용하여 DeviceIoControl 함수를 호출합니다. 이 컨트롤 코드는 각 볼륨의 하나 이상의 익스텐트의 디스크 번호와 오프셋을 반환합니다. 볼륨은 여러 실제 디스크에 걸쳐 있습니다.
실제 드라이브를 여는 예제는 deviceIoControl호출하는
볼륨 또는 이동식 미디어 드라이브(예: 플로피 디스크 드라이브 또는 플래시 메모리 썸 드라이브)를 열 때 lpFileName 문자열은 "\\.\X:"형식이어야 합니다. 드라이브의 루트 디렉터리를 나타내는 후행 백슬래시(\)를 사용하지 마세요. 다음 표에서는 드라이브 문자열의 몇 가지 예를 보여 줍니다.
| 문자열 | 의미 |
|---|---|
| "\\.\A:" | 플로피 디스크 드라이브 A를 엽니다. |
| "\\.\C:" | C: 볼륨을 엽니다. |
| "\\.\C:\" | C: 볼륨의 파일 시스템을 엽니다. |
볼륨 이름을 참조하여 볼륨을 열 수도 있습니다. 자세한 내용은 볼륨이름 지정
볼륨에는 하나 이상의 탑재된 파일 시스템이 포함되어 있습니다. 볼륨 핸들은 CreateFile2캐시되지 않은 옵션이 지정되지 않은 경우에도 특정 파일 시스템의 재량에 따라 캐시되지 않은 것으로 열 수 있습니다. 모든 Microsoft 파일 시스템에서 볼륨 핸들을 캐시되지 않은 것으로 여는 것으로 가정해야 합니다. 파일에 대한 캐시되지 않은 I/O에 대한 제한 사항도 볼륨에 적용됩니다.
데이터가 캐시되지 않은 경우에도 파일 시스템에 버퍼 맞춤이 필요하거나 필요하지 않을 수 있습니다. 그러나 볼륨을 열 때 캐시되지 않은 옵션을 지정하면 볼륨의 파일 시스템에 관계없이 버퍼 맞춤이 적용됩니다. 볼륨 핸들을 캐시되지 않은 것으로 열고 캐시되지 않은 I/O 제한을 따르는 모든 파일 시스템에서 권장됩니다.
변경자 디바이스
DeviceIoControl에 대한 IOCTL_CHANGER_* 제어 코드는 변경자 디바이스에 대한 핸들을 수락할 있습니다. 변경자 디바이스를 열려면 "\\.\Changerx" 형식의 파일 이름을 사용합니다. 여기서 x 0부터 시작하여 열 디바이스를 나타내는 숫자입니다. C 또는 C++로 작성된 애플리케이션에서 체인저 디바이스 0을 열려면 파일 이름 "\\\\.\\\Changer0"을 사용합니다.테이프 드라이브
"\\.\TAPEx" 형식의 파일 이름을 사용하여 테이프 드라이브를 열 수 있습니다. 여기서 x 테이프 드라이브 0부터 시작하여 열 드라이브를 나타내는 숫자입니다. C 또는 C++로 작성된 애플리케이션에서 테이프 드라이브 0을 열려면 파일 이름 "\\\\.\\TAPE0"을 사용합니다.자세한 내용은 Backup참조하세요.
Communications 리소스
CreateFile2 함수는 직렬 포트 COM1과 같은 통신 리소스에 대한 핸들을 만들 수 있습니다. 통신 리소스의 경우9보다 큰 COM 포트 번호를 지정하려면 "\.\COM10" 구문을 사용합니다. 이 구문은 COM 포트 번호를 지정할 수 있는 모든 포트 번호 및 하드웨어에 대해 작동합니다.
통신에 대한 자세한 내용은 Communications참조하세요.
콘솔
CreateFile2 함수는 콘솔 입력에 대한 핸들(CONIN$)을 만들 수 있습니다. 프로세스에 상속 또는 중복의 결과로 열린 핸들이 있는 경우 활성 화면 버퍼(CONOUT$)에 대한 핸들을 만들 수도 있습니다. 호출 프로세스는 상속된 콘솔 또는 AllocConsole 함수에 의해 할당된 콘솔에 연결되어야 합니다. 콘솔 핸들의 경우 다음과 같이 CreateFile2 매개 변수를 설정합니다.| 매개 변수 | 값 |
|---|---|
| lpFileName |
CONIN$ 값을 사용하여 콘솔 입력을 지정합니다.
CONOUT$ 값을 사용하여 콘솔 출력을 지정합니다. CONIN$은 SetStdHandle 함수가 표준 입력 핸들을 리디렉션하더라도 콘솔 입력 버퍼에 대한 핸들을 가져옵니다. 표준 입력 핸들을 가져오려면 GetStdHandle 함수를 사용합니다. CONOUT$는 SetStdHandle 표준 출력 핸들을 리디렉션하는 경우에도 활성 화면 버퍼에 대한 핸들을 가져옵니다. 표준 출력 핸들을 가져오려면 GetStdHandle사용합니다. |
| dwDesiredAccess |
GENERIC_READ | GENERIC_WRITE 선호되지만 둘 중 하나라도 액세스를 제한할 수 있습니다.
|
| dwShareMode |
CONIN$을 열 때 FILE_SHARE_READ지정합니다. CONOUT$를 열 때 FILE_SHARE_WRITE지정합니다.
호출 프로세스가 콘솔을 상속하거나 자식 프로세스가 콘솔에 액세스할 수 있어야 하는 경우 이 매개 변수는 |
| dwCreationDisposition | CreateFile2 사용하여 콘솔을 열 때 OPEN_EXISTING 지정해야 합니다. |
다음과 같이 pCreateExParams 매개 변수에 전달된 CREATEFILE2_EXTENDED_PARAMETERS 구조체의 멤버를 설정합니다.
| 회원 | 값 |
|---|---|
| lpSecurityAttributes |
콘솔을 상속하려는 경우 |
|
dwFileAttributes
dwFileFlags dwSecurityQosFlags hTemplateFile |
무시. |
다음 표에서는 dwDesiredAccess 및 lpFileName다양한 설정을 보여 줍니다.
| lpFileName | dwDesiredAccess | 결과 |
|---|---|---|
| "CON" | GENERIC_READ | 입력할 콘솔을 엽니다. |
| "CON" | GENERIC_WRITE | 출력을 위한 콘솔을 엽니다. |
| "CON" | GENERIC_READ | GENERIC_WRITE |
CreateFile2 실패합니다. GetLastErrorERROR_FILE_NOT_FOUND반환합니다. |
메일 슬롯
CreateFile2 mailslot의 클라이언트 끝을 열면 mailslot 클라이언트가 mailslot 서버에서 CreateMailSlot 함수를 사용하여 로컬 mailslot을 열려고 하면 INVALID_HANDLE_VALUE 반환합니다.자세한 내용은 Mailslots참조하세요.
파이프
CreateFile2 명명된 파이프의 클라이언트 끝을 열면 함수는 수신 대기 상태에 있는 명명된 파이프의 인스턴스를 사용합니다. 여는 프로세스는 핸들을 필요한 횟수만큼 복제할 수 있지만, 핸들을 연 후에는 다른 클라이언트에서 명명된 파이프 인스턴스를 열 수 없습니다. 파이프를 열 때 지정된 액세스는 CreateNamedPipe 함수의 dwOpenMode 매개 변수에 지정된 액세스와 호환되어야 합니다.이 작업 전에 서버에서 CreateNamedPipe 함수가 성공적으로 호출되지 않은 경우 파이프가 존재하지 않으며 CreateFile2ERROR_FILE_NOT_FOUND실패합니다.
활성 파이프 인스턴스가 하나 이상 있지만 서버에 사용 가능한 수신기 파이프가 없으면 모든 파이프 인스턴스가 현재 연결되어 CreateFile2ERROR_PIPE_BUSY실패합니다.
자세한 내용은 파이프
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 8 [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2012 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | fileapi.h(Windows.h 포함) |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |
참고 항목
디렉터리 관리 정보
볼륨 관리 대한
백업
closeHandle
CreateDirectory
CreateDirectoryEx
CreateFile
createFileTransacted
CreateMailSlot
CreateNamedPipe
DeleteFile
DeviceIoControl
파일 암호화
파일 보안 및 액세스 권한
함수
GetLastError
파일 정보 가져오기 및 설정
개요 항목
파이프
ReadFile
ReadFileEx
특수 권한 실행
setFileAttributes
WriteFile
WriteFileEx