Función NtCreateFile (winternl.h)
Crea un nuevo archivo o directorio, o abre un archivo, dispositivo, directorio o volumen existente.
Esta función es el modo de usuario equivalente a la función de ZwCreateFile documentada en el Kit de controladores de Windows (WDK).
Sintaxis
__kernel_entry NTSTATUS NtCreateFile(
[out] PHANDLE FileHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in, optional] PLARGE_INTEGER AllocationSize,
[in] ULONG FileAttributes,
[in] ULONG ShareAccess,
[in] ULONG CreateDisposition,
[in] ULONG CreateOptions,
[in] PVOID EaBuffer,
[in] ULONG EaLength
);
Parámetros
[out] FileHandle
Puntero a una variable que recibe el identificador de archivo si la llamada se realiza correctamente.
[in] DesiredAccess
Valor ACCESS_MASK que expresa el tipo de acceso que requiere el autor de la llamada al archivo o directorio. El conjunto de marcas de
Los autores de llamadas de NtCreateFile pueden especificar una o una combinación de lo siguiente, posiblemente usando un OR bit a bit con marcas compatibles adicionales de la lista de marcas de DesiredAccess, para cualquier objeto de archivo que no represente un archivo de directorio.
El valor de FILE_GENERIC_EXECUTE es irrelevante para los controladores intermedios y del dispositivo.
El STANDARD_RIGHTS_XXX son valores del sistema predefinidos que se usan para aplicar la seguridad en los objetos del sistema.
Para abrir o crear un archivo de directorio, como también se indica con el parámetro CreateOptions
[in] ObjectAttributes
Puntero a una estructura ya inicializada con InitializeObjectAttributes. Los miembros de esta estructura para un objeto de archivo incluyen lo siguiente.
| Valor | Significado |
|---|---|
|
Especifica el número de bytes de ObjectAttributes datos proporcionados. Este valor debe ser al menos sizeof(OBJECT_ATTRIBUTES). |
|
Opcionalmente, especifica un identificador de un directorio obtenido por una llamada anterior a NtCreateFile. Si este valor es NULL, el miembro ObjectName debe ser una especificación de archivo completa que incluya la ruta de acceso completa al archivo de destino. Si este valor no esNULL, el miembro ObjectName especifica un nombre de archivo relativo a este directorio. |
|
Apunta a una cadena Unicode almacenada en búfer que asigna un nombre al archivo que se va a crear o abrir. Este valor debe ser una especificación de archivo completa o el nombre de un objeto de dispositivo, a menos que sea el nombre de un archivo relativo al directorio especificado por RootDirectory. Por ejemplo, \Device\Floppy1\myfile.dat o \?? \B:\myfile.dat podría ser la especificación de archivo completa, siempre que el controlador de disquete y el sistema de archivos excesivamente cargado ya estén cargados. Para obtener más información, vea nombres de archivo, rutas de acceso y espacios de nombres. |
|
Es un conjunto de marcas que controla los atributos del objeto de archivo. Este valor puede ser cero o OBJ_CASE_INSENSITIVE, lo que indica que el código de búsqueda de nombres debe ignorar el caso del ObjectName miembro en lugar de realizar una búsqueda exacta de coincidencias. El valor OBJ_INHERIT es irrelevante para los controladores intermedios y del dispositivo. |
|
Opcionalmente, especifica un descriptor de seguridad que se va a aplicar a un archivo. Las ACL especificadas por este descriptor de seguridad se aplican al archivo solo cuando se crea. Si el valor es NULL cuando se crea un archivo, la ACL colocada en el archivo depende del sistema de archivos; la mayoría de los sistemas de archivos propagan parte de dicha ACL desde el archivo de directorio primario combinado con la ACL predeterminada del autor de la llamada. Los controladores intermedios y de dispositivo pueden establecer este miembro en NULL. |
|
Especifica los derechos de acceso que debe proporcionar un servidor al contexto de seguridad del cliente. Este valor no esNULL solo cuando se establece una conexión a un servidor protegido, lo que permite al autor de la llamada controlar qué partes del contexto de seguridad del autor de la llamada están disponibles para el servidor y si el servidor puede suplantar al autor de la llamada. |
[out] IoStatusBlock
Puntero a una variable que recibe el estado de finalización final e información sobre la operación solicitada. Al devolver de
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
[in, optional] AllocationSize
Tamaño de asignación inicial en bytes para el archivo. Un valor distinto de cero no tiene ningún efecto a menos que se cree, sobrescriba o sustituya el archivo.
[in] FileAttributes
Atributos de archivo. Los atributos especificados explícitamente solo se aplican cuando se crea, reemplaza o, en algunos casos, se sobrescribe el archivo. De forma predeterminada, este valor es un FILE_ATTRIBUTE_NORMAL, que se puede invalidar mediante una combinación de ORed de una o varias marcas de FILE_ATTRIBUTE_xxxx, que se definen en Wdm.h y NtDdk.h. Para obtener una lista de marcas que se pueden usar con NtCreateFile, vea CreateFile.
[in] ShareAccess
Tipo de acceso compartido que el autor de la llamada desea usar en el archivo, como cero, o como una o una combinación de los valores siguientes.
Para obtener más información, consulte Windows SDK.
[in] CreateDisposition
Especifica qué hacer, en función de si el archivo ya existe, como uno de los valores siguientes.
[in] CreateOptions
Las opciones que se aplicarán al crear o abrir el archivo, como una combinación compatible de las marcas siguientes.
[in] EaBuffer
Puntero a un búfer de EA usado para pasar atributos extendidos.
[in] EaLength
Longitud del búfer de EA.
Valor devuelto
NtCreateFile devuelve STATUS_SUCCESS o un estado de error adecuado. Si devuelve un estado de error, el autor de la llamada puede encontrar más información sobre la causa del error comprobando el IoStatusBlock. Para simplificar esta comprobación, una aplicación puede usar las macros NT_SUCCESS, NT_ERRORy NT_WARNING.
Observaciones
El identificador, proporcionado por NtCreateFile, se puede usar mediante llamadas posteriores para manipular datos dentro del archivo o el estado o los atributos del objeto de archivo.
Hay dos maneras alternativas de especificar el nombre del archivo que se va a crear o abrir con NtCreateFile:
- Como nombre de ruta de acceso completo, proporcionado en el ObjectName miembro de la entrada ObjectAttributes
- Como nombre de ruta de acceso relativo al archivo de directorio representado por el identificador del miembro RootDirectory de la entrada ObjectAttributes
Algunos DesiredAccess marcas y combinaciones de marcas tienen los siguientes efectos:
- Para que un autor de llamada sincronice una finalización de E/S esperando el FileHandle devuelto, se debe establecer la marca SYNCHRONIZE.
- Pasar un cero a desiredFlags no es válido.
- Si solo se establecen las marcas de FILE_APPEND_DATA y SYNCHRONIZE, el autor de la llamada solo puede escribir al final del archivo y se omite cualquier información de desplazamiento sobre las escrituras en el archivo. Sin embargo, el archivo se extiende automáticamente según sea necesario para este tipo de operación de escritura.
- Establecer la marca FILE_WRITE_DATA para un archivo también permite que se produzcan escrituras más allá del final del archivo. El archivo también se extiende automáticamente para este tipo de escritura.
- Si solo se establecen las marcas
FILE_EXECUTE ySYNCHRONIZE , el autor de la llamada no puede leer ni escribir directamente ningún dato en el archivo mediante elFileHandle devuelto, es decir, todas las operaciones del archivo se producen a través del buscapersonas del sistema en respuesta a las instrucciones y los accesos a datos.
El parámetro ShareAccess determina si los subprocesos independientes pueden tener acceso al mismo archivo, posiblemente simultáneamente. Siempre que ambos abiertores de archivos tengan el privilegio de acceder a un archivo de la manera especificada, el archivo se puede abrir y compartir correctamente. Si el autor de llamada original de ntCreateFile no especifica FILE_SHARE_READ, FILE_SHARE_WRITEo FILE_SHARE_DELETE, no se puede realizar ninguna otra operación abierta en el archivo; es decir, al autor de la llamada original se le concede acceso exclusivo al archivo.
Para que un archivo compartido se abra correctamente, el parámetro
El valor CreateDispositionFILE_SUPERSEDE requiere que el autor de la llamada tenga acceso DELETE a un objeto de archivo existente. Si es así, una llamada correcta a NtCreateFile con FILE_SUPERSEDE en un archivo existente elimina ese archivo y, a continuación, vuelve a crearlo. Esto implica que, si otro subproceso ya ha abierto el archivo, abrió el archivo especificando un parámetro ShareAccess con la marca FILE_SHARE_DELETE establecida.
Tenga en cuenta que este tipo de disposición es coherente con el estilo POSIX de sobrescribir archivos. Los valores de CreateDispositionFILE_OVERWRITE_IF y FILE_SUPERSEDE son similares. Si se llama
Sobrescribir un archivo es semánticamente equivalente a una operación de sustitución, excepto por lo siguiente:
- El autor de la llamada debe tener acceso de escritura al archivo, en lugar de eliminar el acceso. Esto implica que, si otro subproceso ya ha abierto el archivo, abrió el archivo con la marca FILE_SHARE_WRITE establecida en el parámetro ShareAccess de entrada.
- Los atributos de archivo especificados son lógicamente ORed con los que ya están en el archivo. Esto implica que, si otro subproceso ya ha abierto el archivo, un llamador posterior de NtCreateFile no puede deshabilitar las marcas existentes FileAttributes, pero puede habilitar marcas adicionales para el mismo archivo. Tenga en cuenta que este estilo de sobrescribir archivos es coherente con los sistemas operativos MS-DOS, Windows 3.1 y OS/2.
El valor deFILE_DIRECTORY_FILE CreateOptions especifica que el archivo que se va a crear o abrir es un archivo de directorio. Cuando se crea un archivo de directorio, el sistema de archivos crea una estructura adecuada en el disco para representar un directorio vacío para la estructura en disco de ese sistema de archivos concreto. Si se especificó esta opción y el archivo especificado que se va a abrir no es un archivo de directorio, o si el autor de la llamada especificó un CreateOptions o valor CreateDisposition, se produce un error en la llamada a NtCreateFile.
La marca CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING impide que el sistema de archivos realice un almacenamiento en búfer intermedio en nombre del autor de la llamada. Al especificar este valor, se aplican ciertas restricciones a los parámetros del autor de la llamada a otras rutinas de NtXXXFile, incluidas las siguientes:
- Cualquier ByteOff set opcional que se pase al NtReadFile o función de NtWriteFile debe ser una parte integral del tamaño del sector.
- El longitud
pasado a NtReadFile o ntWriteFile , debe ser un entero del tamaño del sector. Tenga en cuenta que especificar una operación de lectura en un búfer cuya longitud es exactamente el tamaño del sector podría dar lugar a un número menor de bytes significativos que se transfieren a ese búfer si se alcanzó el final del archivo durante la transferencia. - Los búferes deben ajustarse de acuerdo con el requisito de alineación del dispositivo subyacente. Esta información se puede obtener llamando a NtCreateFile para obtener un identificador para el objeto de archivo que representa el dispositivo físico y, a continuación, llamando a NtQueryInformationFile con ese identificador. Para obtener una lista de los valores del sistema FILE_XXX_ALIGNMENT, consulte la documentación de Windows SDK.
- Las llamadas a NtSetInformationFile con el parámetro FileInformationClass establecido en FilePositionInformation deben especificar un desplazamiento que sea un entero del tamaño del sector.
Si el parámetro CreateOptions especifica la marca de FILE_OPEN_REPARSE_POINT y NtCreateFile abre un archivo con un punto de reanálisis, no se produce el procesamiento de reanálisis normal y NtCreateFile intenta abrir directamente el archivo de punto de reanálisis. Si no se especifica la marca FILE_OPEN_REPARSE_POINT, el procesamiento normal de puntos de reanálisis se produce para el archivo. En cualquier caso, si la operación de apertura se realizó correctamente, NtCreateFile devuelve STATUS_SUCCESS; de lo contrario, un código de error. La función
El marca de FILE_OPEN_REQUIRING_OPLOCK del parámetro CreateOptions elimina el tiempo entre el momento en que abre el archivo y solicita un interbloqueo que podría permitir que un tercero abra el archivo, lo que provocaría una infracción de uso compartido. Una aplicación puede usar la marca de
En Windows 7, si existen otros identificadores en el archivo cuando una aplicación usa esta marca, se producirá un error en la operación de creación con STATUS_OPLOCK_NOT_GRANTED. Esta restricción ya no existe a partir de Windows 8.
Si esta operación de creación interrumpiría un interbloqueo que ya existe en el archivo, al establecer la marca FILE_OPEN_REQUIRING_OPLOCK se producirá un error en la operación de creación con STATUS_CANNOT_BREAK_OPLOCK. Esta operación de creación no romperá el interbloqueo existente.
Una aplicación que use esta marca debe solicitar un interbloqueo después de que esta llamada se realice correctamente, o todos los intentos posteriores de abrir el archivo se bloquearán sin la ventaja del procesamiento normal del interbloqueo. Del mismo modo, si esta llamada se realiza correctamente, pero se produce un error en la solicitud de interbloqueo posterior, una aplicación que use esta marca debe cerrar su identificador después de detectar que se ha producido un error en la solicitud de interbloqueo.
La marca
- Emita una solicitud de creación con createOptions de FILE_RESERVE_OPFILTER, DesiredAccess de exactamente FILE_READ_ATTRIBUTESy shareAccess de exactamente
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE). Los posibles errores son los siguientes:- Si ya hay identificadores abiertos, se produce un error en la solicitud de creación con STATUS_OPLOCK_NOT_GRANTEDy también se produce un error en el siguiente interbloqueo solicitado.
- Si abre con más acceso que FILE_READ_ATTRIBUTES o menos uso compartido que
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE), se produce un error en la solicitud con STATUS_OPLOCK_NOT_GRANTED.
- Si la solicitud de creación se realiza correctamente, solicite un interbloqueo.
- Abra otro identificador en el archivo para realizar E/S.
(FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL) y que todavía no interrumpa un interbloqueo de filtro. Sin embargo, cualquier DesiredAccess mayor que (FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE) interrumpirá un interbloqueo de nivel 1 o batch y hará que la marca de FILE_RESERVE_OPFILTER sea inútil para esos tipos de interbloqueo.
NTFS es el único sistema de archivos de Microsoft que implementa FILE_RESERVE_OPFILTER.
Para obtener más información sobre los interbloqueos, vea bloqueos oportunistas.
Tenga en cuenta que el archivo de encabezado de WDK NtDef.h es necesario para muchas definiciones de constantes, así como para la macro InitializeObjectAttributes. También puede usar las funciones de LoadLibrary y GetProcAddress para vincular dinámicamente a NtDll.dll.
Requisitos
| Requisito | Valor |
|---|---|
| de la plataforma de destino de |
Windows |
| encabezado de |
winternl.h |
| biblioteca de |
ntdll.lib |
| DLL de |
ntdll.dll |