CreateFileMappingW 함수(memoryapi.h)
지정된 파일에 대한 명명되거나 명명되지 않은 파일 매핑 개체를 만들거나 엽니다.
실제 메모리에 대한 NUMA 노드를 지정하려면 CreateFileMappingNuma참조하세요.
통사론
HANDLE CreateFileMappingW(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCWSTR lpName
);
매개 변수
[in] hFile
파일 매핑 개체를 만들 파일에 대한 핸들입니다.
flProtect 매개 변수가 지정하는 보호 플래그와 호환되는 액세스 권한으로 파일을 열어야 합니다. 필수는 아니지만 매핑하려는 파일을 단독 액세스를 위해 여는 것이 좋습니다. 자세한 내용은 파일 보안 및 액세스 권한참조하세요.
[in, optional] lpFileMappingAttributes
반환된 핸들을 자식 프로세스에서 상속할 수 있는지 여부를 결정하는 SECURITY_ATTRIBUTES 구조체에 대한 포인터입니다. SECURITY_ATTRIBUTES 구조체의 lpSecurityDescriptor 멤버는 새 파일 매핑 개체에 대한 보안 설명자를 지정합니다.
[in] flProtect
파일 매핑 개체의 페이지 보호를 지정합니다. 개체의 모든 매핑된 뷰는 이 보호와 호환되어야 합니다.
이 매개 변수는 다음 값 중 하나일 수 있습니다.
애플리케이션은 이전 페이지 보호 값 중 하나와 결합하여 파일 매핑 개체에 대해 다음 특성 중 하나 이상을 지정할 수 있습니다.
| 값 | 의미 |
|---|---|
|
파일 매핑 개체가 운영 체제 페이징 파일에서 지원되는 경우(hfile 매개 변수가 INVALID_HANDLE_VALUE), 파일 보기가 프로세스 주소 공간에 매핑될 때 전체 페이지 범위가 예약되지 않고 커밋되도록 지정합니다. 시스템에 전체 매핑을 저장할 수 있는 커밋 가능한 페이지가 있어야 합니다. 그렇지 않으면 CreateFileMapping 이 특성은 실행 파일 또는 데이터 파일에서 지원되는 파일 매핑 개체에 영향을 주지 않습니다(hfile 매개 변수는 파일 핸들). SEC_COMMITSEC_RESERVE함께 사용할 수 없습니다. 특성을 지정하지 않으면 SEC_COMMIT 가정합니다. 그러나 SEC_COMMIT 필요한 다른 SEC_ 특성과 결합할 때 명시적으로 지정해야 합니다. |
|
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 호출자의 토큰에서 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
파일 매핑 개체의 최대 크기 높은 순서의
[in] dwMaximumSizeLow
낮은 순서의 DWORD는 파일 매핑 개체의 최대 크기.
이 매개 변수와
길이가 0인 파일을 매핑하려고 시도하면 오류 코드가 ERROR_FILE_INVALID. 애플리케이션은 길이가 0인 파일을 테스트하고 해당 파일을 거부해야 합니다.
[in, optional] lpName
파일 매핑 개체의 이름입니다.
이 매개 변수가 기존 매핑 개체의 이름과 일치하는 경우 함수는 flProtect 지정하는 보호를 사용하여 개체에 대한 액세스를 요청합니다.
이 매개 변수가 NULL
lpName 기존 이벤트, 세마포, 뮤텍스, 대기 가능한 타이머 또는 작업 개체의 이름과 일치하면 함수가 실패하고 GetLastError 함수는 ERROR_INVALID_HANDLE반환합니다. 이러한 개체는 동일한 네임스페이스를 공유하기 때문에 발생합니다.
이름에는 전역 또는 세션 네임스페이스에서 개체를 명시적으로 만드는 "전역" 또는 "로컬" 접두사를 가질 수 있습니다. 이름의 나머지 부분에는 백슬래시 문자(\)를 제외한 모든 문자가 포함될 수 있습니다. 세션 0 이외의 세션에서 전역 네임스페이스에 파일 매핑 개체를 만들려면 SeCreateGlobalPrivilege 권한이 필요합니다. 자세한 내용은 커널 개체 네임스페이스
빠른 사용자 전환은 터미널 서비스 세션을 사용하여 구현됩니다. 로그온하는 첫 번째 사용자는 세션 0(0)을 사용하고, 로그온할 다음 사용자는 세션 1(1) 등을 사용합니다. 커널 개체 이름은 애플리케이션이 여러 사용자를 지원할 수 있도록 터미널 서비스에 대해 설명된 지침을 따라야 합니다.
반환 값
함수가 성공하면 반환 값은 새로 만든 파일 매핑 개체에 대한 핸들입니다.
함수 호출 전에 개체가 있는 경우 함수는 지정된 크기가 아닌 현재 크기로 기존 개체에 대한 핸들을 반환하고 GetLastErrorERROR_ALREADY_EXISTS반환합니다.
함수가 실패하면 반환 값은 NULL
발언
파일 매핑 개체를 만든 후에는 파일 크기가 파일 매핑 개체의 크기를 초과하지 않아야 합니다. 이 경우 모든 파일 내용을 공유할 수 있는 것은 아닙니다.
애플리케이션이 디스크의 실제 명명된 파일 크기보다 큰 파일 매핑 개체의 크기를 지정하고 페이지 보호에서 쓰기 액세스를 허용하는 경우(즉, flProtect 매개 변수가 PAGE_READWRITE 또는 PAGE_EXECUTE_READWRITE지정함) 디스크의 파일이 파일 매핑 개체의 지정된 크기와 일치하도록 증가합니다. 파일이 확장되면 파일의 이전 끝과 파일의 새 끝 사이의 파일 내용이 0으로 보장되지 않습니다. 동작은 파일 시스템에 의해 정의됩니다. 디스크의 파일을 늘릴 수 없는 경우 CreateFileMapping
운영 체제 페이징 파일에서 지원되는 파일 매핑 개체의 페이지 초기 콘텐츠는 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_READCreateFileMapping 호출한 다음 FILE_MAP_EXECUTE | FILE_MAP_WRITE 또는 FILE_MAP_EXECUTE | FILE_MAP_READMapViewOfFile 호출해야 합니다.
Windows Server 2012에서 이 함수는 다음 기술에서 지원됩니다.
| 기술 | 지원 |
|---|---|
| SMB(서버 메시지 블록) 3.0 프로토콜 | 예 |
| SMB 3.0 TFO(투명한 장애 조치(failover) | 예 |
| SO(스케일 아웃 파일 공유)가 있는 SMB 3.0 | 예 |
| CsvFS(클러스터 공유 볼륨 파일 시스템) | 예 |
| ReFS(복원 파일 시스템) | 예 |
예제
예를 들어 명명된 공유 메모리 만들기 또는 큰 페이지사용하여 파일 매핑 만들기를 참조하세요.
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | memoryapi.h(Windows.h, Memoryapi.h 포함) |
| 라이브러리 | onecore.lib |
| DLL | Kernel32.dll |
참고 항목
closeHandle
파일 매핑 개체 만들기
파일 매핑 함수
mapViewOfFile
mapViewOfFileEx
OpenFileMapping
ReadFile
UnmapViewOfFile
WriteFile