Función CreateFileA (fileapi.h)

Artículo
10/05/2022
Tiempo de lectura: 33 minutos

Crea o abre un archivo o dispositivo de E/S. Los dispositivos de E/S más usados son los siguientes: archivo, secuencia de archivos, directorio, disco físico, volumen, búfer de consola, unidad de cinta, recurso de comunicaciones, mailslot y canalización. La función devuelve un identificador que se puede usar para tener acceso al archivo o dispositivo para varios tipos de E/S según el archivo o dispositivo y las marcas y atributos especificados.

Para realizar esta operación como una operación de transacción, lo que da como resultado un identificador que se puede usar para E/S con transacciones, use la función CreateFileTransact .

Sintaxis

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
);

Parámetros

[in] lpFileName

Nombre del archivo o dispositivo que se va a crear o abrir. Puede usar barras diagonales (/) o barras diagonales inversas (\) en este nombre.

En la versión ANSI de esta función, el nombre se limita a MAX_PATH caracteres. Para ampliar este límite a 32 767 caracteres anchos, llame a la versión Unicode de la función y anteponga "\\?\" a la ruta de acceso. Para obtener más información, vea Nomenclatura de archivos, rutas de acceso y espacios de nombres.

Para obtener información sobre los nombres de dispositivo especiales, consulte Definición de un nombre de dispositivo MS-DOS.

Para crear una secuencia de archivos, especifique el nombre del archivo, dos puntos y, a continuación, el nombre de la secuencia. Para obtener más información, vea Secuencias de archivos.

Propina A partir de Windows 10, versión 1607, para la versión unicode de esta función (CreateFileW), puede optar por quitar el MAX_PATH limitación sin prepending "\\?\". Consulte la sección "Limitación máxima de longitud de ruta de acceso" de Nombres de archivos, rutas de acceso y espacios de nombres para obtener más información.

[in] dwDesiredAccess

El acceso solicitado al archivo o dispositivo, que se puede resumir como de lectura, escritura, ambos o 0 para indicar ninguno).

Los valores más usados son GENERIC_READ, GENERIC_WRITE o ambos (GENERIC_READ | GENERIC_WRITE). Para obtener más información, vea Derechos de acceso genéricos, Derechos de seguridad de archivos y derechos de acceso, Constantes de derechos de acceso de archivos y ACCESS_MASK.

Si este parámetro es cero, la aplicación puede consultar determinados metadatos, como los atributos de archivo, directorio o dispositivo sin tener acceso a ese archivo o dispositivo, incluso si se hubiera denegado GENERIC_READ acceso.

No se puede solicitar un modo de acceso que entre en conflicto con el modo de uso compartido especificado por el parámetro dwShareMode en una solicitud abierta que ya tenga un identificador abierto.

Para obtener más información, vea la sección Comentarios de este tema y Creación y apertura de archivos.

[in] dwShareMode

Modo de uso compartido solicitado del archivo o dispositivo, que se puede leer, escribir, eliminar, todos o ninguno (consulte la tabla siguiente). Las solicitudes de acceso a atributos o atributos extendidos no se ven afectadas por esta marca.

Si este parámetro es cero y CreateFile se realiza correctamente, el archivo o dispositivo no se puede compartir y no se puede volver a abrir hasta que se cierre el identificador del archivo o dispositivo. Para obtener más información, vea la sección Comentarios.

No se puede solicitar un modo de uso compartido que entre en conflicto con el modo de acceso especificado en una solicitud existente que tenga un identificador abierto. CreateFile produciría un error y la función GetLastError devolvería ERROR_SHARING_VIOLATION.

Para permitir que un proceso comparta un archivo o dispositivo mientras otro proceso tenga abierto el archivo o dispositivo, use una combinación compatible de uno o varios de los valores siguientes. Para obtener más información sobre las combinaciones válidas de este parámetro con el parámetro dwDesiredAccess , vea Crear y abrir archivos.

Nota Las opciones de uso compartido de cada identificador abierto permanecen en vigor hasta que se cierra ese identificador, independientemente del contexto del proceso.

Valor	Significado
0 0x00000000	Impide que otros procesos abran un archivo o dispositivo si solicitan acceso de eliminación, lectura o escritura.
FILE_SHARE_DELETE 0x00000004	Habilita las operaciones abiertas posteriores en un archivo o dispositivo para solicitar acceso de eliminación. De lo contrario, otros procesos no pueden abrir el archivo o el dispositivo si solicitan acceso de eliminación. Si no se especifica esta marca, pero se ha abierto el archivo o el dispositivo para el acceso de eliminación, se produce un error en la función. Nota El acceso de eliminación permite las operaciones de eliminación y cambio de nombre.
FILE_SHARE_READ 0x00000001	Habilita las operaciones abiertas posteriores en un archivo o dispositivo para solicitar acceso de lectura. De lo contrario, otros procesos no pueden abrir el archivo o el dispositivo si solicitan acceso de lectura. Si no se especifica esta marca, pero se ha abierto el archivo o el dispositivo para el acceso de lectura, se produce un error en la función.
FILE_SHARE_WRITE 0x00000002	Habilita las operaciones abiertas posteriores en un archivo o dispositivo para solicitar acceso de escritura. De lo contrario, otros procesos no pueden abrir el archivo o el dispositivo si solicitan acceso de escritura. Si no se especifica esta marca, pero el archivo o dispositivo se ha abierto para el acceso de escritura o tiene una asignación de archivos con acceso de escritura, se produce un error en la función.

