Функция 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 . Это необязательно, но рекомендуется открывать файлы, которые планируется сопоставить, для монопольного доступа. Дополнительные сведения см. в разделе Безопасность файлов и права доступа.
Если hFileINVALID_HANDLE_VALUE, вызывающий процесс должен также указать размер объекта сопоставления файлов в параметрах dwMaximumSizeHigh и dwMaximumSizeLow . В этом сценарии CreateFileMapping создает объект сопоставления файлов указанного размера, который поддерживается системным файлом подкачки, а не файлом в файловой системе.
SecurityAttributes
Тип: _In_opt_ SECURITY_ATTRIBUTES*
Указатель на структуру SECURITY_ATTRIBUTES , которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Элемент lpSecurityDescriptor структуры SECURITY_ATTRIBUTES задает дескриптор безопасности для нового объекта сопоставления файлов.
Если lpAttributes имеет значение NULL, дескриптор не может быть унаследован, и объект сопоставления файлов получает дескриптор безопасности по умолчанию. Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для объекта сопоставления файлов поступают из основного маркера или маркера олицетворения создателя. Дополнительные сведения см. в разделе Безопасность сопоставления файлов и права доступа.
DesiredAccess
Тип: _In_ ULONG
Требуемая маска доступа для возвращенного дескриптора сопоставления файлов. Список прав доступа см. в разделе Безопасность сопоставления файлов и права доступа.
PageProtection
Тип: _In_ ULONG
Указывает защиту страницы для объекта сопоставления файлов. Все сопоставленные представления объекта должны быть совместимы с этой защитой.
Этот параметр может принимать одно из указанных ниже значений.
AllocationAttributes
Тип: _In_ ULONG
Для объекта сопоставления файлов можно указать один или несколько следующих атрибутов. См. также параметр PageProtection .
| Значение | Значение |
|---|---|
|
Если объект сопоставления файлов поддерживается файлом подкачки операционной системы (параметр hfile — INVALID_HANDLE_VALUE), указывает, что при сопоставлении представления файла с адресным пространством процесса весь диапазон страниц фиксируется, а не зарезервировано. Система должна иметь достаточно зафиксируемых страниц для хранения всего сопоставления. В противном случае createFileMapping завершается ошибкой .
Этот атрибут не влияет на объекты сопоставления файлов, которые поддерживаются исполняемыми файлами изображений или файлами данных (параметр hfile является дескриптором файла). SEC_COMMIT нельзя сочетать с SEC_RESERVE. Если атрибут не указан, предполагается SEC_COMMIT . |
|
Указывает, что файл, который указывает параметр hFile , является исполняемым файлом образа.
Атрибут SEC_IMAGE должен сочетаться со значением защиты страницы, таким как PAGE_READONLY. Однако это значение защиты страницы не влияет на представления исполняемого файла образа. Защита страниц для представлений исполняемого файла образа определяется самим исполняемым файлом. Никакие другие атрибуты не являются допустимыми для SEC_IMAGE. |
|
Указывает, что файл, который указывает параметр 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 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 с пакетом обновления 1 (SP1). Windows XP: Это значение не поддерживается. |
|
Задает все страницы, которые не кэшируются.
Приложения не должны использовать этот атрибут, за исключением случаев, когда это явно необходимо для устройства. Использование взаимосвязанных функций с памятью, сопоставленной с SEC_NOCACHE , может привести к EXCEPTION_ILLEGAL_INSTRUCTION исключению. SEC_NOCACHE требуется задать атрибут SEC_RESERVE или SEC_COMMIT . |
|
Если объект сопоставления файлов поддерживается файлом подкачки операционной системы (параметр hfileINVALID_HANDLE_VALUE), указывает, что при сопоставлении представления файла с адресным пространством процесса весь диапазон страниц резервируется для последующего использования процессом, а не фиксируется.
Зарезервированные страницы можно зафиксировать при последующих вызовах функции VirtualAlloc . После фиксации страницы они не могут быть освобождены или выведены из эксплуатации с помощью функции VirtualFree . Этот атрибут не влияет на объекты сопоставления файлов, которые поддерживаются исполняемыми файлами изображений или файлами данных (параметр hfile является дескриптором файла). SEC_RESERVE нельзя сочетать с SEC_COMMIT. |
|
Задает все страницы для объединения записей.
Приложения не должны использовать этот атрибут, за исключением случаев, когда это явно необходимо для устройства. Использование взаимосвязанных функций с памятью, сопоставленной с SEC_WRITECOMBINE , может привести к EXCEPTION_ILLEGAL_INSTRUCTION исключению. SEC_WRITECOMBINE требуется задать атрибут SEC_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. Это происходит потому, что эти объекты используют одно и то же пространство имен.
Имя может иметь префикс "Global" или "Local" для явного создания объекта в глобальном пространстве имен или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Для создания объекта сопоставления файлов в глобальном пространстве имен из сеанса, отличного от нулевого сеанса, требуется привилегия SeCreateGlobalPrivilege . Дополнительные сведения см. в разделе Пространства имен объектов ядра.
Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Первый пользователь для входа использует сеанс 0 (ноль), следующий пользователь для входа использует сеанс 1 (один) и т. д. Имена объектов ядра должны соответствовать рекомендациям, изложенным для служб терминалов, чтобы приложения могли поддерживать нескольких пользователей.
ExtendedParameters
Тип: _Inout_updates_opt_(ParameterCount) MEM_EXTENDED_PARAMETER*
Необязательный указатель на один или несколько расширенных параметров типа MEM_EXTENDED_PARAMETER. Каждое из этих значений расширенных параметров может иметь поле Typeлибо MemExtendedParameterAddressRequirements , либо MemExtendedParameterNumaNode. Если расширенный параметр MemExtendedParameterNumaNode не указан, поведение будет таким же, как и для функций VirtualAlloc/MapViewOfFile (то есть предпочтительный узел NUMA для физических страниц определяется на основе идеального процессора потока, который сначала обращается к памяти).
ParameterCount
В ULONG ParameterCount
Количество расширенных параметров, на которые указывает ExtendedParameters.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение является дескриптором для созданного объекта сопоставления файлов.
Если объект существует до вызова функции, функция возвращает дескриптор существующему объекту (с его текущим размером, а не указанным размером), а GetLastError возвращает ERROR_ALREADY_EXISTS.
Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Комментарии
См. примечания для CreateFileMapping.
Примеры
Пример см. в разделе Создание именованной общей памяти или Создание сопоставления файлов с использованием больших страниц.
Требования
| Минимальная версия клиента | Windows 10 сборки 20348 |
| Минимальная версия сервера | Windows 10 сборки 20348 |
| Целевая платформа | Windows |
| Header | memoryapi.h (включая Windows.h, Memoryapi.h) |
| Библиотека | onecore.lib |
| DLL | Kernel32.dll |