Функция CreateFileA (fileapi.h)

Статья
06/02/2023

Создает или открывает файл или устройство ввода-вывода. Наиболее часто используемые устройства ввода-вывода: файл, файловый поток, каталог, физический диск, том, буфер консоли, ленточный накопитель, ресурс связи, почтовый слопот и канал. Функция возвращает дескриптор, который можно использовать для доступа к файлу или устройству для различных типов операций ввода-вывода в зависимости от файла или устройства, а также указанных флагов и атрибутов.

Чтобы выполнить эту операцию как транзакцию, в результате которой создается дескриптор, который можно использовать для транзакционного ввода-вывода, используйте функцию CreateFileTransacted .

Синтаксис

HANDLE CreateFileA(
  [in]           LPCSTR                lpFileName,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwCreationDisposition,
  [in]           DWORD                 dwFlagsAndAttributes,
  [in, optional] HANDLE                hTemplateFile
);

Параметры

[in] lpFileName

Имя создаваемого или открываемого файла или устройства. В этом имени можно использовать косую черту (/) или обратную косую черту (\).

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов в ширину, добавьте к пути "\\?\". Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.

Совет

Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения MAX_PATH без добавления "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

Сведения о специальных именах устройств см. в разделе Определение имени устройства MS-DOS.

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

[in] dwDesiredAccess

Запрошенный доступ к файлу или устройству, который можно суммировать как чтение, запись или 0, чтобы указать ни то, ни другое).

Чаще всего используются значения GENERIC_READ, GENERIC_WRITE или оба (GENERIC_READ | GENERIC_WRITE). Дополнительные сведения см. в разделах Общие права доступа, Безопасность файлов и Права доступа, Константы прав доступа к файлам и ACCESS_MASK.

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

Невозможно запросить режим доступа, конфликтующий с режимом общего доступа, заданным параметром dwShareMode в открытом запросе, который уже имеет открытый дескриптор.

Дополнительные сведения см. в разделе Примечания этого раздела и в разделе Создание и открытие файлов.

[in] dwShareMode

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

Если этот параметр равен нулю и CreateFile завершается успешно, файл или устройство нельзя предоставить к совместному доступу, и их нельзя будет открыть снова, пока не будет закрыт дескриптор файла или устройства. Дополнительные сведения см. в разделе «Примечания».

Невозможно запросить режим общего доступа, конфликтующий с режимом доступа, указанным в существующем запросе с открытым дескриптором. CreateFile завершится ошибкой, а функция GetLastError вернет ERROR_SHARING_VIOLATION.

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

Примечание Параметры общего доступа для каждого открытого дескриптора остаются в силе, пока этот дескриптор не будет закрыт, независимо от контекста процесса.

Значение	Значение
0 0x00000000	Запрещает другим процессам открывать файл или устройство, если они запрашивают доступ к удалению, чтению или записи.
FILE_SHARE_DELETE 0x00000004	Позволяет последующим операциям открытия файла или устройства запрашивать доступ к удалению. В противном случае другие процессы не смогут открыть файл или устройство при запросе на удаление доступа. Если этот флаг не указан, но файл или устройство были открыты для доступа к удалению, функция завершается ошибкой. Примечание Доступ к удалению позволяет выполнять операции удаления и переименования.
FILE_SHARE_READ 0x00000001	Позволяет последующим операциям открытия файла или устройства запрашивать доступ на чтение. В противном случае другие процессы не смогут открыть файл или устройство, если они запрашивают доступ на чтение. Если этот флаг не указан, но файл или устройство были открыты для чтения, функция завершается ошибкой.
FILE_SHARE_WRITE 0x00000002	Позволяет последующим операциям открытия файла или устройства запрашивать доступ на запись. В противном случае другие процессы не смогут открыть файл или устройство, если они запрашивают доступ на запись. Если этот флаг не указан, но файл или устройство были открыты для доступа на запись или имеет сопоставление файлов с доступом на запись, функция завершается ошибкой.

[in, optional] lpSecurityAttributes

Указатель на структуру SECURITY_ATTRIBUTES , содержащую два отдельных, но связанных элемента данных: необязательный дескриптор безопасности и логическое значение, определяющее, может ли возвращаемый дескриптор наследоваться дочерними процессами.

Этот параметр может принимать значение NULL.

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

Элемент lpSecurityDescriptor структуры указывает SECURITY_DESCRIPTOR для файла или устройства. Если этот элемент имеет значение NULL, файлу или устройству, связанному с возвращенным дескриптором, назначается дескриптор безопасности по умолчанию.

CreateFile игнорирует член lpSecurityDescriptor при открытии существующего файла или устройства, но продолжает использовать элемент bInheritHandle .

