CreateFileMappingA 함수(winbase.h)
지정된 파일에 대한 명명되거나 명명되지 않은 파일 매핑 개체를 만들거나 엽니다.
실제 메모리에 대한 NUMA 노드를 지정하려면 CreateFileMappingNuma를 참조하세요.
구문
HANDLE CreateFileMappingA(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCSTR lpName
);
매개 변수
[in] hFile
파일 매핑 개체를 만들 파일에 대한 핸들입니다.
flProtect 매개 변수가 지정하는 보호 플래그와 호환되는 액세스 권한으로 파일을 열어야 합니다. 필수는 아니지만 매핑하려는 파일을 단독 액세스용으로 여는 것이 좋습니다. 자세한 내용은 파일 보안 및 액세스 권한을 참조하세요.
hFile이 INVALID_HANDLE_VALUE 경우 호출 프로세스는 dwMaximumSizeHigh 및 dwMaximumSizeLow 매개 변수에서 파일 매핑 개체의 크기도 지정해야 합니다. 이 시나리오에서 CreateFileMapping 은 파일 시스템의 파일이 아닌 시스템 페이징 파일에서 지원되는 지정된 크기의 파일 매핑 개체를 만듭니다.
[in, optional] lpFileMappingAttributes
반환된 핸들을 자식 프로세스에서 상속할 수 있는지 여부를 결정하는 SECURITY_ATTRIBUTES 구조체에 대한 포인터입니다. SECURITY_ATTRIBUTES 구조체의 lpSecurityDescriptor 멤버는 새 파일 매핑 개체에 대한 보안 설명자를 지정합니다.
lpFileMappingAttributes가 NULL이면 핸들을 상속할 수 없으며 파일 매핑 개체는 기본 보안 설명자를 가져옵니다. 파일 매핑 개체에 대한 기본 보안 설명자의 ACL(액세스 제어 목록)은 작성자의 기본 또는 가장 토큰에서 가져옵니다. 자세한 내용은 파일 매핑 보안 및 액세스 권한을 참조하세요.
[in] flProtect
파일 매핑 개체의 페이지 보호를 지정합니다. 개체의 모든 매핑된 뷰는 이 보호와 호환되어야 합니다.
이 매개 변수는 다음 값 중 하나일 수 있습니다.
애플리케이션은 이전 페이지 보호 값 중 하나와 결합하여 파일 매핑 개체에 대해 다음 특성 중 하나 이상을 지정할 수 있습니다.
| 값 | 의미 |
|---|---|
|
파일 매핑 개체가 운영 체제 페이징 파일에서 백업되는 경우( hfile 매개 변수가 INVALID_HANDLE_VALUE), 파일 보기가 프로세스 주소 공간에 매핑될 때 전체 페이지 범위가 예약되지 않고 커밋되도록 지정합니다. 시스템에는 전체 매핑을 저장할 수 있는 커밋 가능한 페이지가 충분히 있어야 합니다. 그렇지 않으면 CreateFileMapping 이 실패합니다.
이 특성은 실행 파일 이미지 파일 또는 데이터 파일에서 백업되는 파일 매핑 개체에 영향을 주지 않습니다( hfile 매개 변수는 파일에 대한 핸들임). SEC_COMMITSEC_RESERVE 결합할 수 없습니다. 특성이 지정되지 않은 경우 SEC_COMMIT 가정합니다. |
|
hFile 매개 변수가 지정하는 파일이 실행 파일 이미지 파일임을 지정합니다.
SEC_IMAGE 특성은 PAGE_READONLY 같은 페이지 보호 값과 결합되어야 합니다. 그러나 이 페이지 보호 값은 실행 파일 이미지 파일의 보기에 영향을 주지 않습니다. 실행 파일 이미지 파일의 보기에 대한 페이지 보호는 실행 파일 자체에 의해 결정됩니다. 다른 특성은 SEC_IMAGE 유효하지 않습니다. |
|
hFile 매개 변수가 지정하는 파일이 실행되지 않을 실행 가능한 이미지 파일이며 로드된 이미지 파일에 강제 무결성 검사가 실행되지 않도록 지정합니다.
또한 SEC_IMAGE_NO_EXECUTE 특성으로 만든 파일 매핑 개체의 보기를 매핑해도 PsSetLoadImageNotifyRoutine 커널 API를 사용하여 등록된 드라이버 콜백이 호출되지 않습니다.
SEC_IMAGE_NO_EXECUTE 특성은 PAGE_READONLY 페이지 보호 값과 결합되어야 합니다. 다른 특성은 SEC_IMAGE_NO_EXECUTE 유효하지 않습니다. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 이 값은 Windows Server 2012 및 Windows 8 전에 지원되지 않습니다. |
|
운영 체제 페이징 파일에서 지원하는 파일 매핑 개체에 큰 페이지를 사용할 수 있습니다( hfile 매개 변수는 INVALID_HANDLE_VALUE). 이 특성은 실행 파일 또는 데이터 파일에서 지원하는 파일 매핑 개체에 대해 지원되지 않습니다( hFile 매개 변수는 실행 파일 이미지 또는 데이터 파일에 대한 핸들임).
파일 매핑 개체의 최대 크기는 GetLargePageMinimum 함수에서 반환하는 큰 페이지의 최소 크기의 배수여야 합니다. 그렇지 않으면 CreateFileMapping 이 실패합니다. SEC_LARGE_PAGES 사용하여 만든 파일 매핑 개체의 뷰를 매핑하는 경우 기본 주소와 보기 크기도 최소 큰 페이지 크기의 배수여야 합니다. SEC_LARGE_PAGES 호출자의 토큰에서 SeLockMemoryPrivilege 권한을 사용하도록 설정해야 합니다. SEC_LARGE_PAGES 지정한 경우 SEC_COMMIT 지정해야 합니다. Windows Server 2003: 이 값은 WINDOWS Server 2003 SP1까지 지원되지 않습니다. Windows XP: 이 값은 지원되지 않습니다. |
|
모든 페이지를 캐시할 수 없도록 설정합니다.
애플리케이션은 디바이스에 명시적으로 필요한 경우를 제외하고 이 특성을 사용하면 안 됩니다. SEC_NOCACHE 매핑된 메모리와 함께 연동 함수를 사용하면 EXCEPTION_ILLEGAL_INSTRUCTION 예외 가 발생할 수 있습니다. SEC_NOCACHESEC_RESERVE 또는 SEC_COMMIT 특성을 설정해야 합니다. |
|
파일 매핑 개체가 운영 체제 페이징 파일( hfile 매개 변수 가 INVALID_HANDLE_VALUE)에 의해 지원되는 경우 파일 보기가 프로세스 주소 공간에 매핑될 때 전체 페이지 범위가 커밋되지 않고 프로세스에서 나중에 사용하도록 예약되도록 지정합니다.
예약된 페이지는 VirtualAlloc 함수에 대한 후속 호출에서 커밋할 수 있습니다. 페이지를 커밋한 후에는 VirtualFree 함수를 사용하여 해제하거나 커밋 해제할 수 없습니다. 이 특성은 실행 파일 이미지 파일 또는 데이터 파일( hfile 매개 변수는 파일에 대한 핸들)에 의해 뒷받침되는 파일 매핑 개체에 영향을 주지 않습니다. SEC_RESERVESEC_COMMIT 결합할 수 없습니다. |
|
모든 페이지를 쓰기 결합으로 설정합니다.
애플리케이션은 디바이스에 명시적으로 필요한 경우를 제외하고 이 특성을 사용하면 안 됩니다. SEC_WRITECOMBINE 매핑된 메모리와 함께 연결된 함수를 사용하면 EXCEPTION_ILLEGAL_INSTRUCTION 예외가 발생할 수 있습니다. SEC_WRITECOMBINESEC_RESERVE 또는 SEC_COMMIT 특성을 설정해야 합니다. Windows Server 2003 및 Windows XP: 이 플래그는 Windows Vista까지 지원되지 않습니다. |
[in] dwMaximumSizeHigh
파일 매핑 개체의 최대 크기의 상위 DWORD 입니다.
[in] dwMaximumSizeLow
파일 매핑 개체의 최대 크기의 낮은 순서 DWORD 입니다.
이 매개 변수와 dwMaximumSizeHigh 가 0인 경우 파일 매핑 개체의 최대 크기는 hFile 에서 식별하는 파일의 현재 크기와 같습니다.
길이가 0인 파일을 매핑하려고 시도하면 오류 코드가 ERROR_FILE_INVALID 실패합니다. 애플리케이션은 길이가 0인 파일을 테스트하고 해당 파일을 거부해야 합니다.
[in, optional] lpName
파일 매핑 개체의 이름입니다.
이 매개 변수가 기존 매핑 개체의 이름과 일치하는 경우 함수는 flProtect 가 지정하는 보호를 사용하여 개체에 대한 액세스를 요청합니다.
이 매개 변수가 NULL이면 이름 없이 파일 매핑 개체가 만들어집니다.
lpName이 기존 이벤트, 세마포, 뮤텍스, 대기 가능한 타이머 또는 작업 개체의 이름과 일치하면 함수가 실패하고 GetLastError 함수가 ERROR_INVALID_HANDLE 반환합니다. 이 문제는 이러한 개체가 동일한 네임스페이스를 공유하기 때문에 발생합니다.
이름에는 전역 또는 세션 네임스페이스에 개체를 명시적으로 만드는 "전역" 또는 "로컬" 접두사를 가질 수 있습니다. 이름의 나머지 부분에는 백슬래시 문자(\)를 제외한 모든 문자가 포함될 수 있습니다. 세션 0이 아닌 세션에서 전역 네임스페이스에 파일 매핑 개체를 만들려면 SeCreateGlobalPrivilege 권한이 필요합니다. 자세한 내용은 커널 개체 네임스페이스를 참조하세요.
빠른 사용자 전환은 터미널 서비스 세션을 사용하여 구현됩니다. 로그온하는 첫 번째 사용자는 세션 0(0)을 사용하고, 로그온할 다음 사용자는 세션 1(1) 등을 사용합니다. 커널 개체 이름은 애플리케이션이 여러 사용자를 지원할 수 있도록 터미널 서비스에 대해 설명된 지침을 따라야 합니다.
반환 값
함수가 성공하면 반환 값은 새로 만든 파일 매핑 개체에 대한 핸들입니다.
함수 호출 전에 개체가 있는 경우 함수는 기존 개체에 대한 핸들을 반환하고(지정된 크기가 아닌 현재 크기) GetLastError 는 ERROR_ALREADY_EXISTS 반환합니다.
함수가 실패하면 반환 값은 NULL입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.
설명
파일 매핑 개체를 만든 후에는 파일 크기가 파일 매핑 개체의 크기를 초과하지 않아야 합니다. 이 경우 모든 파일 콘텐츠를 공유할 수 있는 것은 아닙니다.
애플리케이션이 디스크의 실제 명명된 파일 크기보다 큰 파일 매핑 개체의 크기를 지정하고 페이지 보호에서 쓰기 액세스를 허용하는 경우(즉, flProtect 매개 변수가 PAGE_READWRITE 또는 PAGE_EXECUTE_READWRITE 지정함) 디스크의 파일이 파일 매핑 개체의 지정된 크기와 일치하도록 증가합니다. 파일이 확장되면 파일의 이전 끝과 파일의 새 끝 사이의 파일 내용이 0으로 보장되지 않습니다. 동작은 파일 시스템에 의해 정의됩니다. 디스크의 파일을 늘릴 수 없으면 CreateFileMapping 이 실패하고 GetLastError가ERROR_DISK_FULL 반환합니다.
운영 체제 페이징 파일에서 백업되는 파일 매핑 개체의 페이지 초기 콘텐츠는 0입니다.
CreateFileMapping이 반환하는 핸들은 새 파일 매핑 개체에 대한 모든 액세스 권한을 가지며 파일 매핑 개체에 대한 핸들이 필요한 모든 함수와 함께 사용할 수 있습니다.
여러 프로세스는 단일 공유 파일 매핑 개체를 사용하거나 동일한 파일에서 지원되는 별도의 파일 매핑 개체를 만들어 동일한 파일의 보기를 공유할 수 있습니다. 단일 파일 매핑 개체는 프로세스 생성 시 핸들을 상속하거나, 핸들을 복제하거나, 이름으로 파일 매핑 개체를 열어 여러 프로세스에서 공유할 수 있습니다. 자세한 내용은 CreateProcess, DuplicateHandle 및 OpenFileMapping 함수를 참조하세요.
파일 매핑 개체를 만들면 실제로 뷰를 프로세스 주소 공간에 매핑하지 않습니다. MapViewOfFile 및 MapViewOfFileEx 함수는 파일 보기를 프로세스 주소 공간에 매핑합니다.
한 가지 중요한 예외를 제외하고 동일한 파일에서 백업되는 파일 매핑 개체에서 파생된 파일 뷰는 특정 시간에 일관되거나 동일합니다. 일관성은 프로세스 내의 뷰 및 다른 프로세스에 의해 매핑되는 뷰에 대해 보장됩니다.
예외는 원격 파일과 관련이 있습니다. CreateFileMapping은 원격 파일에서 작동하지만 일관성을 유지하지는 않습니다. 예를 들어 두 컴퓨터가 모두 파일을 쓰기 가능으로 매핑하고 둘 다 동일한 페이지를 변경하는 경우 각 컴퓨터는 페이지에 대한 자체 쓰기만 볼 수 있습니다. 디스크에서 데이터가 업데이트되면 병합되지 않습니다.
입력 및 출력(I/O) 함수(ReadFile 및 WriteFile)를 사용하여 액세스하는 매핑된 파일과 파일이 반드시 일관되지는 않습니다.
파일 매핑 개체의 매핑된 뷰는 개체에 대한 내부 참조를 유지 관리하며, 파일에 대한 모든 참조가 해제될 때까지 파일 매핑 개체가 닫히지 않습니다. 따라서 파일 매핑 개체를 완전히 닫기 위해 애플리케이션은 UnmapViewOfFile 을 호출하여 파일 매핑 개체의 매핑된 뷰를 모두 매핑 해제하고 CloseHandle을 호출하여 파일 매핑 개체 핸들을 닫아야 합니다. 이러한 함수는 어떤 순서로든 호출할 수 있습니다.
매핑된 보기를 통해 파일을 수정하는 경우 마지막 수정 타임스탬프가 자동으로 업데이트되지 않을 수 있습니다. 필요한 경우 호출자는 SetFileTime 을 사용하여 타임스탬프를 설정해야 합니다.
세션 0이 아닌 세션에서 전역 네임스페이스에 파일 매핑 개체를 만들려면 SeCreateGlobalPrivilege 권한이 필요합니다. 이 권한 검사 파일 매핑 개체 만들기로 제한되며 기존 개체를 여는 데는 적용되지 않습니다. 예를 들어 서비스 또는 시스템이 전역 네임스페이스에 파일 매핑 개체를 만드는 경우 모든 세션에서 실행되는 모든 프로세스는 호출자에게 필요한 액세스 권한이 있는 경우 해당 파일 매핑 개체에 액세스할 수 있습니다.
Windows XP: 이전 단락에서 설명한 요구 사항은 Windows Server 2003 및 Windows XP SP2에서 도입되었습니다.
구조적 예외 처리를 사용하여 파일 뷰에서 쓰거나 읽는 코드를 보호합니다. 자세한 내용은 파일 보기에서 읽기 및 쓰기를 참조하세요.
실행 가능한 권한으로 매핑하려면 애플리케이션이 PAGE_EXECUTE_READWRITE 또는PAGE_EXECUTE_READ사용하여 CreateFileMapping을 호출한 다음 또는 FILE_MAP_EXECUTE | FILE_MAP_READ를 사용하여 MapViewOfFile을 FILE_MAP_EXECUTE | FILE_MAP_WRITE 호출해야 합니다.
Windows Server 2012 이 함수는 다음 기술에서 지원됩니다.
| 기술 | 지원됨 |
|---|---|
| SMB(서버 메시지 블록) 3.0 프로토콜 | Yes |
| SMB 3.0 TFO(투명 장애 조치(failover)) | Yes |
| SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0 | Yes |
| CsvFS(클러스터 공유 볼륨 파일 시스템) | Yes |
| ReFS(Resilient File System) | 예 |
예제
예를 들어 명명된 공유 메모리 만들기 또는 큰 페이지를 사용하여 파일 매핑 만들기를 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | winbase.h(Windows.h, Memoryapi.h 포함) |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |
참고 항목
파일 매핑 함수
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기