Поделиться через


Функция 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 . Это не обязательно, но рекомендуется открывать файлы, которые планируется сопоставить, для монопольного доступа. Дополнительные сведения см. в разделе Безопасность файлов и права доступа.

Если hFileINVALID_HANDLE_VALUE, вызывающий процесс должен также указать размер объекта сопоставления файлов в параметрах dwMaximumSizeHigh и dwMaximumSizeLow . В этом сценарии CreateFileMappingNuma создает объект сопоставления файлов указанного размера, который поддерживается системным файлом подкачки, а не файлом в файловой системе.

[in, optional] lpFileMappingAttributes

Указатель на структуру SECURITY_ATTRIBUTES , которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Элемент lpSecurityDescriptor
SECURITY_ATTRIBUTES структура задает дескриптор безопасности для нового объекта сопоставления файлов.

Если lpFileMappingAttributes имеет значение NULL, дескриптор не может быть унаследован, а объект сопоставления файлов получает дескриптор безопасности по умолчанию. Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для объекта сопоставления файлов поступают из основного маркера или маркера олицетворения создателя. Дополнительные сведения см. в разделе Безопасность сопоставления файлов и права доступа.

[in] flProtect

Задает защиту страницы объекта сопоставления файлов. Все сопоставленные представления объекта должны быть совместимы с этой защитой.

Этот параметр может принимать одно из указанных ниже значений.

Значение Значение
PAGE_EXECUTE_READ
0x20
Позволяет сопоставлять представления для доступа только для чтения, копирования при записи или выполнения.

Дескриптор файла, который указывает параметр hFile , должен быть создан с правами доступа GENERIC_READ и GENERIC_EXECUTE .

PAGE_EXECUTE_READWRITE
0x40
Позволяет сопоставлять представления для доступа только для чтения, копирования при записи, чтения и записи или выполнения.

Дескриптор файла, который указывает параметр hFile , должен быть создан с правами доступа GENERIC_READ, GENERIC_WRITE и GENERIC_EXECUTE .

PAGE_EXECUTE_WRITECOPY
0x80
Позволяет сопоставлять представления для доступа только для чтения, копирования при записи или выполнения. Это значение эквивалентно PAGE_EXECUTE_READ.

Дескриптор файла, который указывает параметр hFile , должен быть создан с правами доступа GENERIC_READ и GENERIC_EXECUTE .

Windows Vista: Это значение недоступно до windows Vista с пакетом обновления 1 (SP1).

PAGE_READONLY
0x02
Позволяет сопоставлять представления для доступа только для чтения или копирования при записи. Попытка записи в определенный регион приводит к нарушению доступа.

Дескриптор файла, который указывает параметр hFile , должен быть создан с правом доступа GENERIC_READ .

PAGE_READWRITE
0x04
Позволяет сопоставлять представления для доступа только для чтения, копирования при записи или для чтения и записи.

Дескриптор файла, который указывает параметр hFile , должен быть создан с правами доступа GENERIC_READ и GENERIC_WRITE .

PAGE_WRITECOPY
0x08
Позволяет сопоставлять представления для доступа только для чтения или копирования при записи. Это значение эквивалентно PAGE_READONLY.

Дескриптор файла, который указывает параметр hFile , должен быть создан с правом доступа GENERIC_READ .

 

Приложение может указать один или несколько следующих атрибутов для объекта сопоставления файлов, объединяя их с одним из предыдущих значений защиты страниц.

Значение Значение
SEC_COMMIT
0x8000000
Выделяет физическое хранилище в памяти или файл подкачки для всех страниц.

Это параметр по умолчанию.

SEC_IMAGE
0x1000000
Задает указанный файл как исполняемый файл образа.

Атрибут SEC_IMAGE должен быть объединён со значением защиты страницы, например PAGE_READONLY. Однако это значение защиты страницы не влияет на представления исполняемого файла образа. Защита страниц для представлений исполняемого файла образа определяется самим исполняемым файлом.

Никакие другие атрибуты не являются допустимыми для SEC_IMAGE.