[in, optional] lpSecurityAttributes

Puntero a una estructura de SECURITY_ATTRIBUTES que contiene dos miembros de datos independientes pero relacionados: un descriptor de seguridad opcional y un valor booleano que determina si los procesos secundarios pueden heredar el identificador devuelto.

Este parámetro puede ser NULL.

Si este parámetro es NULL, el identificador devuelto por CreateFile no puede ser heredado por ningún proceso secundario que la aplicación pueda crear y el archivo o dispositivo asociado al identificador devuelto obtiene un descriptor de seguridad predeterminado.

El miembro lpSecurityDescriptor de la estructura especifica un SECURITY_DESCRIPTOR para un archivo o dispositivo. Si este miembro es NULL, se asigna un descriptor de seguridad predeterminado al archivo o dispositivo asociado al identificador devuelto.

CreateFile omite el miembro lpSecurityDescriptor al abrir un archivo o dispositivo existente, pero sigue usando el miembro bInheritHandle .

El miembro bInheritHandle de la estructura especifica si se puede heredar el identificador devuelto.

Para obtener más información, vea la sección Comentarios.

[in] dwCreationDisposition

Acción que se debe realizar en un archivo o dispositivo que existe o no existe.

En el caso de los dispositivos distintos de los archivos, este parámetro suele establecerse en OPEN_EXISTING.

Para obtener más información, vea la sección Comentarios.

Este parámetro debe ser uno de los siguientes valores, que no se pueden combinar:

Valor	Significado
CREATE_ALWAYS 2	Crea un nuevo archivo, siempre. Si el archivo especificado existe y se puede escribir, la función sobrescribe el archivo, la función se realiza correctamente y el código de último error se establece en ERROR_ALREADY_EXISTS (183). Si el archivo especificado no existe y es una ruta de acceso válida, se crea un nuevo archivo, la función se realiza correctamente y el último código de error se establece en cero. Para obtener más información, vea la sección Comentarios de este tema.
CREATE_NEW 1	Crea un nuevo archivo, solo si aún no existe. Si el archivo especificado existe, se produce un error en la función y el último código de error se establece en ERROR_FILE_EXISTS (80). Si el archivo especificado no existe y es una ruta de acceso válida a una ubicación grabable, se crea un nuevo archivo.
OPEN_ALWAYS 4	Abre un archivo, siempre. Si el archivo especificado existe, la función se realiza correctamente y el último código de error se establece en ERROR_ALREADY_EXISTS (183). Si el archivo especificado no existe y es una ruta de acceso válida a una ubicación grabable, la función crea un archivo y el último código de error se establece en cero.
OPEN_EXISTING 3	Abre un archivo o dispositivo, solo si existe. Si el archivo o dispositivo especificados no existe, se produce un error en la función y el último código de error se establece en ERROR_FILE_NOT_FOUND (2). Para obtener más información sobre los dispositivos, consulte la sección Comentarios.
TRUNCATE_EXISTING 5	Abre un archivo y lo trunca para que su tamaño sea cero bytes, solo si existe. Si el archivo especificado no existe, se produce un error en la función y el último código de error se establece en ERROR_FILE_NOT_FOUND (2). El proceso de llamada debe abrir el archivo con el GENERIC_WRITE bit establecido como parte del parámetro dwDesiredAccess .

[in] dwFlagsAndAttributes

Los atributos y marcas de archivo o dispositivo, FILE_ATTRIBUTE_NORMAL siendo el valor predeterminado más común para los archivos.

Este parámetro puede incluir cualquier combinación de los atributos de archivo disponibles (FILE_ATTRIBUTE_*). Todos los demás atributos de archivo invalidan FILE_ATTRIBUTE_NORMAL.

Este parámetro también puede contener combinaciones de marcas (FILE_FLAG_*) para controlar el comportamiento del almacenamiento en caché de archivos o dispositivos, los modos de acceso y otras marcas de propósito especial. Se combinan con cualquier valor de FILE_ATTRIBUTE_* .

Este parámetro también puede contener información de calidad de servicio de seguridad (SQOS) especificando la marca SECURITY_SQOS_PRESENT . La información adicional sobre marcas relacionadas con SQOS se presenta en la tabla que sigue a las tablas de atributos y marcas.

Nota Cuando CreateFile abre un archivo existente, normalmente combina las marcas de archivo con los atributos de archivo del archivo existente y omite los atributos de archivo proporcionados como parte de dwFlagsAndAttributes. Los casos especiales se detallan en Crear y abrir archivos.

Algunos de los siguientes atributos y marcas de archivo solo se pueden aplicar a los archivos y no necesariamente todos los demás tipos de dispositivos que CreateFile pueden abrir. Para obtener más información, vea la sección Comentarios de este tema y Crear y abrir archivos.

Para obtener acceso más avanzado a los atributos de archivo, vea SetFileAttributes. Para obtener una lista completa de todos los atributos de archivo con sus valores y descripciones, vea Constantes de atributo de archivo.