Член структуры bInheritHandle указывает, можно ли наследовать возвращаемый дескриптор.

Дополнительные сведения см. в разделе «Примечания».

[in] dwCreationDisposition

Действие, выполняемое с файлом или устройством, которые существуют или не существуют.

Для устройств, отличных от файлов, этот параметр обычно имеет значение OPEN_EXISTING.

Дополнительные сведения см. в разделе «Примечания».

Этот параметр должен иметь одно из следующих значений, которые нельзя объединить:

Значение	Значение
CREATE_ALWAYS 2	Всегда создает новый файл. Если указанный файл существует и доступен для записи, функция усекает файл, выполняется успешно, а для кода последней ошибки задано значение ERROR_ALREADY_EXISTS (183). Если указанный файл не существует и является допустимым путем, создается новый файл, функция завершается успешно, а код последней ошибки равен нулю. Дополнительные сведения см. в разделе Примечания этой статьи.
CREATE_NEW 1	Создает новый файл, только если он еще не существует. Если указанный файл существует, функция завершается сбоем, а для кода последней ошибки задано значение ERROR_FILE_EXISTS (80). Если указанный файл не существует и является допустимым путем к расположению, доступному для записи, создается новый файл.
OPEN_ALWAYS 4	Всегда открывает файл. Если указанный файл существует, функция выполняется успешно, а для кода последней ошибки задано значение ERROR_ALREADY_EXISTS (183). Если указанный файл не существует и является допустимым путем к расположению, доступному для записи, функция создает файл, а код последней ошибки равен нулю.
OPEN_EXISTING 3	Открывает файл или устройство, только если они существуют. Если указанный файл или устройство не существует, функция завершается сбоем, а для кода последней ошибки задано значение ERROR_FILE_NOT_FOUND (2). Дополнительные сведения об устройствах см. в разделе Примечания.
TRUNCATE_EXISTING 5	Открывает файл и усекает его таким образом, чтобы его размер был равен нулю байтов, только если он существует. Если указанный файл не существует, функция завершается сбоем, а код последней ошибки имеет значение ERROR_FILE_NOT_FOUND (2). Вызывающий процесс должен открыть файл с битом GENERIC_WRITE , заданным как часть параметра dwDesiredAccess .

[in] dwFlagsAndAttributes

Атрибуты и флаги файла или устройства FILE_ATTRIBUTE_NORMAL являются наиболее распространенным значением по умолчанию для файлов.

Этот параметр может включать любое сочетание доступных атрибутов файла (FILE_ATTRIBUTE_*). Все остальные атрибуты файла переопределяют FILE_ATTRIBUTE_NORMAL.

Этот параметр также может содержать сочетания флагов (FILE_FLAG_*) для управления поведением кэширования файлов или устройств, режимов доступа и других специальных флагов. Они объединяются со значениями FILE_ATTRIBUTE_* .

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

Примечание Когда CreateFile открывает существующий файл, он обычно объединяет флаги файла с атрибутами существующего файла и игнорирует все атрибуты файла, предоставленные в составе dwFlagsAndAttributes. Особые случаи описаны в разделе Создание и открытие файлов.

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

Дополнительные сведения о расширенном доступе к атрибутам файлов см. в разделе SetFileAttributes. Полный список всех атрибутов файла с их значениями и описаниями см. в разделе File Attribute Constants.

attribute	Значение
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	Файл должен быть заархивирован. Приложения используют этот атрибут, чтобы отмечать файлы для резервного копирования или удаления.
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	Файл или каталог зашифрован. Для файла это означает, что все данные в файле зашифрованы. Для каталога это означает, что шифрование используется по умолчанию для вновь созданных файлов и подкаталогов. Дополнительные сведения см. в разделе Шифрование файлов. Этот флаг не действует, если также указан FILE_ATTRIBUTE_SYSTEM . Этот флаг не поддерживается в выпусках Windows Home, Home Premium, Starter или ARM.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	Файл скрыт. Не включайте его в обычный список каталогов.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	В файле не заданы другие атрибуты. При использовании этого атрибута не допускается использование других атрибутов.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	Данные файла доступны не сразу. Этот атрибут указывает, что данные файлов физически перемещаются в автономное хранилище. Этот атрибут используется удаленным хранилищем, программным обеспечением для управления иерархическим хранилищем. Приложения не должны произвольно изменять этот атрибут.
FILE_ATTRIBUTE_READONLY 1 (0x1)	Файл доступен только для чтения. Приложения могут считывать файл, но не могут записывать или удалять его.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	Файл является частью операционной системы или используется исключительно в ней.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	Файл используется для временного хранения. Дополнительные сведения см. в разделе Поведение кэширования этой статьи.