SEC_IMAGE_NO_EXECUTE
0x11000000
Указывает, что файл, который указывает параметр hFile , является исполняемым файлом образа, который не будет выполняться, а загруженный файл образа не будет выполняться принудительной проверки целостности. Кроме того, сопоставление представления объекта сопоставления файлов, созданного с помощью атрибута SEC_IMAGE_NO_EXECUTE , не будет вызывать обратные вызовы драйвера, зарегистрированные с помощью API ядра PsSetLoadImageNotifyRoutine .

Атрибут 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.

SEC_LARGE_PAGES
0x80000000
Позволяет использовать большие страницы при сопоставлении изображений или резервной копии из файла подкачки, но не при сопоставлении данных для обычных файлов. Обязательно укажите максимальный размер объекта сопоставления файлов как минимальный размер большой страницы, сообщаемый функцией GetLargePageMinimum , и включите привилегию SeLockMemoryPrivilege .
SEC_NOCACHE
0x10000000
Устанавливает для всех страниц значение noncachable.

Приложения не должны использовать этот флаг, за исключением случаев, когда явно требуется для устройства. Использование взаимосвязанных функций с памятью, сопоставленной с SEC_NOCACHE , может привести к EXCEPTION_ILLEGAL_INSTRUCTION исключению.

SEC_NOCACHE необходимо задать SEC_RESERVE или SEC_COMMIT .

SEC_RESERVE
0x4000000
Резервирует все страницы без выделения физического хранилища.

Зарезервированный диапазон страниц не может использоваться другими операциями выделения, пока диапазон страниц не будет освобожден.

Зарезервированные страницы можно определить при последующих вызовах функции VirtualAllocExNuma . Этот атрибут действителен, только если параметр hFileINVALID_HANDLE_VALUE ( то есть объект сопоставления файлов, поддерживаемый системным файлом подкачки).

SEC_WRITECOMBINE
0x40000000
Задает все страницы для объединения записей.

Приложения не должны использовать этот атрибут, за исключением случаев, когда это явно необходимо для устройства. Использование взаимосвязанных функций с памятью, сопоставленной с SEC_WRITECOMBINE , может привести к EXCEPTION_ILLEGAL_INSTRUCTION исключению.

SEC_WRITECOMBINE требуется задать атрибут SEC_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. Это происходит потому, что эти объекты используют одно и то же пространство имен.

Имя может иметь префикс "Global" или "Local" для явного создания объекта в глобальном пространстве имен или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Для создания объекта сопоставления файлов в глобальном пространстве имен требуется привилегия SeCreateGlobalPrivilege . Дополнительные сведения см. в разделе Пространства имен объектов ядра.

Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Первый пользователь для входа использует сеанс 0 (ноль), следующий пользователь для входа использует сеанс 1 (один) и т. д. Имена объектов ядра должны соответствовать рекомендациям, чтобы приложения могли поддерживать нескольких пользователей.

[in] nndPreferred

Узел NUMA, на котором должна находиться физическая память.

Значение Значение
NUMA_NO_PREFERRED_NODE
0xffffffff
Не рекомендуется использовать узел NUMA. Это то же самое, что вызов функции CreateFileMapping .

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение является дескриптором для объекта сопоставления файлов.

Если объект существует до вызова функции, функция возвращает дескриптор существующему объекту (с его текущим размером, а не указанным размером), а функция GetLastError возвращает ERROR_ALREADY_EXISTS.

Если функция завершается сбоем, возвращается значение NULL. Чтобы получить расширенные сведения об ошибке, вызовите функцию GetLastError .

Комментарии

После создания объекта сопоставления файлов размер файла не должен превышать размер объекта сопоставления файлов; Если это так, не все содержимое файла доступно для совместного использования.

Объект сопоставления файлов может совместно использоваться путем дублирования, наследования или по имени. Начальное содержимое страниц в объекте сопоставления файлов, поддерживаемом файлом подкачки, равно 0 (ноль).

Если приложение указывает размер объекта сопоставления файлов, который больше размера фактического именованного файла на диске и если защита страницы разрешает доступ на запись (то есть параметр flProtect указывает PAGE_READWRITE или PAGE_EXECUTE_READWRITE), файл на диске увеличивается в соответствии с указанным размером объекта сопоставления файлов. Если файл расширен, содержимое файла между старым и новым концами файла не гарантируется равным нулю; поведение определяется файловой системой.