Atributo	Significado
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	El archivo debe archivarse. Las aplicaciones usan este atributo para marcar los archivos para crear una copia de seguridad o quitarlos.
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	El archivo o directorio está cifrado. Para un archivo, esto significa que todos los datos del archivo están cifrados. Para un directorio, esto significa que el cifrado es el valor predeterminado para los archivos y subdirectorios recién creados. Para obtener más información, vea Cifrado de archivos. Esta marca no tiene ningún efecto si también se especifica FILE_ATTRIBUTE_SYSTEM . Esta marca no se admite en las ediciones Home, Home Premium, Starter o ARM de Windows.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	El archivo está oculto. No lo incluya en una lista de directorios normales.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	El archivo no tiene otros atributos establecidos. Este atributo solo es válido si se usa por sí solo.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	Los datos de un archivo no están disponibles inmediatamente. Este atributo indica que los datos de archivo se mueven físicamente al almacenamiento sin conexión. El almacenamiento remoto usa este atributo, el software de administración de almacenamiento jerárquico. Las aplicaciones no deben cambiar arbitrariamente este atributo.
FILE_ATTRIBUTE_READONLY 1 (0x1)	El archivo es de solo lectura. Las aplicaciones pueden leer el archivo, pero no pueden escribir en él ni eliminarlo.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	El archivo forma parte o se utiliza exclusivamente por un sistema operativo.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	El archivo se usa para el almacenamiento temporal. Para obtener más información, vea la sección Comportamiento del almacenamiento en caché de este tema.

Marca	Significado
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	El archivo se está abriendo o creando para una operación de copia de seguridad o restauración. El sistema garantiza que el proceso de llamada invalide las comprobaciones de seguridad de archivos cuando el proceso tiene privilegios SE_BACKUP_NAME y SE_RESTORE_NAME . Para obtener más información, consulte Cambio de privilegios en un token. Debe establecer esta marca para obtener un identificador en un directorio. Se puede pasar un identificador de directorio a algunas funciones en lugar de a un identificador de archivo. Para obtener más información, vea la sección Comentarios.
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	El archivo se eliminará inmediatamente después de que se cierren todos sus identificadores, lo que incluye el identificador especificado y cualquier otro identificador abierto o duplicado. Si hay identificadores abiertos existentes en un archivo, se produce un error en la llamada a menos que se hayan abierto con el modo de FILE_SHARE_DELETE recurso compartido. Se producirá un error en las solicitudes de apertura posteriores del archivo, a menos que se especifique el modo de recurso compartido FILE_SHARE_DELETE.
FILE_FLAG_NO_BUFFERING 0x20000000	El archivo o dispositivo se abre sin almacenamiento en caché del sistema para las lecturas y escrituras de datos. Esta marca no afecta al almacenamiento en caché del disco duro ni a los archivos asignados a memoria. Hay requisitos estrictos para trabajar correctamente con archivos abiertos con CreateFile mediante la marca FILE_FLAG_NO_BUFFERING , para obtener más información, consulte File Buffering.
FILE_FLAG_OPEN_NO_RECALL 0x00100000	Se solicitan los datos del archivo, pero deben seguir estando ubicados en el almacenamiento remoto. No se debe transportar de vuelta al almacenamiento local. Esta marca es para que la usen los sistemas de almacenamiento remoto.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	No se producirá el procesamiento normal del punto de reanálisis ; CreateFile intentará abrir el punto de reanálisis. Cuando se abre un archivo, se devuelve un identificador de archivo, independientemente de si el filtro que controla el punto de reanálisis está operativo. Esta marca no se puede usar con la marca CREATE_ALWAYS . Si el archivo no es un punto de reanálisis, se omite esta marca. Para obtener más información, vea la sección Comentarios.
FILE_FLAG_OVERLAPPED 0x40000000	El archivo o dispositivo se está abriendo o creando para E/S asincrónica. Cuando se completen las operaciones de E/S posteriores en este identificador, el evento especificado en la estructura SUPERPUESTA se establecerá en el estado señalado. Si se especifica esta marca, el archivo se puede usar para operaciones simultáneas de lectura y escritura. Si no se especifica esta marca, las operaciones de E/S se serializan, incluso si las llamadas a las funciones de lectura y escritura especifican una estructura SUPERPUESTA . Para obtener información sobre las consideraciones al usar un identificador de archivo creado con esta marca, consulte la sección Identificadores de E/S sincrónicos y asincrónicos de este tema.
FILE_FLAG_POSIX_SEMANTICS 0x01000000	El acceso se producirá según las reglas POSIX. Esto incluye permitir varios archivos con nombres, que solo difieren en el caso de los sistemas de archivos que admiten esa nomenclatura. Use cuidado al usar esta opción, ya que es posible que las aplicaciones escritas para MS-DOS o Windows de 16 bits no puedan acceder a los archivos creados con esta marca.
FILE_FLAG_RANDOM_ACCESS 0x10000000	El acceso está pensado para ser aleatorio. El sistema puede considerar que esto es una sugerencia para optimizar el almacenamiento en caché del archivo. Esta marca no tiene ningún efecto si el sistema de archivos no admite la E/S almacenada en caché ni FILE_FLAG_NO_BUFFERING. Para obtener más información, vea la sección Comportamiento del almacenamiento en caché de este tema.
FILE_FLAG_SESSION_AWARE 0x00800000	El archivo o dispositivo se está abriendo con reconocimiento de sesión. Si no se especifica esta marca, los procesos que se ejecutan en la sesión 0 no pueden abrir los dispositivos por sesión (por ejemplo, un dispositivo que usa el redireccionamiento USB de RemoteFX). Esta marca no tiene ningún efecto para los llamadores que no están en la sesión 0. Esta marca solo se admite en las ediciones de servidor de Windows. Windows Server 2008 R2 y Windows Server 2008: Esta marca no se admite antes de Windows Server 2012.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	El acceso está pensado para ser secuencial de principio a fin. El sistema puede considerar que esto es una sugerencia para optimizar el almacenamiento en caché del archivo. Esta marca no se debe usar si se usará lectura subyacente (es decir, exámenes inversos). Esta marca no tiene ningún efecto si el sistema de archivos no admite la E/S almacenada en caché ni FILE_FLAG_NO_BUFFERING. Para obtener más información, vea la sección Comportamiento del almacenamiento en caché de este tema.
FILE_FLAG_WRITE_THROUGH 0x80000000	Las operaciones de escritura no pasarán por ninguna memoria caché intermedia, y pasarán directamente al disco. Para obtener más información, consulte la sección Comportamiento del almacenamiento en caché de este tema.

