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