Flag	Значение
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	Файл открывается или создается для резервного копирования или восстановления. Система гарантирует, что вызывающий процесс переопределяет проверки безопасности файлов, если у процесса есть SE_BACKUP_NAME и SE_RESTORE_NAME привилегии. Дополнительные сведения см. в разделе Изменение привилегий в токене. Этот флаг необходимо задать, чтобы получить дескриптор каталога. Дескриптор каталога можно передать некоторым функциям вместо дескриптора файла. Дополнительные сведения см. в разделе «Примечания».
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	Файл будет удален сразу после закрытия всех его дескрипторов, включая указанный дескриптор и другие открытые или дублирующиеся дескрипторы. Если для файла имеются открытые дескрипторы, вызов завершается ошибкой, если только они не были открыты в режиме общего доступа FILE_SHARE_DELETE . Последующие запросы на открытие файла завершатся сбоем, если только не указан режим совместного использования FILE_SHARE_DELETE.
FILE_FLAG_NO_BUFFERING 0x20000000	Файл или устройство открывается без системного кэширования для операций чтения и записи данных. Этот флаг не влияет на кэширование жесткого диска или сопоставленные файлы в памяти. Существуют строгие требования к успешной работе с файлами, открытыми с помощью CreateFile с помощью флага FILE_FLAG_NO_BUFFERING . Дополнительные сведения см. в разделе Буферизация файлов.
FILE_FLAG_OPEN_NO_RECALL 0x00100000	Данные файла запрашивается, но они должны по-прежнему находиться в удаленном хранилище. Его не следует переносить обратно в локальное хранилище. Этот флаг предназначен для использования системами удаленного хранения.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	Обычная обработка точек повторного обработки не выполняется; CreateFile попытается открыть точку повторной аналитики. При открытии файла возвращается дескриптор файла, независимо от того, работает ли фильтр, управляющий точкой повторного определения. Этот флаг нельзя использовать с флагом CREATE_ALWAYS . Если файл не является точкой повторного извлечения, этот флаг игнорируется. Дополнительные сведения см. в разделе «Примечания».
FILE_FLAG_OVERLAPPED 0x40000000	Файл или устройство открывается или создается для асинхронного ввода-вывода. После завершения последующих операций ввода-вывода для этого дескриптора событие, указанное в структуре OVERLAPPED , будет установлено в состояние сигнала. Если этот флаг указан, файл можно использовать для одновременных операций чтения и записи. Если этот флаг не указан, операции ввода-вывода сериализуются, даже если вызовы функций чтения и записи указывают структуру OVERLAPPED . Сведения об использовании дескриптора файла, созданного с помощью этого флага, см. в разделе Синхронные и асинхронные дескрипторы ввода-вывода этой статьи.
FILE_FLAG_POSIX_SEMANTICS 0x01000000	Доступ будет осуществляться в соответствии с правилами POSIX. Это включает в себя разрешение нескольких файлов с именами, отличающимися только в случае, для файловой системы, поддерживающей такое именование. Будьте внимательны при использовании этого параметра, так как файлы, созданные с этим флагом, могут быть недоступны приложениям, написанным для MS-DOS или 16-разрядной версии Windows.
FILE_FLAG_RANDOM_ACCESS 0x10000000	Доступ должен быть случайным. Система может использовать это в качестве указания для оптимизации кэширования файлов. Этот флаг не действует, если файловая система не поддерживает кэшированные ввод-вывод и FILE_FLAG_NO_BUFFERING. Дополнительные сведения см. в разделе Поведение кэширования этой статьи.
FILE_FLAG_SESSION_AWARE 0x00800000	Файл или устройство открывается с пониманием сеанса. Если этот флаг не указан, то устройства для сеанса (например, устройства, использующие перенаправление USB RemoteFX) не могут быть открыты процессами, выполняемыми в сеансе 0. Этот флаг не действует для вызывающих абонентов, не в сеансе 0. Этот флаг поддерживается только в серверных выпусках Windows. Windows Server 2008 R2 и Windows Server 2008: Этот флаг не поддерживается до Windows Server 2012.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	Доступ должен быть последовательным от начала до конца. Система может использовать это в качестве указания для оптимизации кэширования файлов. Этот флаг не следует использовать, если будет использоваться режим чтения с задней части (то есть обратные проверки). Этот флаг не действует, если файловая система не поддерживает кэшированные ввод-вывод и FILE_FLAG_NO_BUFFERING. Дополнительные сведения см. в разделе Поведение кэширования этой статьи.
FILE_FLAG_WRITE_THROUGH 0x80000000	Операции записи не будут проходить через промежуточный кэш, они будут отправляться непосредственно на диск. Дополнительные сведения см. в разделе Поведение кэширования этой статьи.