Если невозможно увеличить размер файла, это приведет к сбою при создании объекта сопоставления файлов и функция GetLastError возвращает ERROR_DISK_FULL.

Дескриптор, возвращаемый функцией CreateFileMappingNuma , имеет полный доступ к новому объекту сопоставления файлов и может использоваться с любой функцией, требующей дескриптора для объекта сопоставления файлов. Объект сопоставления файлов можно совместно использовать путем создания процесса, обработки дублирования или по имени. Дополнительные сведения см. в разделе Функции DuplicateHandle и OpenFileMapping .

Создание объекта сопоставления файлов создает возможность сопоставления представления файла, но не сопоставляет представление. Функция MapViewOfFileExNuma сопоставляет представление файла с адресным пространством процесса.

За одним важным исключением, представления файлов, производные от одного объекта сопоставления файлов, являются согласованными или идентичными в определенное время. Если несколько процессов имеют дескриптор одного объекта сопоставления файлов, они видят согласованное представление данных при сопоставлении представления файла.

Исключение связано с удаленными файлами. Хотя функция CreateFileMappingNuma работает с удаленными файлами, она не поддерживает их согласованность. Например, если два компьютера сопоставляют файл как доступный для записи и изменяют одну и ту же страницу, каждый компьютер видит только собственные записи на страницу. При обновлении данных на диске страница не объединяется.

Сопоставленный файл и файл, к которому осуществляется доступ с помощью функций ввода-вывода (ReadFile и WriteFile), не обязательно являются согласованными.

Чтобы полностью закрыть объект сопоставления файлов, приложение должно отменить сопоставление всех сопоставленных представлений объекта сопоставления файлов путем вызова функции UnmapViewOfFile , а затем закрыть дескриптор объекта сопоставления файлов, вызвав функцию CloseHandle .

Эти функции можно вызывать в любом порядке. Вызов функции UnmapViewOfFile необходим, так как сопоставленные представления объекта сопоставления файлов поддерживают внутренние открытые дескрипторы для объекта, а объект сопоставления файлов не закрывается, пока не будут закрыты все открытые дескрипторы.

При изменении файла с помощью сопоставленного представления метка времени последнего изменения может не обновляться автоматически. При необходимости вызывающий объект должен использовать SetFileTime для установки метки времени.

Для создания объекта сопоставления файлов из сеанса, отличного от нулевого сеанса, требуется привилегия SeCreateGlobalPrivilege . Обратите внимание, что эта привилегия проверка ограничена созданием объектов сопоставления файлов и не применяется к открытию существующих. Например, если служба или система создает объект сопоставления файлов, любой процесс, выполняющийся в любом сеансе, может получить доступ к объекту сопоставления файлов при условии, что вызывающий объект имеет необходимые права доступа.

Используйте структурированную обработку исключений для защиты любого кода, который записывает или считывает данные из сопоставленного представления в памяти. Дополнительные сведения см. в статье Чтение и запись из представления файлов.

Чтобы получить сопоставление с разрешениями исполняемого файла, приложение должно вызвать функцию CreateFileMappingNuma с помощью PAGE_EXECUTE_READWRITE или PAGE_EXECUTE_READ а затем вызвать функцию MapViewOfFileExNuma с FILE_MAP_EXECUTE | FILE_MAP_WRITE помощью или FILE_MAP_EXECUTE | FILE_MAP_READ.

В Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология Поддерживается
Протокол SMB 3.0 Да
Прозрачная отработка отказа (TFO) SMB 3.0 Да
SMB 3.0 с масштабируемыми общими папками (SO) Да
Файловая система общего тома кластера (CSVFS) Да
Восстанавливаемая файловая система (ReFS) Да

Требования

Требование Значение
Минимальная версия клиента Windows Vista [только классические приложения]
Минимальная версия сервера Windows Server 2008 [только классические приложения]
Целевая платформа Windows
Header memoryapi.h (включая Windows.h, Memoryapi.h)
Библиотека onecore.lib
DLL Kernel32.dll

См. также

CloseHandle

CreateFileMapping

DuplicateHandle

Функции сопоставления файлов

MapViewOfFileExNuma

Поддержка NUMA

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAllocExNuma

WriteFile