El parámetro dwFlagsAndAttributes también puede especificar información de SQOS. Para obtener más información, vea Niveles de suplantación. Cuando la aplicación que realiza la llamada especifica la marca SECURITY_SQOS_PRESENT como parte de dwFlagsAndAttributes, también puede contener uno o varios de los valores siguientes.

Marca de seguridad	Significado
SECURITY_ANONYMOUS	Suplanta a un cliente en el nivel de suplantación anónima.
SECURITY_CONTEXT_TRACKING	El modo de seguimiento de seguridad es dinámico. Si no se especifica esta marca, el modo de seguimiento de seguridad es estático.
SECURITY_DELEGATION	Suplanta a un cliente en el nivel de suplantación de delegación.
SECURITY_EFFECTIVE_ONLY	Solo los aspectos habilitados del contexto de seguridad del cliente están disponibles para el servidor. Si no especifica esta marca, todos los aspectos del contexto de seguridad del cliente están disponibles. Esto permite al cliente limitar los grupos y privilegios que un servidor puede usar al suplantar al cliente.
SECURITY_IDENTIFICATION	Suplanta a un cliente en el nivel de suplantación de identificación.
SECURITY_IMPERSONATION	Suplantar a un cliente en el nivel de suplantación. Este es el comportamiento predeterminado si no se especifica ninguna otra marca junto con la marca SECURITY_SQOS_PRESENT .

[in, optional] hTemplateFile

Identificador válido para un archivo de plantilla con el derecho de acceso GENERIC_READ . El archivo de plantilla proporciona atributos extendidos y atributos de archivo para el archivo que se va a crear.

Este parámetro puede ser NULL.

Al abrir un archivo existente, CreateFile omite este parámetro.

Al abrir un nuevo archivo cifrado, el archivo hereda la lista de control de acceso discrecional de su directorio primario. Para obtener más información, consulte Cifrado de archivos.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es un identificador abierto para el archivo, dispositivo, canalización con nombre o ranura de correo especificados.

Si se produce un error en la función, el valor devuelto es INVALID_HANDLE_VALUE. Para obtener información de error extendida, llame a GetLastError.

Comentarios

CreateFile se desarrolló originalmente para la interacción de archivos, pero desde entonces se ha ampliado y mejorado para incluir la mayoría de los otros tipos de dispositivos y mecanismos de E/S disponibles para los desarrolladores de Windows. En esta sección se intentan tratar los diversos problemas que pueden experimentar los desarrolladores al usar CreateFile en contextos diferentes y con diferentes tipos de E/S. El texto intenta usar el archivo de palabras solo cuando se hace referencia específicamente a los datos almacenados en un archivo real en un sistema de archivos. Sin embargo, algunos usos del archivo pueden hacer referencia más generalmente a un objeto de E/S que admite mecanismos similares a archivos. Este uso liberal del término archivo es especialmente frecuente en nombres constantes y nombres de parámetros debido a los motivos históricos mencionados anteriormente.

Cuando una aplicación termine de usar el identificador de objeto devuelto por CreateFile, use la función CloseHandle para cerrar el identificador. Esto no solo libera recursos del sistema, pero puede tener una influencia más amplia en aspectos como compartir el archivo o el dispositivo y confirmar datos en el disco. Los detalles se indican en este tema según corresponda.

Windows Server 2003 y Windows XP: Se produce una infracción de uso compartido si se intenta abrir un archivo o directorio para su eliminación en un equipo remoto cuando el valor del parámetro dwDesiredAccess es la marca de acceso DELETE (0x00010000) O con cualquier otra marca de acceso y el archivo o directorio remoto no se ha abierto con FILE_SHARE_DELETE. Para evitar la infracción de uso compartido en este escenario, abra el archivo o directorio remoto solo con el derecho de acceso DELETE , o llame a DeleteFile sin abrir primero el archivo o directorio para su eliminación.

Algunos sistemas de archivos, como el sistema de archivos NTFS, admiten la compresión o el cifrado para archivos y directorios individuales. En los volúmenes que tienen un sistema de archivos montado con esta compatibilidad, un nuevo archivo hereda los atributos de compresión y cifrado de su directorio.

No se puede usar CreateFile para controlar la compresión, descompresión o descifrado en un archivo o directorio. Para obtener más información, vea Crear y abrir archivos, compresión y descompresión de archivos y cifrado de archivos.