Параметр dwFlagsAndAttributes также может указывать сведения о SQOS. Дополнительные сведения см. в разделе Уровни олицетворения. Если вызывающее приложение задает флаг SECURITY_SQOS_PRESENT в составе dwFlagsAndAttributes, оно также может содержать одно или несколько из следующих значений.

Флаг безопасности	Значение
SECURITY_ANONYMOUS	Олицетворяет клиента на уровне анонимного олицетворения.
SECURITY_CONTEXT_TRACKING	Режим отслеживания безопасности является динамическим. Если этот флаг не указан, режим отслеживания безопасности является статическим.
SECURITY_DELEGATION	Олицетворяет клиента на уровне олицетворения делегирования.
SECURITY_EFFECTIVE_ONLY	Серверу доступны только включенные аспекты контекста безопасности клиента. Если этот флаг не указан, будут доступны все аспекты контекста безопасности клиента. Это позволяет клиенту ограничить группы и привилегии, которые сервер может использовать при олицетворении клиента.
SECURITY_IDENTIFICATION	Олицетворяет клиента на уровне олицетворения идентификации.
SECURITY_IMPERSONATION	Олицетворение клиента на уровне олицетворения. Это поведение по умолчанию, если другие флаги не указаны вместе с флагом SECURITY_SQOS_PRESENT .

[in, optional] hTemplateFile

Допустимый дескриптор файла шаблона с правом доступа GENERIC_READ . Файл шаблона предоставляет атрибуты файла и расширенные атрибуты для создаваемого файла.

Этот параметр может принимать значение NULL.

При открытии существующего файла CreateFile игнорирует этот параметр.

При открытии нового зашифрованного файла файл наследует список управления доступом по усмотрению из родительского каталога. Дополнительные сведения см. в разделе Шифрование файлов.

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

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

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

Файл CreateFile изначально был разработан специально для взаимодействия с файлами, но с тех пор был расширен и расширен для включения большинства других типов устройств ввода-вывода и механизмов, доступных разработчикам Windows. В этом разделе рассматриваются различные проблемы, с которыми разработчики могут столкнуться при использовании CreateFile в разных контекстах и с разными типами ввода-вывода. Текст пытается использовать файл слов только при ссылке на данные, хранящиеся в фактическом файле в файловой системе. Однако некоторые варианты использования файлов в целом относятся к объекту ввода-вывода, который поддерживает файлоподобные механизмы. Такое свободное использование файла терминов особенно распространено в постоянных именах и именах параметров по ранее упомянутым историческим причинам.

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

Windows Server 2003 и Windows XP: Нарушение общего доступа возникает при попытке открыть файл или каталог для удаления на удаленном компьютере, если значение параметра dwDesiredAccess равно флагу доступа DELETE (0x00010000) ИЛИ с любым другим флагом доступа, а удаленный файл или каталог не были открыты с FILE_SHARE_DELETE. Чтобы избежать нарушения общего доступа в этом сценарии, откройте удаленный файл или каталог только с правом доступа DELETE или вызовите Метод DeleteFile , не открывая файл или каталог для удаления.

Некоторые файловые системы, такие как файловая система NTFS, поддерживают сжатие или шифрование для отдельных файлов и каталогов. На томах с подключенной файловой системой с этой поддержкой новый файл наследует атрибуты сжатия и шифрования своего каталога.

CreateFile нельзя использовать для управления сжатием, распаковкой или расшифровкой в файле или каталоге. Дополнительные сведения см. в разделах Создание и открытие файлов, Сжатие и распаковка файлов и Шифрование файлов.

Windows Server 2003 и Windows XP: Для обеспечения обратной совместимости CreateFile не применяет правила наследования при указании дескриптора безопасности в lpSecurityAttributes. Для поддержки наследования функции, которые позже запрашивают дескриптор безопасности этого файла, могут эвристически определять и сообщать о действии наследования. Дополнительные сведения см. в статье Автоматическое распространение наследуемых ACE.

Как упоминалось ранее, если параметр lpSecurityAttributes имеет значение NULL, дескриптор, возвращаемый CreateFile, не может быть унаследован никакими дочерними процессами, которые может создать приложение. Также применяются следующие сведения об этом параметре:

