CreateFile2 함수(fileapi.h)
파일 또는 I/O 디바이스를 만들거나 엽니다. 가장 일반적으로 사용되는 I/O 디바이스는 파일, 파일 스트림, 디렉터리, 물리적 디스크, 볼륨, 콘솔 버퍼, 테이프 드라이브, 통신 리소스, 메일 슬롯 및 파이프입니다. 함수는 파일 또는 디바이스 및 지정된 플래그 및 특성에 따라 다양한 형식의 I/O에 대한 파일 또는 디바이스에 액세스하는 데 사용할 수 있는 핸들을 반환합니다.
Windows 스토어 앱에서 호출되면 CreateFile2 가 간소화됩니다. ApplicationData.LocalFolder 또는 Package.InstalledLocation 디렉터리 내에서 파일 또는 디렉터리만 열 수 있습니다. 명명된 파이프 또는 메일 슬롯을 열거나 암호화된 파일(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 반환합니다.
다른 프로세스에서 파일 또는 디바이스가 열려 있는 동안 프로세스에서 파일 또는 디바이스를 공유할 수 있도록 하려면 다음 값 중 하나 이상의 호환 가능한 조합을 사용합니다. 이 매개 변수와 dwDesiredAccess 매개 변수의 유효한 조합에 대한 자세한 내용은 파일 만들기 및 열기를 참조하세요.
[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 를 사용할 때 발생할 수 있는 다양한 문제를 다룹니다. 텍스트는 파일 시스템의 실제 파일에 저장된 데이터를 구체적으로 참조할 때만 단어 파일을 사용하려고 합니다. 그러나 파일의 일부 사용은 파일 과 유사한 메커니즘을 지원하는 I/O 개체를 더 일반적으로 참조할 수 있습니다. 이 용어 파일 의 자유로운 사용은 이전에 언급한 기록상의 이유로 인해 상수 이름 및 매개 변수 이름에 특히 널리 퍼집니다.
CreateFile2에서 반환된 개체 핸들을 사용하여 애플리케이션이 완료되면 CloseHandle 함수를 사용하여 핸들을 닫습니다. 이렇게 하면 시스템 리소스를 확보할 수 있을 뿐만 아니라 파일 또는 디바이스 공유 및 디스크에 데이터 커밋과 같은 항목에 더 큰 영향을 미칠 수 있습니다. 세부 정보는 이 항목 내에서 적절하게 설명됩니다.
NTFS 파일 시스템과 같은 일부 파일 시스템은 개별 파일 및 디렉터리에 대한 압축 또는 암호화를 지원합니다. 이 지원을 통해 탑재된 파일 시스템이 있는 볼륨에서 새 파일은 해당 디렉터리의 압축 및 암호화 특성을 상속합니다.
CreateFile2를 사용하여 파일 또는 디렉터리에 대한 압축, 압축 해제 또는 암호 해독을 제어할 수 없습니다. 자세한 내용은 파일 만들기 및 열기, 파일 압축 및 압축 해제 및파일 암호화를 참조하세요.
pCreateExParams 매개 변수에 전달된 CREATEFILE2_EXTENDED_PARAMETERS 구조체의 lpSecurityAttributes 멤버가 NULL인 경우 CreateFile2에서 반환된 핸들은 애플리케이션이 만들 수 있는 자식 프로세스에서 상속할 수 없습니다. 이 멤버에 대한 다음 정보도 적용됩니다.
- bInheritHandle 멤버 변수가 0이 아닌 값인 FALSE가 아니면 핸들을 상속할 수 있습니다. 따라서 핸들을 상속할 수 없도록 하려면 이 구조체 멤버를 FALSE 로 올바르게 초기화해야 합니다.
- 파일 또는 디렉터리에 대한 기본 보안 설명자의 ACL(액세스 제어 목록)은 부모 디렉터리에서 상속됩니다.
- 대상 파일 시스템은 lpSecurityDescriptor 멤버가 영향을 주도록 파일 및 디렉터리에 대한 보안을 지원해야 하며, GetVolumeInformation을 사용하여 확인할 수 있습니다.
| 기술 | 지원됨 |
|---|---|
| SMB(서버 메시지 블록) 3.0 프로토콜 | Yes |
| SMB 3.0 TFO(투명 장애 조치(failover)) | No |
| SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0 | No |
| CsvFS(클러스터 공유 볼륨 파일 시스템) | Yes |
| ReFS(Resilient File System) | Yes |
기호 링크 동작
이 함수를 호출하면 파일이 만들어지면 동작이 변경되지 않습니다. 또한 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를 호출하면 함수가 실패합니다. 운영 체제는 파일에 대한 모든 핸들이 닫을 때까지 파일 삭제를 지연합니다. GetLastError는ERROR_ACCESS_DENIED 반환합니다.
dwDesiredAccess 매개 변수는 0일 수 있으므로 애플리케이션이 적절한 보안 설정으로 실행 중인 경우 파일에 액세스하지 않고 파일 특성을 쿼리할 수 있습니다. 읽기 및/또는 쓰기 액세스를 위해 파일을 열지 않고 파일이 있는지 테스트하거나 파일 또는 디렉터리에 대한 다른 통계를 가져오는 데 유용합니다. 파일 정보 가져오기 및 설정 및 GetFileInformationByHandle을 참조하세요.
애플리케이션이 네트워크를 통해 파일을 만드는 경우 GENERIC_WRITE 단독으로 사용하는 것보다 dwDesiredAccess에 사용하는 GENERIC_READ | GENERIC_WRITE 것이 좋습니다. 리렉터에서 캐시 관리자를 사용하고 더 많은 데이터로 더 적은 SMB를 보낼 수 있으므로 결과 코드는 더 빠릅니다.
또한 이 조합은 네트워크를 통해 파일에 쓰는 경우 때때로 ERROR_ACCESS_DENIED 반환할 수 있는 문제를 방지합니다.
자세한 내용은 파일 만들기 및 열기를 참조하세요.
파일 스트림
NTFS 파일 시스템에서 CreateFile2 를 사용하여 파일 내에 별도의 스트림을 만들 수 있습니다. 자세한 내용은 파일 스트림을 참조하세요.디렉터리
애플리케이션은 CreateFile2를 사용하여 디렉터리를 만들 수 없으므로 이 사용 사례의 경우 dwCreationDisposition에 대해 OPEN_EXISTING 값만 유효합니다. 디렉터리를 만들려면 애플리케이션에서 CreateDirectory 또는 CreateDirectoryEx를 호출해야 합니다.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 플래그가 있어야 합니다.
| String | 의미 |
|---|---|
| "\\.\PhysicalDrive0" | 첫 번째 실제 드라이브를 엽니다. |
| "\\.\PhysicalDrive2" | 세 번째 실제 드라이브를 엽니다. |
볼륨에 대한 물리적 드라이브 식별자를 가져오려면 볼륨에 대한 핸들을 열고 IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS사용하여 DeviceIoControl 함수를 호출합니다. 이 컨트롤 코드는 각 볼륨의 하나 이상의 익스텐트의 디스크 번호와 오프셋을 반환합니다. 볼륨은 여러 실제 디스크에 걸쳐 있습니다.
실제 드라이브를 여는 예제는 DeviceIoControl 호출을 참조하세요.
볼륨 또는 이동식 미디어 드라이브(예: 플로피 디스크 드라이브 또는 플래시 메모리 썸 드라이브)를 열 때 lpFileName 문자열은 "\.\X:" 형식이어야 합니다. 드라이브의 루트 디렉터리를 나타내는 후행 백슬래시(\)를 사용하지 마세요. 다음 표에서는 드라이브 문자열의 몇 가지 예를 보여 줍니다.
| String | 의미 |
|---|---|
| "\\.\A:" | 플로피 디스크 드라이브 A를 엽니다. |
| "\\.\C:" | C: 볼륨을 엽니다. |
| "\\.\C:\" | C: 볼륨의 파일 시스템을 엽니다. |
볼륨 이름을 참조하여 볼륨을 열 수도 있습니다. 자세한 내용은 볼륨 이름을 참조하세요.
볼륨에는 하나 이상의 탑재된 파일 시스템이 포함되어 있습니다. 볼륨 핸들은 CreateFile2에서 캐시되지 않은 옵션이 지정되지 않은 경우에도 특정 파일 시스템의 재량에 따라 캐시되지 않은 것으로 열 수 있습니다. 모든 Microsoft 파일 시스템이 볼륨 핸들을 캐시되지 않은 것으로 여는 것으로 가정해야 합니다. 파일에 대한 캐시되지 않은 I/O에 대한 제한 사항도 볼륨에 적용됩니다.
데이터가 캐시되지 않더라도 파일 시스템에 버퍼 맞춤이 필요하거나 필요하지 않을 수 있습니다. 그러나 볼륨을 열 때 캐시되지 않은 옵션을 지정하면 볼륨의 파일 시스템에 관계없이 버퍼 맞춤이 적용됩니다. 볼륨 핸들을 캐시되지 않은 것으로 열고 캐시되지 않은 I/O 제한을 따르는 모든 파일 시스템에서 권장됩니다.
Changer Device
DeviceIoControl에 대한 IOCTL_CHANGER_* 제어 코드는 변경자 디바이스에 대한 핸들을 허용합니다. 변경자 디바이스를 열려면 "\\.\Changerx" 형식의 파일 이름을 사용합니다. 여기서 x 는 0부터 시작하여 열 디바이스를 나타내는 숫자입니다. C 또는 C++로 작성된 애플리케이션에서 변경자 디바이스 0을 열려면 파일 이름 "\\\\.\\Changer0"을 사용합니다.테이프 드라이브
"\\.\TAPEx" 형식의 파일 이름을 사용하여 테이프 드라이브를 열 수 있습니다. 여기서 x 는 테이프 드라이브 0부터 시작하여 열 드라이브를 나타내는 숫자입니다. C 또는 C++로 작성된 애플리케이션에서 테이프 드라이브 0을 열려면 파일 이름 "\\\\.\\TAPE0"을 사용합니다.자세한 내용은 Backup을 참조 하세요.
통신 리소스
CreateFile2 함수는 직렬 포트 COM1과 같은 통신 리소스에 대한 핸들을 만들 수 있습니다. 통신 리소스의 경우 dwCreationDisposition 매개 변수는 OPEN_EXISTING, dwShareMode 매개 변수는 0(전용 액세스)이어야 하며 hTemplateFile 매개 변수는 NULL이어야 합니다. 읽기, 쓰기 또는 읽기/쓰기 액세스를 지정할 수 있으며 겹치는 I/O에 대해 핸들을 열 수 있습니다.9보다 큰 COM 포트 번호를 지정하려면 "\.\COM10" 구문을 사용합니다. 이 구문은 COM 포트 번호를 지정할 수 있는 모든 포트 번호 및 하드웨어에 대해 작동합니다.
통신에 대한 자세한 내용은 통신을 참조하세요.
콘솔
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 | 콘솔을 상속하려면 SECURITY_ATTRIBUTES 구조체의 bInheritHandle 멤버가 TRUE여야 합니다. |
|
dwFileAttributes
dwFileFlags dwSecurityQosFlags hTemplateFile |
무시됩니다. |
다음 표에서는 dwDesiredAccess 및 lpFileName의 다양한 설정을 보여 줍니다.
| lpFileName | dwDesiredAccess | 결과 |
|---|---|---|
| "CON" | GENERIC_READ | 입력할 콘솔을 엽니다. |
| "CON" | GENERIC_WRITE | 출력을 위한 콘솔을 엽니다. |
| "CON" | GENERIC_READ | GENERIC_WRITE |
CreateFile2가 실패하도록 합니다. GetLastError는ERROR_FILE_NOT_FOUND 반환합니다. |
메일 슬롯
CreateFile2가 mailslot의 클라이언트 끝을 열면 mailslot 클라이언트가 mailslot 서버가 CreateMailSlot 함수를 사용하여 만들기 전에 mailslot 클라이언트가 로컬 mailslot을 열려고 하면 INVALID_HANDLE_VALUE 반환합니다.자세한 내용은 Mailslots를 참조하세요.
파이프
CreateFile2에서 명명된 파이프의 클라이언트 끝을 열면 함수는 수신 대기 상태에 있는 명명된 파이프의 instance 사용합니다. 여는 프로세스는 필요에 따라 핸들을 여러 번 복제할 수 있지만, 핸들을 연 후에는 명명된 파이프 instance 다른 클라이언트에서 열 수 없습니다. 파이프를 열 때 지정된 액세스는 CreateNamedPipe 함수의 dwOpenMode 매개 변수에 지정된 액세스와 호환되어야 합니다.이 작업 전에 서버에서 CreateNamedPipe 함수가 성공적으로 호출되지 않은 경우 파이프가 존재하지 않으며 CreateFile2 가 ERROR_FILE_NOT_FOUND 실패합니다.
활성 파이프 instance 하나 이상 있지만 서버에 사용 가능한 수신기 파이프가 없으면 모든 파이프 인스턴스가 현재 연결되어 있으므로 CreateFile2는 ERROR_PIPE_BUSY 실패합니다.
자세한 내용은 파이프를 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows 8 [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2012 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | fileapi.h(Windows.h 포함) |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |
참고 항목
함수
개요 항목
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기