CreateFileMappingNumaA 함수(winbase.h)
지정된 파일에 대한 명명되거나 명명되지 않은 파일 매핑 개체를 만들거나 열고 실제 메모리에 대한 NUMA 노드를 지정합니다.
통사론
HANDLE CreateFileMappingNumaA(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCSTR lpName,
[in] DWORD nndPreferred
);
매개 변수
[in] hFile
파일 매핑 개체를 만들 파일에 대한 핸들입니다.
flProtect 매개 변수가 지정하는 보호 플래그와 호환되는 액세스 권한으로 파일을 열어야 합니다. 필수는 아니지만 매핑하려는 파일을 단독 액세스를 위해 여는 것이 좋습니다. 자세한 내용은 파일 보안 및 액세스 권한참조하세요.
[in, optional] lpFileMappingAttributes
반환된 핸들을 자식 프로세스에서 상속할 수 있는지 여부를 결정하는 SECURITY_ATTRIBUTES 구조체에 대한 포인터입니다.
lpSecurityDescriptor 멤버
SECURITY_ATTRIBUTES 구조체는 새 파일 매핑 개체에 대한 보안 설명자를 지정합니다.
[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
파일 매핑 개체의 최대 크기 높은 순서의
[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
발언
파일 매핑 개체를 만든 후에는 파일 크기가 파일 매핑 개체의 크기를 초과하지 않아야 합니다. 이 경우 모든 파일 내용을 공유할 수 있는 것은 아닙니다.
파일 매핑 개체는 중복, 상속 또는 이름으로 공유할 수 있습니다. 페이지 파일에서 지원되는 파일 매핑 개체의 페이지 초기 콘텐츠는 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_READCreateFileMappingNuma 함수를 호출한 다음 FILE_MAP_EXECUTE | FILE_MAP_WRITE 또는 FILE_MAP_EXECUTE | FILE_MAP_READ사용하여 MapViewOfFileExNuma 함수를 호출해야 합니다.
Windows Server 2012에서 이 함수는 다음 기술에서 지원됩니다.
| 기술 | 지원 |
|---|---|
| SMB(서버 메시지 블록) 3.0 프로토콜 | 예 |
| SMB 3.0 TFO(투명한 장애 조치(failover) | 예 |
| SO(스케일 아웃 파일 공유)가 있는 SMB 3.0 | 예 |
| CsvFS(클러스터 공유 볼륨 파일 시스템) | 예 |
| ReFS(복원 파일 시스템) | 예 |
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows Vista [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2008 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | winbase.h(Windows.h, Memoryapi.h 포함) |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |
참고 항목
closeHandle
CreateFileMapping
NUMA 지원
OpenFileMapping
ReadFile
UnmapViewOfFile
WriteFile