Если переменная-член bInheritHandle не имеет значения FALSE, то дескриптор может быть унаследован. Поэтому очень важно правильно инициализировать этот элемент структуры со значением FALSE , если не предполагается, что дескриптор наследуется.
Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для файла или каталога наследуются от родительского каталога.
Целевая файловая система должна поддерживать безопасность файлов и каталогов, чтобы член lpSecurityDescriptor влиял на них, что можно определить с помощью GetVolumeInformation.

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

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

Обратите внимание, что createFile с заменой при выполнении с файлом, в котором уже есть открытый альтернативный поток данных, завершится ошибкой.

Поведение символьных ссылок

Если вызов этой функции создает файл, поведение не изменяется. Кроме того, учитывайте следующие сведения о FILE_FLAG_OPEN_REPARSE_POINT:

Если указан FILE_FLAG_OPEN_REPARSE_POINT :
- Если существующий файл открыт и является символьной ссылкой, возвращенный дескриптор является дескриптором символьной ссылки.
- Если указаны TRUNCATE_EXISTING или FILE_FLAG_DELETE_ON_CLOSE , затронутый файл является символьной ссылкой.
Если FILE_FLAG_OPEN_REPARSE_POINT не указан:
- Если существующий файл открыт и является символьной ссылкой, возвращенный дескриптор является дескриптором целевого объекта.
- Если указаны CREATE_ALWAYS, TRUNCATE_EXISTING или FILE_FLAG_DELETE_ON_CLOSE , затронутый файл является целевым объектом.

Поведение кэширования

Некоторые из возможных значений параметра dwFlagsAndAttributes используются CreateFile для управления или влияния на то, как данные, связанные с дескриптором, кэшируются системой. К ним относятся:

FILE_FLAG_NO_BUFFERING
FILE_FLAG_RANDOM_ACCESS
FILE_FLAG_SEQUENTIAL_SCAN
FILE_FLAG_WRITE_THROUGH
FILE_ATTRIBUTE_TEMPORARY

Если ни один из этих флагов не указан, система использует схему кэширования общего назначения по умолчанию. В противном случае системное кэширование работает так, как указано для каждого флага.

Некоторые из этих флагов не следует объединять. Например, объединение FILE_FLAG_RANDOM_ACCESS с FILE_FLAG_SEQUENTIAL_SCAN является саморазумным.

Указание флага FILE_FLAG_SEQUENTIAL_SCAN может повысить производительность приложений, которые считывают большие файлы с помощью последовательного доступа. Повышение производительности может быть еще более заметным для приложений, которые считывают большие файлы в основном последовательно, но иногда пропускают вперед через небольшие диапазоны байтов. Если приложение перемещает указатель файла для произвольного доступа, оптимальная производительность кэширования, скорее всего, не будет. Однако правильная операция по-прежнему гарантируется.

Флаги FILE_FLAG_WRITE_THROUGH и FILE_FLAG_NO_BUFFERING являются независимыми и могут быть объединены.

Если используется FILE_FLAG_WRITE_THROUGH , но FILE_FLAG_NO_BUFFERING также не указан, поэтому системное кэширование действует, данные записываются в системный кэш, но сбрасываются на диск без задержки.

Если указаны FILE_FLAG_WRITE_THROUGH и FILE_FLAG_NO_BUFFERING , чтобы системное кэширование не действовало, данные немедленно сбрасываются на диск, не проходя через системный кэш Windows. Операционная система также запрашивает запись локального аппаратного кэша жесткого диска на постоянный носитель.

Примечание Эта возможность поддерживается не всем оборудованием жестких дисков.

Правильное использование флага FILE_FLAG_NO_BUFFERING требует особых рекомендаций по приложениям. Дополнительные сведения см. в разделе Буферизация файлов.

Запрос на запись через FILE_FLAG_WRITE_THROUGH также приводит к тому, что NTFS очищает любые изменения метаданных, такие как обновление метки времени или операция переименования, которые возникают в результате обработки запроса. По этой причине флаг FILE_FLAG_WRITE_THROUGH часто используется вместе с флагом FILE_FLAG_NO_BUFFERING в качестве замены для вызова функции FlushFileBuffers после каждой записи, что может привести к ненужным ограничениям производительности. Использование этих флагов вместе позволяет избежать этих штрафов. Общие сведения о кэшировании файлов и метаданных см. в разделе Кэширование файлов.

При сочетании FILE_FLAG_NO_BUFFERING с FILE_FLAG_OVERLAPPED флаги обеспечивают максимальную асинхронную производительность, так как операции ввода-вывода не зависят от синхронных операций диспетчера памяти. Однако некоторые операции ввода-вывода занимают больше времени, так как данные не хранятся в кэше. Кроме того, метаданные файла могут по-прежнему кэшироваться (например, при создании пустого файла). Чтобы обеспечить очистку метаданных на диск, используйте функцию FlushFileBuffers .

