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

Статья
06/02/2023

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

Чтобы выполнить эту операцию как транзакцию, которая приводит к дескриптору, который может использоваться для транзакций ввода-вывода, используйте функцию 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_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)	Файл используется для временного хранилища. Дополнительные сведения см. в разделе "Поведение кэширования" этой статьи.

Флаг	Значение
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 dwDesiredAccess является флагом доступа DELETE (0x00010000) OR'ed с любым другим флагом доступа, и удаленный файл или каталог не был открыт с FILE_SHARE_DELETE. Чтобы избежать нарушения общего доступа в этом сценарии, откройте удаленный файл или каталог с помощью DELETE доступ только или вызовите DeleteFile без первого открытия файла или каталога для удаления.

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

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

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

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

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

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

Технологии	Поддержанный
Протокол SMB 3.0	Да
Отработка отказа SMB 3.0 (TFO)	Просмотр примечаний
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. Результирующий код быстрее, так как перенаправитель может использовать диспетчер кэша и отправлять меньше SMOB-объектов с большим количеством данных. Это сочетание также позволяет избежать проблемы, при которой запись в файл в сети может иногда возвращать ERROR_ACCESS_DENIED.

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

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

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

файловых потоков

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

Каталоги

Приложение не может создать каталог с помощью CreateFile, поэтому только значение OPEN_EXISTING допустимо для dwCreationDisposition для этого варианта использования. Чтобы создать каталог, приложение должно вызвать 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.
При открытии тома или диска floppy параметр dwShareMode должен иметь флаг FILE_SHARE_WRITE.

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

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

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

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

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

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

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

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

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

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

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

устройство changer

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

ленточные диски

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

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

ресурсы связи

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

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

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

консоли

Функция createFile 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	Чтобы открыть консоль, необходимо указать OPEN_EXISTING при использовании CreateFile.
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 CreateMailSlot.

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

каналы

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

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

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

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

Примеры

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

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

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

Работа с mailslot показана в записи в mailslot.

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	fileapi.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll