CreateFileMapping2 함수(memoryapi.h)
지정된 파일에 대한 명명되거나 명명되지 않은 파일 매핑 개체를 만들거나 엽니다. 물리적 메모리에 대한 기본 NUMA 노드를 확장 매개 변수로 지정할 수 있습니다. ExtendedParameters 매개 변수를 참조하세요.
구문
HANDLE CreateFileMapping2(
HANDLE File,
SECURITY_ATTRIBUTES *SecurityAttributes,
ULONG DesiredAccess,
ULONG PageProtection,
ULONG AllocationAttributes,
ULONG64 MaximumSize,
PCWSTR Name,
MEM_EXTENDED_PARAMETER *ExtendedParameters,
ULONG ParameterCount
);
매개 변수
File
형식: _In_ HANDLE
파일 매핑 개체를 만들 파일에 대한 핸들입니다.
flProtect 매개 변수가 지정하는 보호 플래그와 호환되는 액세스 권한으로 파일을 열어야 합니다. 필수는 아니지만 매핑하려는 파일을 단독 액세스를 위해 여는 것이 좋습니다. 자세한 내용은 파일 보안 및 액세스 권한을 참조하세요.
hFile이 INVALID_HANDLE_VALUE 경우 호출 프로세스는 dwMaximumSizeHigh 및 dwMaximumSizeLow 매개 변수에서 파일 매핑 개체의 크기도 지정해야 합니다. 이 시나리오에서 CreateFileMapping 은 파일 시스템의 파일 대신 시스템 페이징 파일에서 지원되는 지정된 크기의 파일 매핑 개체를 만듭니다.
SecurityAttributes
형식: _In_opt_ SECURITY_ATTRIBUTES*
반환된 핸들을 자식 프로세스에서 상속할 수 있는지 여부를 결정하는 SECURITY_ATTRIBUTES 구조체에 대한 포인터입니다. SECURITY_ATTRIBUTES 구조체의 lpSecurityDescriptor 멤버는 새 파일 매핑 개체에 대한 보안 설명자를 지정합니다.
lpAttributes가 NULL이면 핸들을 상속할 수 없으며 파일 매핑 개체는 기본 보안 설명자를 가져옵니다. 파일 매핑 개체에 대한 기본 보안 설명자의 ACL(액세스 제어 목록)은 작성자의 기본 또는 가장 토큰에서 가져옵니다. 자세한 내용은 파일 매핑 보안 및 액세스 권한을 참조하세요.
DesiredAccess
형식: _In_ ULONG
반환된 파일 매핑 핸들에 대한 원하는 액세스 마스크입니다. 액세스 권한 목록은 파일 매핑 보안 및 액세스 권한을 참조하세요.
PageProtection
형식: _In_ ULONG
파일 매핑 개체의 페이지 보호를 지정합니다. 개체의 모든 매핑된 뷰는 이 보호와 호환되어야 합니다.
이 매개 변수는 다음 값 중 하나일 수 있습니다.
AllocationAttributes
형식: _In_ ULONG
파일 매핑 개체에 대해 다음 특성 중 하나 이상을 지정할 수 있습니다. PageProtection 매개 변수도 참조하세요.
| 값 | 의미 |
|---|---|
|
파일 매핑 개체가 운영 체제 페이징 파일( 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_RESERVE SEC_COMMIT 결합할 수 없습니다. |
|
모든 페이지를 쓰기 결합으로 설정합니다.
애플리케이션은 디바이스에 명시적으로 필요한 경우를 제외하고 이 특성을 사용하면 안 됩니다. SEC_WRITECOMBINE 매핑된 메모리와 함께 연결된 함수를 사용하면 EXCEPTION_ILLEGAL_INSTRUCTION 예외가 발생할 수 있습니다. SEC_WRITECOMBINESEC_RESERVE 또는 SEC_COMMIT 특성을 설정해야 합니다. Windows Server 2003 및 Windows XP: 이 플래그는 Windows Vista까지 지원되지 않습니다. |
MaximumSize
형식: _In_ ULONG64
파일 매핑 개체의 최대 크기입니다.
이 매개 변수가 0인 경우 파일 매핑 개체의 최대 크기는 hFile 에서 식별하는 파일의 현재 크기와 같습니다.
길이가 0인 파일을 매핑하려고 시도하면 오류 코드가 ERROR_FILE_INVALID 실패합니다. 길이가 0인 파일을 테스트하고 해당 파일을 거부해야 합니다.
Name
형식: _In_opt_ PCWSTR
파일 매핑 개체의 이름입니다.
이 매개 변수가 기존 매핑 개체의 이름과 일치하는 경우 함수는 flProtect 가 지정하는 보호를 사용하여 개체에 대한 액세스를 요청합니다.
이 매개 변수가 NULL이면 파일 매핑 개체가 이름 없이 만들어집니다.
lpName이 기존 이벤트, 세마포, 뮤텍스, 대기 가능한 타이머 또는 작업 개체의 이름과 일치하면 함수가 실패하고 GetLastError 함수가 ERROR_INVALID_HANDLE 반환합니다. 이러한 개체는 동일한 네임스페이스를 공유하기 때문에 발생합니다.
이름에는 전역 또는 세션 네임스페이스에 개체를 명시적으로 만드는 "전역" 또는 "로컬" 접두사를 사용할 수 있습니다. 이름의 나머지 부분에는 백슬래시 문자(\)를 제외한 모든 문자가 포함될 수 있습니다. 세션 0 이외의 세션에서 전역 네임스페이스에 파일 매핑 개체를 만들려면 SeCreateGlobalPrivilege 권한이 필요합니다. 자세한 내용은 커널 개체 네임스페이스를 참조하세요.
빠른 사용자 전환은 터미널 서비스 세션을 사용하여 구현됩니다. 로그온하는 첫 번째 사용자는 세션 0(0)을 사용하고, 로그온할 다음 사용자는 세션 1(1) 등을 사용합니다. 커널 개체 이름은 애플리케이션이 여러 사용자를 지원할 수 있도록 터미널 서비스에 대해 설명된 지침을 따라야 합니다.
ExtendedParameters
형식: _Inout_updates_opt_(ParameterCount) MEM_EXTENDED_PARAMETER*
MEM_EXTENDED_PARAMETER 형식의 확장 매개 변수 하나 이상에 대한 선택적 포인터입니다. 이러한 각 확장 매개 변수 값 자체에는 MemExtendedParameterAddressRequirements 또는 MemExtendedParameterNumaNode의 형식 필드가 있을 수 있습니다. MemExtendedParameterNumaNode 확장 매개 변수가 제공되지 않으면 동작은 VirtualAlloc/MapViewOfFile 함수와 동일합니다(즉, 실제 페이지에 대한 기본 NUMA 노드는 먼저 메모리에 액세스하는 스레드의 이상적인 프로세서에 따라 결정됨).
ParameterCount
In ULONG ParameterCount
ExtendedParameters가 가리키는 확장 매개 변수 수입니다.
반환 값
함수가 성공하면 반환 값은 새로 만든 파일 매핑 개체에 대한 핸들입니다.
함수 호출 전에 개체가 있는 경우 함수는 기존 개체에 대한 핸들(지정된 크기가 아닌 현재 크기)을 반환하고 GetLastError 는 ERROR_ALREADY_EXISTS 반환합니다.
함수가 실패하면 반환 값은 NULL입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.
설명
CreateFileMapping에 대한 설명을 참조하세요.
예제
예를 들어 명명된 공유 메모리 만들기 또는 큰 페이지를 사용하여 파일 매핑 만들기를 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows 10 빌드 20348 |
| 지원되는 최소 서버 | Windows 10 빌드 20348 |
| 대상 플랫폼 | Windows |
| 헤더 | memoryapi.h(Windows.h, Memoryapi.h 포함) |
| 라이브러리 | onecore.lib |
| DLL | Kernel32.dll |
참고 항목
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기