Указание атрибута FILE_ATTRIBUTE_TEMPORARY приводит к тому, что файловые системы не будут записывать данные обратно в массовое хранилище, если доступно достаточно памяти кэша, так как приложение удаляет временный файл после закрытия дескриптора. В этом случае система может полностью избежать записи данных. Хотя он напрямую не управляет кэшированием данных так же, как упомянутые ранее флаги, атрибут FILE_ATTRIBUTE_TEMPORARY указывает системе хранить как можно больше данных в системном кэше без записи и, следовательно, может быть проблемой для некоторых приложений.

Файлы

Если вы переименовываете или удаляете файл, а затем восстанавливаете его вскоре после этого, система ищет в кэше сведения о файле для восстановления. Кэшированные сведения включают пару коротких и длинных имен и время создания.

При вызове CreateFile для файла, ожидающего удаления в результате предыдущего вызова DeleteFile, функция завершается ошибкой. Операционная система задерживает удаление файла, пока не будут закрыты все дескрипторы файла. GetLastError возвращает ERROR_ACCESS_DENIED.

Параметр dwDesiredAccess может быть равен нулю, что позволяет приложению запрашивать атрибуты файла без доступа к файлу, если приложение выполняется с соответствующими параметрами безопасности. Это полезно для проверки существования файла, не открывая его для доступа на чтение и (или) запись, а также для получения другой статистики о файле или каталоге. См. статьи Получение и настройка сведений о файле и GetFileInformationByHandle.

Если указаны CREATE_ALWAYS и FILE_ATTRIBUTE_NORMAL , createFile завершается ошибкой и задает последнюю ошибку ERROR_ACCESS_DENIED, если файл существует и имеет атрибут FILE_ATTRIBUTE_HIDDEN или FILE_ATTRIBUTE_SYSTEM . Чтобы избежать ошибки, укажите те же атрибуты, что и существующий файл.

Когда приложение создает файл по сети, лучше использовать GENERIC_READ | GENERIC_WRITE для dwDesiredAccess , чем использовать GENERIC_WRITE в одиночку. Результирующий код выполняется быстрее, так как перенаправитель может использовать диспетчер кэша и отправлять меньше SMB с большим объемом данных. Это сочетание также позволяет избежать проблемы, из-за которой запись в файл по сети иногда может возвращать ERROR_ACCESS_DENIED.

Дополнительные сведения см. в разделе Создание и открытие файлов.

Синхронные и асинхронные дескрипторы ввода-вывода

CreateFile позволяет создать дескриптор файла или устройства, который является синхронным или асинхронным. Синхронный дескриптор ведет себя таким образом, что вызовы функции ввода-вывода, использующие этот дескриптор, блокируются до их завершения, а асинхронный дескриптор файла позволяет системе немедленно возвращать данные из вызовов функции ввода-вывода независимо от того, завершена ли операция ввода-вывода или нет. Как было сказано ранее, это синхронное и асинхронное поведение определяется указанием FILE_FLAG_OVERLAPPED в параметре dwFlagsAndAttributes . Существует несколько сложностей и потенциальных ошибок при использовании асинхронных операций ввода-вывода; Дополнительные сведения см. в разделе Синхронный и асинхронный ввод-вывод.

Потоки файлов

В файловых системах NTFS можно использовать CreateFile для создания отдельных потоков в файле. Дополнительные сведения см. в разделе Файловые потоки.

Каталоги

Приложение не может создать каталог с помощью CreateFile, поэтому для dwCreationDisposition в этом случае допустимо только значение OPEN_EXISTING. Чтобы создать каталог, приложение должно вызвать CreateDirectory или CreateDirectoryEx.

Чтобы открыть каталог с помощью CreateFile, укажите флаг FILE_FLAG_BACKUP_SEMANTICS в составе dwFlagsAndAttributes. Соответствующие проверки безопасности по-прежнему применяются, если этот флаг используется без SE_BACKUP_NAME и SE_RESTORE_NAME привилегий.

При использовании CreateFile для открытия каталога во время дефрагментации тома файловой системы FAT или FAT32 не указывайте право доступа MAXIMUM_ALLOWED . В этом случае доступ к каталогу будет запрещен. Вместо этого укажите право доступа GENERIC_READ .

Дополнительные сведения см. в разделе Об управлении каталогами.

Физические диски и тома

Прямой доступ к диску или тому ограничен.

Windows Server 2003 и Windows XP: Прямой доступ к диску или тому таким образом не ограничен.