Windows Server 2003 y Windows XP: Con fines de compatibilidad con versiones anteriores, CreateFile no aplica reglas de herencia al especificar un descriptor de seguridad en lpSecurityAttributes. Para admitir la herencia, las funciones que posteriormente consultan el descriptor de seguridad de este archivo pueden determinar y notificar de forma heurística que la herencia está en vigor. Para obtener más información, vea Propagación automática de ACE heredables.

Como se indicó anteriormente, si el parámetro lpSecurityAttributes es NULL, cualquier proceso secundario puede crear el identificador devuelto por CreateFile . También se aplica la siguiente información sobre este parámetro:

Si la variable miembro bInheritHandle no es FALSE, que es cualquier valor distinto de cero, se puede heredar el identificador. Por lo tanto, es fundamental que este miembro de estructura se inicialice correctamente en FALSE si no pretende que el identificador se pueda heredar.
Las listas de control de acceso (ACL) del descriptor de seguridad predeterminado para un archivo o directorio se heredan de su directorio primario.
El sistema de archivos de destino debe admitir la seguridad en los archivos y directorios para que el miembro lpSecurityDescriptor tenga un efecto sobre ellos, que se puede determinar mediante GetVolumeInformation.

En Windows 8 y Windows Server 2012, esta función es compatible con las siguientes tecnologías.

Technology	Compatible
Protocolo bloque de mensajes del servidor (SMB) 3.0	Yes
Conmutación por error transparente (TFO) de SMB 3.0	Ver comentarios
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Ver comentarios
Sistema de archivos de volumen compartido de clúster (CsvFS)	Yes
Sistema de archivos resistente a errores (ReFS)	Yes

Tenga en cuenta que CreateFile con eliminación de sustitución producirá un error si se realiza en un archivo donde ya hay un flujo de datos alternativo abierto.

Comportamiento del vínculo simbólico

Si la llamada a esta función crea un archivo, no hay ningún cambio en el comportamiento. Además, tenga en cuenta la siguiente información sobre FILE_FLAG_OPEN_REPARSE_POINT:

Si se especifica FILE_FLAG_OPEN_REPARSE_POINT :
- Si se abre un archivo existente y es un vínculo simbólico, el identificador devuelto es un identificador para el vínculo simbólico.
- Si se especifican TRUNCATE_EXISTING o FILE_FLAG_DELETE_ON_CLOSE , el archivo afectado es un vínculo simbólico.
Si no se especifica FILE_FLAG_OPEN_REPARSE_POINT:
- Si se abre un archivo existente y es un vínculo simbólico, el identificador devuelto es un identificador para el destino.
- Si se especifican CREATE_ALWAYS, TRUNCATE_EXISTING o FILE_FLAG_DELETE_ON_CLOSE , el archivo afectado es el destino.

Comportamiento del almacenamiento en caché

CreateFile usa varios de los valores posibles para el parámetro dwFlagsAndAttributes para controlar o afectar a cómo el sistema almacena en caché los datos asociados al identificador. Son las siguientes:

FILE_FLAG_NO_BUFFERING
FILE_FLAG_RANDOM_ACCESS
FILE_FLAG_SEQUENTIAL_SCAN
FILE_FLAG_WRITE_THROUGH
FILE_ATTRIBUTE_TEMPORARY

Si no se especifica ninguna de estas marcas, el sistema usa un esquema de almacenamiento en caché de uso general predeterminado. De lo contrario, el almacenamiento en caché del sistema se comporta como se especifica para cada marca.

Algunas de estas marcas no deben combinarse. Por ejemplo, la combinación de FILE_FLAG_RANDOM_ACCESS con FILE_FLAG_SEQUENTIAL_SCAN es la auto-derrota.

Especificar la marca FILE_FLAG_SEQUENTIAL_SCAN puede aumentar el rendimiento de las aplicaciones que leen archivos grandes mediante el acceso secuencial. Las mejoras de rendimiento pueden ser aún más notables para las aplicaciones que leen archivos grandes principalmente secuencialmente, pero en ocasiones omiten hacia delante en intervalos pequeños de bytes. Si una aplicación mueve el puntero de archivo para el acceso aleatorio, lo más probable es que no se produzca un rendimiento óptimo del almacenamiento en caché. Sin embargo, todavía se garantiza la operación correcta.

Las marcas FILE_FLAG_WRITE_THROUGH y FILE_FLAG_NO_BUFFERING son independientes y se pueden combinar.

Si se usa FILE_FLAG_WRITE_THROUGH pero no se especifica también FILE_FLAG_NO_BUFFERING , de modo que el almacenamiento en caché del sistema esté en vigor, los datos se escriben en la memoria caché del sistema, pero se vacían en el disco sin demora.

Si se especifican FILE_FLAG_WRITE_THROUGH y FILE_FLAG_NO_BUFFERING , de modo que el almacenamiento en caché del sistema no esté en vigor, los datos se vacían inmediatamente en el disco sin pasar por la memoria caché del sistema de Windows. El sistema operativo también solicita una escritura a través de la caché de hardware local del disco duro a medios persistentes.

Nota No todo el hardware de disco duro admite esta funcionalidad de escritura a través.

El uso adecuado de la marca FILE_FLAG_NO_BUFFERING requiere consideraciones especiales sobre la aplicación. Para obtener más información, vea File Buffering.

