Функция CreateFileMappingW (memoryapi.h)
Создает или открывает именованный или неименованный объект сопоставления файлов для указанного файла.
Сведения об указании узла NUMA для физической памяти см. в разделе CreateFileMappingNuma.
Синтаксис
HANDLE CreateFileMappingW(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCWSTR lpName
);
Параметры
[in] hFile
Дескриптор файла, из которого создается объект сопоставления файлов.
Файл должен быть открыт с правами доступа, совместимыми с флагами защиты , указанными параметром flProtect. Это не обязательно, но рекомендуется, чтобы файлы, которые планируется сопоставить для эксклюзивного доступа. Дополнительные сведения см. в права доступа и безопасности файлов.
Если hFile INVALID_HANDLE_VALUE, вызов должен также указать размер объекта сопоставления файлов в dwMaximumSizeHigh и параметры dwMaximumSizeLow dwMaximumSizeLow. В этом сценарии CreateFileMapping создает объект сопоставления файлов указанного размера, который поддерживается системным файлом на страницы вместо файла в файловой системе.
[in, optional] lpFileMappingAttributes
Указатель на структуру SECURITY_ATTRIBUTES, которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Элемент
Если lpAttributesNULL, дескриптор не может наследоваться, а объект сопоставления файлов получает дескриптор безопасности по умолчанию. Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для объекта сопоставления файлов получены из первичного или олицетворения маркера создателя. Дополнительные сведения см. в "Безопасность и доступ к файлам".
[in] flProtect
Указывает защиту страницы объекта сопоставления файлов. Все сопоставленные представления объекта должны быть совместимы с этой защитой.
Этот параметр может быть одним из следующих значений.
Приложение может указать один или несколько следующих атрибутов для объекта сопоставления файлов, объединив их с одним из предыдущих значений защиты страниц.
| Ценность | Значение |
|---|---|
|
Если объект сопоставления файлов поддерживается файлом разбиения по страницам операционной системы (параметр hfileINVALID_HANDLE_VALUE), указывает, что при сопоставлении представления файла в адресное пространство процесса весь диапазон страниц фиксируется, а не зарезервирован. Система должна иметь достаточно зафиксируемых страниц для хранения всего сопоставления. В противном случае CreateFileMapping завершается ошибкой.
Этот атрибут не влияет на объекты сопоставления файлов, поддерживаемые исполняемыми файлами изображений или файлами данных (параметр hfile является дескриптором файла). SEC_COMMIT нельзя объединить с SEC_RESERVE. Если атрибут не указан, SEC_COMMIT предполагается. Однако SEC_COMMIT необходимо явно указать при объединении его с другим атрибутом SEC_, который требует его. |
|
Указывает, что файл, указывающий параметр 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. |
[in] dwMaximumSizeHigh
Высокий порядок DWORD максимального размера объекта сопоставления файлов.
[in] dwMaximumSizeLow
Низкий порядок DWORD максимального размера объекта сопоставления файлов.
Если этот параметр и dwMaximumSizeHigh равны 0 (ноль), максимальный размер объекта сопоставления файлов равен текущему размеру файла, который hFile.
Попытка сопоставить файл с длиной 0 (ноль) завершается ошибкой с кодом ошибки ERROR_FILE_INVALID. Приложения должны тестировать файлы с длиной 0 (ноль) и отклонять эти файлы.
[in, optional] lpName
Имя объекта сопоставления файлов.
Если этот параметр соответствует имени существующего объекта сопоставления, функция запрашивает доступ к объекту с защитой, которая flProtect указывает.
Если этот параметр null, объект сопоставления файлов создается без имени.
Если lpName соответствует имени существующего события, семафора, мьютекса, ожидающего таймера или объекта задания, функция завершается ошибкой, а функция getLastError возвращает ERROR_INVALID_HANDLE. Это происходит, так как эти объекты используют одно и то же пространство имен.
Имя может иметь префикс "Глобальный" или "Локальный", чтобы явно создать объект в глобальном или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Для создания объекта сопоставления файлов в глобальном пространстве имен из сеанса, отличного от нуля сеанса, требуется
Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Первый пользователь для входа использует сеанс 0 (ноль), следующий пользователь для входа использует сеанс 1 (один) и т. д. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать несколько пользователей.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение является дескриптором созданного объекта сопоставления файлов.
Если объект существует перед вызовом функции, функция возвращает дескриптор существующему объекту (с текущим размером, а не указанным размером), а GetLastError возвращает ERROR_ALREADY_EXISTS.
Если функция завершается ошибкой, возвращаемое значение равно NULL. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.
Замечания
После создания объекта сопоставления файлов размер файла не должен превышать размер объекта сопоставления файлов; Если это так, для общего доступа доступны не все содержимое файла.
Если приложение задает размер объекта сопоставления файлов, превышающего размер фактического именованного файла на диске, и если защита страницы разрешает доступ на запись (то есть параметр flProtect указывает PAGE_READWRITE или PAGE_EXECUTE_READWRITE), файл на диске увеличивается, чтобы соответствовать указанному размеру объекта сопоставления файлов. Если файл расширен, содержимое файла между старым концем файла и новым концем файла не гарантируется нулевой. Поведение определяется файловой системой. Если файл на диске нельзя увеличить, CreateFileMapping завершается ошибкой, и GetLastError возвращает ERROR_DISK_FULL.
Начальное содержимое страниц в объекте сопоставления файлов, поддерживаемом файлом подкачки операционной системы, равно 0 (ноль).
Дескриптор, который CreateFileMapping возвращает полный доступ к новому объекту сопоставления файлов и может использоваться с любой функцией, требующей дескриптора объекта сопоставления файлов.
Несколько процессов могут совместно использовать представление одного файла с помощью одного объекта сопоставления файлов или создания отдельных объектов сопоставления файлов, поддерживаемых одним и тем же файлом. Один объект сопоставления файлов можно совместно использовать несколькими процессами, наследуя дескриптор при создании процесса, дедупликации дескриптора или открытия объекта сопоставления файлов по имени. Дополнительные сведения см. вCreateProcess
Создание объекта сопоставления файлов фактически не сопоставляет представление с адресным пространством процесса. Функции MapViewOfFile и MapViewOfFileEx сопоставляют представление файла в адресное пространство процесса.
При одном важном исключении представления файлов, производные от любого объекта сопоставления файлов, поддерживаемого одним и тем же файлом, являются последовательными или идентичными в определенное время. Совместная обработка гарантируется для представлений в процессе и для представлений, сопоставленных различными процессами.
Исключение связано с удаленными файлами. Хотя CreateFileMapping работает с удаленными файлами, он не поддерживает их согласованность. Например, если два компьютера сопоставляют файл как доступный для записи, и оба изменяют одну и ту же страницу, каждый компьютер видит только собственные записи на страницу. Когда данные обновляются на диске, они не объединяются.
Сопоставленный файл и файл, к которому осуществляется доступ с помощью функций ввода-вывода (ReadFile и WriteFile) не обязательно согласованы.
Сопоставленные представления объекта сопоставления файлов поддерживают внутренние ссылки на объект, и объект сопоставления файлов не закрывается до тех пор, пока не будут выпущены все ссылки на него. Таким образом, чтобы полностью закрыть объект сопоставления файлов, приложение должно отменить сопоставление всех сопоставленных представлений объекта сопоставления файлов путем вызова UnmapViewOfFile и закрытия дескриптора объекта сопоставления файлов путем вызова CloseHandle. Эти функции можно вызывать в любом порядке.
При изменении файла с помощью сопоставленного представления метка времени последнего изменения может не обновляться автоматически. При необходимости вызывающий объект должен использовать SetFileTime, чтобы задать метку времени.
Для создания объекта сопоставления файлов в глобальном пространстве имен из сеанса, отличного от нуля сеанса, требуется
Windows XP: Требование, описанное в предыдущем абзаце, было введено с Windows Server 2003 и Windows XP с пакетом обновления 2 (SP2)
Используйте структурированную обработку исключений для защиты любого кода, записываемого в представление файла или считывающего их. Дополнительные сведения см. в чтения и записи изпредставления файлов.
Чтобы иметь сопоставление с разрешениями исполняемого файла, приложение должно вызывать CreateFileMapping с PAGE_EXECUTE_READWRITE или PAGE_EXECUTE_READ, а затем вызывать MapViewOfFile с FILE_MAP_EXECUTE | FILE_MAP_WRITE или FILE_MAP_EXECUTE | FILE_MAP_READ.
В Windows Server 2012 эта функция поддерживается следующими технологиями.
| Технологии | Поддержанный |
|---|---|
| Протокол SMB 3.0 | Да |
| Отработка отказа SMB 3.0 (TFO) | Да |
| SMB 3.0 с масштабируемыми общими папками (SO) | Да |
| Файловая система общего тома кластера (CSVFS) | Да |
| Отказоустойчивая файловая система (ReFS) | Да |
Примеры
Пример см. в статье создание именованной общей памяти или создание сопоставления файлов с помощью больших страниц.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows XP [только классические приложения] |
| минимальный поддерживаемый сервер | Windows Server 2003 [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | memoryapi.h (включая Windows.h, Memoryapi.h) |
| библиотеки |
onecore.lib |
| DLL | Kernel32.dll |
См. также
создание объекта сопоставления файлов
Функции сопоставления файлов