Функцию CreateFile можно использовать для открытия физического диска или тома, который возвращает дескриптор устройства хранения данных с прямым доступом (DASD), который можно использовать с функцией DeviceIoControl . Это позволяет получить доступ к диску или тому напрямую, например к таким метаданным диска, как таблица секций. Однако такой тип доступа также подвергает диск или том потенциальной потере данных, так как неправильная запись на диск с помощью этого механизма может сделать его содержимое недоступным для операционной системы. Чтобы обеспечить целостность данных, ознакомьтесь с DeviceIoControl и тем, как другие API работают иначе с дескриптором прямого доступа, а не с дескриптором файловой системы.

Для успешного выполнения такого вызова необходимо выполнить следующие требования:

Вызывающий объект должен иметь права администратора. Дополнительные сведения см. в разделе Выполнение с особыми привилегиями.
Параметр dwCreationDisposition должен иметь флаг OPEN_EXISTING .
При открытии тома или дискеты параметр dwShareMode должен иметь флаг FILE_SHARE_WRITE .

Примечание Параметр dwDesiredAccess может быть равен нулю, что позволяет приложению запрашивать атрибуты устройства без доступа к устройству. Это полезно для приложения, чтобы определить размер дисковода гибких дисков и поддерживаемые им форматы, например, без необходимости использовать гибкий диск на диске. Его также можно использовать для чтения статистики без разрешения на чтение и запись данных более высокого уровня.

При открытии физического диска x:строка lpFileName должна иметь следующий вид: \\.\PhysicalDriveX. Номера жестких дисков начинаются с нуля. В следующей таблице приведены некоторые примеры физических строк диска.

Строка	Значение
"\\.\PhysicalDrive0"	Открывает первый физический диск.
"\\.\PhysicalDrive2"	Открывает третий физический диск.

Чтобы получить идентификатор физического диска для тома, откройте дескриптор тома и вызовите функцию DeviceIoControl с IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. Этот управляющий код возвращает номер диска и смещение для каждого из экстентов тома; том может охватывать несколько физических дисков.

Пример открытия физического диска см. в разделе Вызов DeviceIoControl.

При открытии тома или съемного носителя (например, дисковод гибких дисков или флэш-памяти) строка lpFileName должна иметь следующий вид: "\.\X:". Не используйте обратную косую черту (\), которая указывает корневой каталог диска. В следующей таблице приведены примеры строк диска.

Строка	Значение
"\\.\A:"	Открывает гибкий диск A.
"\\.\C:"	Открывает том C:.
"\\.\C:\"	Открывает файловую систему тома C:.

Вы также можете открыть том, ссылаясь на его имя тома. Дополнительные сведения см. в разделе Именование тома.

Том содержит одну или несколько подключенных файловых систем. Дескриптор тома можно открывать как некэшированные по усмотрению конкретной файловой системы, даже если параметр без кэширования не указан в Файле CreateFile. Следует предположить, что все файловые системы Майкрософт открытые тома обрабатываются как некэшированные. Ограничения на некэшированные операции ввода-вывода для файлов также применяются к томам.

Файловая система может требовать выравнивания буфера, даже если данные не кэшированы. Однако если при открытии тома указан параметр без кэширования, выравнивание буфера применяется независимо от файловой системы тома. Во всех файловых системах рекомендуется открывать дескриптор тома как некэшированные и следовать ограничениям ввода-вывода без кэширования.

Примечание Для чтения или записи в последние несколько секторов тома необходимо вызвать DeviceIoControl и указать FSCTL_ALLOW_EXTENDED_DASD_IO. Это сигнализирует драйверу файловой системы не выполнять никаких проверок границ ввода-вывода при вызовах чтения или записи секций. Вместо этого проверки границ выполняются драйвером устройства.

Устройство changer

Коды элементов управления IOCTL_CHANGER_* для DeviceIoControl принимают дескриптор устройства. Чтобы открыть устройство, используйте имя файла следующей формы: \\.\Changerx, где x — это число, указывающее, какое устройство открыть, начиная с нуля. Чтобы открыть ноль устройства changer в приложении, написанном на языке C или C++, используйте следующее имя файла: "\\.\Changer0".

Ленточные накопители

Вы можете открыть ленточные накопители с именем файла следующей формы: \\.\TAPEx, где x — это число, указывающее, какой диск следует открыть, начиная с нуля. Чтобы открыть нуль ленточный накопитель в приложении, написанном на языке C или C++, используйте следующее имя файла: "\.\TAPE0".

Дополнительные сведения см. в разделе Резервное копирование.

Информационные ресурсы