Una solicitud de escritura a través de FILE_FLAG_WRITE_THROUGH también hace que NTFS vacíe los cambios de metadatos, como una actualización de marca de tiempo o una operación de cambio de nombre, que resulta del procesamiento de la solicitud. Por este motivo, la marca FILE_FLAG_WRITE_THROUGH se usa a menudo con la marca FILE_FLAG_NO_BUFFERING como reemplazo de llamar a la función FlushFileBuffers después de cada escritura, lo que puede provocar penalizaciones de rendimiento innecesarias. El uso de estas marcas conjuntamente evita esas penalizaciones. Para obtener información general sobre el almacenamiento en caché de archivos y metadatos, vea Almacenamiento en caché de archivos.

Cuando FILE_FLAG_NO_BUFFERING se combina con FILE_FLAG_OVERLAPPED, las marcas proporcionan un rendimiento asincrónico máximo, ya que la E/S no se basa en las operaciones sincrónicas del administrador de memoria. Sin embargo, algunas operaciones de E/S tardan más tiempo, ya que los datos no se mantienen en la memoria caché. Además, es posible que los metadatos del archivo todavía se almacenen en caché (por ejemplo, al crear un archivo vacío). Para asegurarse de que los metadatos se vacían en el disco, use la función FlushFileBuffers .

Especificar el atributo FILE_ATTRIBUTE_TEMPORARY hace que los sistemas de archivos eviten volver a escribir datos en almacenamiento masivo si hay suficiente memoria caché disponible, ya que una aplicación elimina un archivo temporal después de cerrar un identificador. En ese caso, el sistema puede evitar por completo la escritura de los datos. Aunque no controla directamente el almacenamiento en caché de datos de la misma manera que las marcas mencionadas anteriormente, el atributo FILE_ATTRIBUTE_TEMPORARY indica al sistema que contenga tanto como sea posible en la memoria caché del sistema sin escribir y, por lo tanto, puede ser de preocupación para determinadas aplicaciones.

Archivos

Si cambia el nombre o elimina un archivo y, a continuación, lo restaura poco después, el sistema busca en la memoria caché la información del archivo que se va a restaurar. La información almacenada en caché incluye su par de nombres cortos y largos y el tiempo de creación.

Si llama a CreateFile en un archivo que está pendiente de eliminación como resultado de una llamada anterior a DeleteFile, se produce un error en la función. El sistema operativo retrasa la eliminación de archivos hasta que se cierran todos los identificadores del archivo. GetLastError devuelve ERROR_ACCESS_DENIED.

El parámetro dwDesiredAccess puede ser cero, lo que permite a la aplicación consultar atributos de archivo sin tener acceso al archivo si la aplicación se ejecuta con una configuración de seguridad adecuada. Esto resulta útil para probar la existencia de un archivo sin abrirlo para el acceso de lectura o escritura, o para obtener otras estadísticas sobre el archivo o directorio. Vea Obtener y establecer información de archivo y GetFileInformationByHandle.

Si se especifican CREATE_ALWAYS y FILE_ATTRIBUTE_NORMAL , CreateFile produce un error y establece el último error en ERROR_ACCESS_DENIED si el archivo existe y tiene el atributo FILE_ATTRIBUTE_HIDDEN o FILE_ATTRIBUTE_SYSTEM . Para evitar el error, especifique los mismos atributos que el archivo existente.

Cuando una aplicación crea un archivo a través de una red, es mejor usarlo GENERIC_READ | GENERIC_WRITE para dwDesiredAccess que usar solo GENERIC_WRITE . El código resultante es más rápido, ya que el redirector puede usar el administrador de caché y enviar menos SMB con más datos. Esta combinación también evita un problema por el que la escritura en un archivo a través de una red puede devolver ocasionalmente ERROR_ACCESS_DENIED.

Para obtener más información, vea Crear y abrir archivos.

Identificadores de E/S sincrónicos y asincrónicos

CreateFile proporciona para crear un identificador de archivo o dispositivo que sea sincrónico o asincrónico. Un identificador sincrónico se comporta de forma que las llamadas de función de E/S que usan ese identificador se bloquean hasta que se completen, mientras que un identificador de archivo asincrónico permite que el sistema devuelva inmediatamente de las llamadas de función de E/S, tanto si han completado la operación de E/S como si no. Como se indicó anteriormente, este comportamiento sincrónico frente a asincrónico se determina especificando FILE_FLAG_OVERLAPPED dentro del parámetro dwFlagsAndAttributes . Hay varias complejidades y posibles dificultades al usar E/S asincrónica; para obtener más información, vea E/S sincrónica y asincrónica.

Secuencias de archivos

En los sistemas de archivos NTFS, puede usar CreateFile para crear secuencias independientes dentro de un archivo. Para obtener más información, vea Secuencias de archivos.

Directorios

Una aplicación no puede crear un directorio mediante CreateFile, por lo que solo el valor de OPEN_EXISTING es válido para dwCreationDisposition para este caso de uso. Para crear un directorio, la aplicación debe llamar a CreateDirectory o CreateDirectoryEx.

Para abrir un directorio mediante CreateFile, especifique la marca FILE_FLAG_BACKUP_SEMANTICS como parte de dwFlagsAndAttributes. Las comprobaciones de seguridad adecuadas se siguen aplicando cuando se usa esta marca sin privilegios de SE_BACKUP_NAME y SE_RESTORE_NAME .

Al usar CreateFile para abrir un directorio durante la desfragmentación de un volumen del sistema de archivos FAT o FAT32, no especifique el derecho de acceso MAXIMUM_ALLOWED . Si se hace esto, se deniega el acceso al directorio. Especifique el derecho de acceso GENERIC_READ en su lugar.

Para obtener más información, consulte Acerca de la administración de directorios.

Discos físicos y volúmenes

El acceso directo al disco o a un volumen está restringido.

Windows Server 2003 y Windows XP: El acceso directo al disco o a un volumen no está restringido de esta manera.

Puede usar la función CreateFile para abrir una unidad de disco físico o un volumen, que devuelve un identificador de dispositivo de almacenamiento de acceso directo (DASD) que se puede usar con la función DeviceIoControl . Esto le permite acceder directamente al disco o al volumen, por ejemplo, metadatos de disco como la tabla de particiones. Sin embargo, este tipo de acceso también expone la unidad de disco o volumen a una posible pérdida de datos, ya que una escritura incorrecta en un disco mediante este mecanismo podría hacer que su contenido fuera inaccesible para el sistema operativo. Para garantizar la integridad de los datos, asegúrese de familiarizarse con DeviceIoControl y de cómo otras API se comportan de forma diferente con un identificador de acceso directo en lugar de un identificador de sistema de archivos.

Se deben cumplir los siguientes requisitos para que dicha llamada se realice correctamente:

El autor de la llamada debe tener privilegios administrativos. Para obtener más información, consulte Ejecución con privilegios especiales.
El parámetro dwCreationDisposition debe tener la marca OPEN_EXISTING .
Al abrir un volumen o un disquete, el parámetro dwShareMode debe tener la marca FILE_SHARE_WRITE .

Nota El parámetro dwDesiredAccess puede ser cero, lo que permite que la aplicación consulte los atributos del dispositivo sin tener acceso a un dispositivo. Esto es útil para que una aplicación determine el tamaño de una unidad de disco de disquete y los formatos que admite sin necesidad de un disquete en una unidad, por ejemplo. También se puede usar para leer estadísticas sin necesidad de permiso de lectura y escritura de datos de nivel superior.

Al abrir una unidad física x:, la cadena lpFileName debe tener el siguiente formato: "\\.\PhysicalDriveX". Los números de disco duro comienzan en cero. En la tabla siguiente se muestran algunos ejemplos de cadenas de unidad física.

String	Significado
"\\.\PhysicalDrive0"	Abre la primera unidad física.
"\\.\PhysicalDrive2"	Abre la tercera unidad física.

Para obtener el identificador de unidad física de un volumen, abra un identificador para el volumen y llame a la función DeviceIoControl con IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. Este código de control devuelve el número de disco y el desplazamiento de cada una de las extensiones del volumen; un volumen puede abarcar varios discos físicos.

Para obtener un ejemplo de cómo abrir una unidad física, consulte Llamada a DeviceIoControl.

Al abrir un volumen o una unidad multimedia extraíble (por ejemplo, una unidad de disco de disquete o memoria flash), la cadena lpFileName debe ser la siguiente forma: "\.\X:". No use una barra diagonal inversa final (\), que indica el directorio raíz de una unidad. En la tabla siguiente se muestran algunos ejemplos de cadenas de unidad.

String	Significado
"\\.\A:"	Abre la unidad de disco A.
"\\.\C:"	Abre el volumen C: .
"\\.\C:\"	Abre el sistema de archivos del volumen C: .

También puede abrir un volumen haciendo referencia a su nombre de volumen. Para obtener más información, consulte Nomenclatura de un volumen.

Un volumen contiene uno o varios sistemas de archivos montados. Los identificadores de volumen se pueden abrir como no almacenados en caché a discreción del sistema de archivos determinado, incluso cuando la opción no almacenada en caché no se especifica en CreateFile. Debe suponer que todos los sistemas de archivos de Microsoft abren los identificadores de volumen como no almacenados en caché. Las restricciones de E/S no almacenadas en caché para los archivos también se aplican a los volúmenes.

Un sistema de archivos puede o no requerir alineación del búfer aunque los datos no se almacenen en caché. Sin embargo, si se especifica la opción no almacenada en caché al abrir un volumen, se aplica la alineación del búfer independientemente del sistema de archivos del volumen. Se recomienda en todos los sistemas de archivos que abra los identificadores de volumen como no almacenados en caché y siga las restricciones de E/S no almacenadas en caché.

Nota Para leer o escribir en los últimos sectores del volumen, debe llamar a DeviceIoControl y especificar FSCTL_ALLOW_EXTENDED_DASD_IO. Esto indica al controlador del sistema de archivos que no realice ninguna comprobación de límites de E/S en las llamadas de lectura o escritura de particiones. En su lugar, el controlador del dispositivo realiza comprobaciones de límites.

Dispositivo de modificador

Los códigos de control IOCTL_CHANGER_* para DeviceIoControl aceptan un identificador para un dispositivo modificador. Para abrir un dispositivo modificador, use un nombre de archivo con el siguiente formato: "\\.\Changerx", donde x es un número que indica qué dispositivo se va a abrir, empezando por cero. Para abrir el dispositivo modificador cero en una aplicación escrita en C o C++, use el siguiente nombre de archivo: "\\.\Changer0".

Unidades de cinta

Puede abrir unidades de cinta con un nombre de archivo de la siguiente forma: "\\.\TAPEx", donde x es un número que indica qué unidad se va a abrir, empezando por la unidad de cinta cero. Para abrir la unidad de cinta cero en una aplicación escrita en C o C++, use el siguiente nombre de archivo: "\\.\TAPE0".

Para obtener más información, consulte Copia de seguridad.

Recursos de comunicaciones

La función CreateFile puede crear un identificador para un recurso de comunicaciones, como el puerto serie COM1. Para los recursos de comunicaciones, el parámetro dwCreationDisposition debe ser OPEN_EXISTING, el parámetro dwShareMode debe ser cero (acceso exclusivo) y el parámetro hTemplateFile debe ser NULL. Se puede especificar el acceso de lectura, escritura o lectura y escritura, y el identificador se puede abrir para E/S superpuesta.

Para especificar un número de puerto COM mayor que 9, use la sintaxis siguiente: "\\.\COM10". Esta sintaxis funciona para todos los números de puerto y hardware que permite especificar números de puerto COM.

Para obtener más información sobre las comunicaciones, vea Comunicaciones.

Consolas

La función CreateFile puede crear un identificador para la entrada de la consola (CONIN$). Si el proceso tiene un identificador abierto como resultado de la herencia o duplicación, también puede crear un identificador para el búfer de pantalla activo (CONOUT$). El proceso de llamada debe asociarse a una consola heredada o a una asignada por la función AllocConsole . Para los identificadores de consola, establezca los parámetros CreateFile como se indica a continuación.

Parámetros	Valor
lpFileName	Use el valor CONIN$ para especificar la entrada de la consola. Use el valor CONOUT$ para especificar la salida de la consola. CONIN$ obtiene un identificador para el búfer de entrada de la consola, incluso si la función SetStdHandle redirige el identificador de entrada estándar. Para obtener el identificador de entrada estándar, use la función GetStdHandle . CONOUT$ obtiene un identificador del búfer de pantalla activo, incluso si SetStdHandle redirige el identificador de salida estándar. Para obtener el identificador de salida estándar, use GetStdHandle.
dwDesiredAccess	`GENERIC_READ \| GENERIC_WRITE` es preferible, pero cualquiera de ellos puede limitar el acceso.
dwShareMode	Al abrir CONIN$, especifique FILE_SHARE_READ. Al abrir CONOUT$, especifique FILE_SHARE_WRITE. Si el proceso de llamada hereda la consola o si un proceso secundario debe poder acceder a la consola, este parámetro debe ser `FILE_SHARE_READ \| FILE_SHARE_WRITE`.
lpSecurityAttributes	Si desea que la consola se herede, el miembro bInheritHandle de la estructura SECURITY_ATTRIBUTES debe ser TRUE.
dwCreationDisposition	Debe especificar OPEN_EXISTING al usar CreateFile para abrir la consola.
dwFlagsAndAttributes	ignorado.
hTemplateFile	ignorado.

En la tabla siguiente se muestran varios valores de dwDesiredAccess y lpFileName.

lpFileName	dwDesiredAccess	Resultado
"CON"	GENERIC_READ	Abre la consola para la entrada.
"CON"	GENERIC_WRITE	Abre la consola para la salida.
"CON"	`GENERIC_READ \| GENERIC_WRITE`	Provoca un error en CreateFile ; GetLastError devuelve ERROR_FILE_NOT_FOUND.

Mailslots

Si CreateFile abre el final del cliente de un mailslot, la función devuelve INVALID_HANDLE_VALUE si el cliente mailslot intenta abrir un mailslot local antes de que el servidor mailslot lo haya creado con la función CreateMailSlot .

Para obtener más información, vea Mailslots.

Tuberías

Si CreateFile abre el extremo del cliente de una canalización con nombre, la función usa cualquier instancia de la canalización con nombre que esté en estado de escucha. El proceso de apertura puede duplicar el identificador tantas veces como sea necesario, pero después de abrirlo, otro cliente no puede abrir la instancia de canalización con nombre. El acceso especificado cuando se abre una canalización debe ser compatible con el acceso especificado en el parámetro dwOpenMode de la función CreateNamedPipe .

Si la función CreateNamedPipe no se llamó correctamente en el servidor antes de esta operación, no existirá una canalización y CreateFile producirá un error ERROR_FILE_NOT_FOUND.

Si hay al menos una instancia de canalización activa, pero no hay canalizaciones de agente de escucha disponibles en el servidor, lo que significa que todas las instancias de canalización están conectadas actualmente, CreateFile produce un error con ERROR_PIPE_BUSY.

Para obtener más información, consulte Canalizaciones.

Ejemplos

Las operaciones de archivo de ejemplo se muestran en los temas siguientes:

La E/S del dispositivo físico se muestra en los temas siguientes:

Un ejemplo de uso de canalizaciones con nombre se encuentra en El cliente de canalización con nombre.

El trabajo con un mailslot se muestra en Escribir en un objeto Mailslot.

Puede encontrar un fragmento de código de copia de seguridad en cinta en Creación de una aplicación de copia de seguridad.

Nota

El encabezado fileapi.h define CreateFile como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos


Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	fileapi.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll