Función CreateFileA (fileapi.h)
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 CreateFileTransacted
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.
De forma predeterminada, el nombre se limita a MAX_PATH caracteres. Para ampliar este límite a 32 767 caracteres anchos, anteponga "\\?\\ " a la ruta de acceso. Para obtener más información, vea Archivos de nomenclatura, rutas de acceso y espacios de nombres.
Propina
A partir de Windows 10, versión 1607, puedes optar por quitar la limitación del MAX_PATH sin tener que prepending "\\?\". Consulte la sección "Limitación máxima de longitud de ruta de acceso" de Archivos de nomenclatura, rutas de acceso y espacios de nombres para obtener más información.
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, consulte secuencias de archivos.
[in] dwDesiredAccess
Acceso solicitado al archivo o dispositivo, que se puede resumir como 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 acceso y seguridad de archivos, constantes de derechos de acceso a archivosy 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 el acceso GENERIC_READ.
No se puede solicitar un modo de acceso que entra en conflicto con el modo de uso compartido especificado por el parámetro dwShareMode en una solicitud abierta que ya tiene un identificador abierto.
Para obtener más información, vea la sección Comentarios de este tema y crear y abrir 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.
Para habilitar un proceso para compartir un archivo o dispositivo mientras otro proceso tiene 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.
[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 se puede heredar 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, al archivo o dispositivo asociado al identificador devuelto se le asigna un descriptor de seguridad predeterminado.
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 va a realizar en un archivo o dispositivo que existe o no existe.
En el caso de los dispositivos que no sean archivos, este parámetro normalmente se establece 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:
[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 FILE_ATTRIBUTE_* valores.
Este parámetro también puede contener información de calidad de seguridad del servicio (SQOS) especificando la marca SECURITY_SQOS_PRESENT. La información adicional sobre marcas relacionadas con SQOS se presenta en la tabla siguiendo los atributos y las tablas de marcas.
Para obtener acceso más avanzado a los atributos de archivo, consulte SetFileAttributes. Para obtener una lista completa de todos los atributos de archivo con sus valores y descripciones, vea constantes de atributos de archivo.
| Atributo | Significado |
|---|---|
|
El archivo debe archivarse. Las aplicaciones usan este atributo para marcar los archivos de copia de seguridad o eliminación. |
|
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, consulte 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. |
|
El archivo está oculto. No lo incluya en una lista de directorios normal. |
|
El archivo no tiene otros atributos establecidos. Este atributo solo es válido si se usa solo. |
|
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. Este atributo lo usa Almacenamiento remoto, el software de administración de almacenamiento jerárquico. Las aplicaciones no deben cambiar arbitrariamente este atributo. |
|
El archivo es de solo lectura. Las aplicaciones pueden leer el archivo, pero no pueden escribir en él ni eliminarlo. |
|
El archivo forma parte o se usa exclusivamente por un sistema operativo. |
|
El archivo se usa para el almacenamiento temporal.
Para obtener más información, consulte la sección comportamiento de almacenamiento en caché de |
| Bandera | Significado |
|---|---|
|
El archivo se abre o crea para una operación de copia de seguridad o restauración. El sistema garantiza que el proceso de llamada invalida 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. Un identificador de directorio se puede pasar a algunas funciones en lugar de un identificador de archivo. Para obtener más información, vea la sección Comentarios. |
|
El archivo se va a eliminar inmediatamente después de que se cierren todos sus identificadores, 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 recurso compartido de FILE_SHARE_DELETE. Se produce un error en las solicitudes abiertas posteriores del archivo, a menos que se especifique el modo de recurso compartido de FILE_SHARE_DELETE. |
|
El archivo o dispositivo se está abriendo sin almacenamiento en caché del sistema para 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 de almacenamiento en búfer de archivos. |
|
Los datos del archivo se solicitan, pero deben seguir estando ubicados en el almacenamiento remoto. No debe transportarse de vuelta al almacenamiento local. Esta marca la usan los sistemas de almacenamiento remoto. |
|
No se producirá el procesamiento normal 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. |
|
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 sobre el uso de un identificador de archivo creado con esta marca, consulte la sección identificadores de E/S sincrónicos y asincrónicos de este tema. |
|
El acceso se producirá según las reglas POSIX. Esto incluye permitir varios archivos con nombres, que solo difieren en el caso, para 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. |
|
El acceso está pensado para ser aleatorio. El sistema puede usarlo como sugerencia para optimizar el almacenamiento en caché de archivos.
Esta marca no tiene ningún efecto si el sistema de archivos no admite la E/S almacenada en caché y FILE_FLAG_NO_BUFFERING. Para obtener más información, consulte la sección comportamiento de almacenamiento en caché de |
|
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 redirección USB remoteFX).
Esta marca no tiene ningún efecto para los autores de llamadas 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. |
|
El acceso está pensado para ser secuencial desde el principio hasta el final. El sistema puede usarlo como sugerencia para optimizar el almacenamiento en caché de archivos.
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é y FILE_FLAG_NO_BUFFERING. Para obtener más información, consulte la sección comportamiento de almacenamiento en caché de |
|
Las operaciones de escritura no pasarán a través de ninguna caché intermedia, pasarán directamente al disco.
Para obtener más información, consulte la sección comportamiento de almacenamiento en caché de |
El parámetro dwFlagsAndAttributes también puede especificar información de SQOS. Para obtener más información, consulte 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.
[in, optional] hTemplateFile
Identificador válido para un archivo de plantilla con el derecho de acceso GENERIC_READ. El archivo de plantilla proporciona atributos de archivo y atributos extendidos para el archivo que se está creando.
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 de cifrado de archivos .
Valor devuelto
Si la función se ejecuta 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.
Observaciones
CreateFile se desarrolló originalmente específicamente para la interacción de archivos, pero desde entonces se ha ampliado y mejorado para incluir la mayoría de 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 la palabra archivo solo cuando se hace referencia específicamente a los datos almacenados en un archivo real en un sistema de archivos. Sin embargo, algunos usos de archivo pueden referirse más generalmente a un objeto de E/S que admita mecanismos similares a archivos. Este uso liberal del término archivo es especialmente frecuente en nombres constantes y nombres de parámetros debido a las razones históricas mencionadas 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 los recursos del sistema, pero puede tener una influencia más amplia en cosas 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) OR'ed con cualquier otra marca de acceso, y el archivo o directorio remoto no se han abierto con FILE_SHARE_DELETE. Para evitar la infracción de uso compartido en este escenario, abra el archivo o directorio remoto con el derecho de acceso delete solo 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 compresión o 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 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 archivosy 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 más adelante 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 acees heredables.
Como se indicó anteriormente, si el parámetro lpSecurityAttributes es NULL, el identificador devuelto por CreateFile no puede ser heredado por ningún proceso secundario que la aplicación pueda crear. 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 para 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 archivos y directorios para el miembro lpSecurityDescriptor para que tenga un efecto en ellos, que se puede determinar mediante GetVolumeInformation.
| Tecnología | Soportado |
|---|---|
| Protocolo bloque de mensajes del servidor (SMB) 3.0 | Sí |
| 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) | Sí |
| Sistema de archivos resistente (ReFS) | Sí |
Tenga en cuenta que createFile con eliminación de sustitución producirá un error si se realiza en un archivo en el que ya hay un flujo de datos alternativo abierto.
comportamiento de vínculo simbólico de
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 del 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_EXISTINGo FILE_FLAG_DELETE_ON_CLOSE, el archivo afectado es el destino.
Comportamiento de almacenamiento en caché de
El sistema usa varios de los valores posibles para el parámetro dwFlagsAndAttributesCreateFile para controlar o afectar a la forma en que el sistema almacena en caché los datos asociados con el identificador. Son:- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
Algunas de estas marcas no deben combinarse. Por ejemplo, combinar FILE_FLAG_RANDOM_ACCESS con FILE_FLAG_SEQUENTIAL_SCAN es la auto-derrota.
La especificación de la marca FILE_FLAG_SEQUENTIAL_SCAN puede aumentar el rendimiento de las aplicaciones que leen archivos grandes mediante acceso secuencial. Las mejoras de rendimiento pueden ser aún más notables para las aplicaciones que leen archivos grandes principalmente secuencialmente, pero ocasionalmente omiten hacia delante en pequeños intervalos 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 una 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 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 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.
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, lo que resulta de procesar 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 innecesarias de rendimiento. El uso de estas marcas conjuntamente evita esas penalizaciones. Para obtener información general sobre el almacenamiento en caché de archivos y metadatos, consulte 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 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
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 escribir 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 tanto, puede ser de preocupación para determinadas aplicaciones.
archivos de
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 corto/largo 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. Consulte 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 usar 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 la creación de 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 especificandoflujos de archivos de
En los sistemas de archivos NTFS, puede usar CreateFile para crear secuencias independientes dentro de un archivo. Para obtener más información, consulte secuencias de archivos.directorios de
Una aplicación no puede crear un directorio mediante CreateFile, por lo tanto, 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 de 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 GENERIC_READ derecho de acceso 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: acceso directo al disco o a un volumen no está restringido de esta manera.
Puede usar la función createFile de
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, vea En 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.
| Cuerda | 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 en el volumen y llame a la función DeviceIoControl
Para obtener un ejemplo de apertura de 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 una unidad de memoria flash), el lpFileName cadena 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.
| Cuerda | 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, vea Asignar nombre a 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 concreto, 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 requerir o no 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é.
dispositivo de Changer
Los códigos de control IOCTL_CHANGER_* para DeviceIoControl aceptan un identificador para un dispositivo de modificador. Para abrir un dispositivo de 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 de modificador cero en una aplicación escrita en C o C++, use el siguiente nombre de archivo: "\\.\Changer0".unidades de cinta de
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, vea backup.
Recursos de comunicaciones de
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 siguiente sintaxis: "\\.\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 Communications.
Consolas de
La función CreateFile puede crear un identificador para la entrada de la consola (CONIN$). Si el proceso tiene un identificador abierto para él 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. En el caso de 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 del 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 |
| lpSecurityAttributes |
Si desea que se herede la consola, el miembro |
| 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.
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.
canalizaciones de
Si CreateFile abre el final 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
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:
- anexar un archivo a otro archivo
- cancelar operaciones de E/S pendientes
- Crear un proceso secundario con de entrada y salida redirigidos
- crear y usar un de archivos temporales
- FSCTL_RECALL_FILE
- GetFinalPathNameByHandle
- bloqueo y desbloqueo de intervalos de bytes en archivos
- obtener un nombre de archivo de un identificador de archivo
- obtener información de reconocimiento del sistema de archivos
- abrir un archivo para leer o escribir
- recuperar el de tiempo de Last-Write
- SetFileInformationByHandle
- Pruebas para el final de un de archivo
- uso de fibras
- usar secuencias
- caminar un búfer de registros de diario de cambios
- Wow64DisableWow64FsRedirection
- Wow64EnableWow64FsRedirection
- llamada a DeviceIoControl
- configuración de un recurso de comunicaciones
-
Supervisión de eventos de comunicaciones de
- procesar una solicitud para quitar un de dispositivo
Trabajar con un mailslot se muestra en Escribir en unmailslot .
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 dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows XP [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows Server 2003 [solo aplicaciones de escritorio] |
| de la plataforma de destino de |
Windows |
| encabezado de |
fileapi.h (incluya Windows.h) |
| biblioteca de |
Kernel32.lib |
| DLL de |
Kernel32.dll |
Consulte también
Acerca de la administración de directorios
Acerca de la administración de volúmenes
de copia de seguridad de
de comunicaciones de
crear, eliminar y mantener archivos
de entrada y salida (IOCTL) del dispositivo
de compresión y descompresión de archivos
de cifrado de archivos de
funciones de administración de archivos
derechos de acceso y seguridad de archivos
flujos de archivos de
funciones de
de puertos de finalización de E/S de
obtener y establecer información de archivo
Temas de información general de
canalizaciones de