Функция CreateFile может создать дескриптор для ресурса связи, например последовательного порта COM1. Для ресурсов связи параметр dwCreationDisposition должен быть OPEN_EXISTING, параметр dwShareMode должен быть равен нулю (монопольный доступ), а параметр hTemplateFile должен иметь значение NULL. Можно указать доступ для чтения, записи или чтения и записи, а также открыть дескриптор для перекрывающихся операций ввода-вывода.

Чтобы указать номер COM-порта больше 9, используйте следующий синтаксис: \\.\COM10. Этот синтаксис работает для всех номеров портов и оборудования, что позволяет указывать номера COM-портов.

Дополнительные сведения о коммуникациях см. в разделе Коммуникации.

Консолей

Функция CreateFile может создать дескриптор для ввода данных консоли (CONIN$). Если процесс имеет открытый дескриптор в результате наследования или дублирования, он также может создать дескриптор для активного буфера экрана (CONOUT$). Вызывающий процесс должен быть присоединен к наследуемой консоли или консоли, выделенной функцией AllocConsole . Для дескрипторов консоли задайте параметры CreateFile следующим образом.

Параметры	Значение
lpFileName	Используйте значение CONIN$, чтобы указать входные данные консоли. Используйте значение CONOUT$, чтобы указать выходные данные консоли. CONIN$ получает дескриптор входного буфера консоли, даже если функция SetStdHandle перенаправляет стандартный дескриптор ввода. Чтобы получить стандартный дескриптор ввода, используйте функцию GetStdHandle . CONOUT$ получает дескриптор активного буфера экрана, даже если SetStdHandle перенаправляет стандартный дескриптор вывода. Чтобы получить стандартный дескриптор вывода, используйте GetStdHandle.
dwDesiredAccess	`GENERIC_READ \| GENERIC_WRITE` предпочтительнее, но любой из них может ограничить доступ.
dwShareMode	При открытии CONIN$укажите FILE_SHARE_READ. При открытии CONOUT$укажите FILE_SHARE_WRITE. Если вызывающий процесс наследует консоль или дочерний процесс должен иметь доступ к консоли, этот параметр должен иметь значение `FILE_SHARE_READ \| FILE_SHARE_WRITE`.
lpSecurityAttributes	Если вы хотите, чтобы консоль была унаследована, член bInheritHandle структуры SECURITY_ATTRIBUTES должен иметь значение TRUE.
dwCreationDisposition	При открытии консоли с помощью CreateFile следует указать OPEN_EXISTING.
dwFlagsAndAttributes	Не обрабатывается.
hTemplateFile	Не обрабатывается.

В следующей таблице показаны различные параметры dwDesiredAccess и lpFileName.

lpFileName	dwDesiredAccess	Результат
"CON"	GENERIC_READ	Открывает консоль для ввода данных.
"CON"	GENERIC_WRITE	Открывает консоль для выходных данных.
"CON"	`GENERIC_READ \| GENERIC_WRITE`	Вызывает сбой CreateFile ; GetLastError возвращает ERROR_FILE_NOT_FOUND.

Mailslots

Если CreateFile открывает клиентский конец почтового объекта, функция возвращает INVALID_HANDLE_VALUE , если клиент mailslot пытается открыть локальный почтовый слоот, прежде чем сервер mailslot создаст его с помощью функции CreateMailSlot .

Дополнительные сведения см. в разделе Mailslots.

Трубы

Если CreateFile открывает клиентский конец именованного канала, функция использует любой экземпляр именованного канала, который находится в состоянии прослушивания. Процесс открытия может дублировать дескриптор столько раз, сколько потребуется, но после его открытия экземпляр именованного канала не может быть открыт другим клиентом. Доступ, указанный при открытии канала, должен быть совместим с доступом, указанным в параметре dwOpenMode функции CreateNamedPipe .

Если функция CreateNamedPipe не была успешно вызвана на сервере до этой операции, канал не будет существовать, а CreateFile завершится сбоем с ERROR_FILE_NOT_FOUND.

Если имеется хотя бы один активный экземпляр канала, но на сервере отсутствуют доступные каналы прослушивания. Это означает, что все экземпляры канала подключены в данный момент, createFile завершается сбоем с ERROR_PIPE_BUSY.

Дополнительные сведения см. в разделе Каналы.

Примеры

Примеры операций с файлами приведены в следующих разделах:

Физические устройства ввода-вывода демонстрируются в следующих разделах:

Пример использования именованных каналов находится в разделе Клиент именованного канала.

Работа с почтовым слоем показана в разделе Запись в mailslot.

Фрагмент кода резервной копии на ленте можно найти в статье Создание приложения резервного копирования.

Примечание

Заголовок fileapi.h определяет CreateFile как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll