Función IoCreateFile (wdm.h)

Artículo
08/08/2023

La rutina IoCreateFile hace que se cree un nuevo archivo o directorio, o bien abre un archivo, un dispositivo, un directorio o un volumen existentes, lo que proporciona al autor de la llamada un identificador para el objeto de archivo.

Sintaxis

NTSTATUS IoCreateFile(
  [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              Disposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength,
  [in]           CREATE_FILE_TYPE   CreateFileType,
  [in, optional] PVOID              InternalParameters,
  [in]           ULONG              Options
);

Parámetros

[out] FileHandle

Puntero a una variable que recibe el identificador de archivo si la llamada se realiza correctamente. El controlador debe cerrar el controlador con ZwClose una vez que el controlador ya no esté en uso.

[in] DesiredAccess

Máscara de bits de marcas que especifican el tipo de acceso al archivo o directorio que requiere el autor de la llamada. Consulte el parámetro DesiredAccess de IoCreateFileEx para obtener más información sobre este parámetro y para obtener la lista de valores de marca.

[in] ObjectAttributes

Puntero a una estructura OBJECT_ATTRIBUTES opaca que ya se ha inicializado con InitializeObjectAttributes. Consulte el parámetro ObjectAttributes de IoCreateFileEx para obtener más información y para obtener una descripción de cada miembro de estructura.

[out] IoStatusBlock

Puntero a una estructura de IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación solicitada. Consulte el parámetro IoStatusBlock de IoCreateFileEx.

[in, optional] AllocationSize

Opcionalmente, especifica el 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

Los atributos especificados explícitamente solo se aplican cuando el archivo se crea, reemplaza o, en algunos casos, se sobrescribe. De forma predeterminada, este valor es FILE_ATTRIBUTE_NORMAL, que se puede invalidar mediante una combinación de ORed de una o varias marcas FILE_ATTRIBUTE_XXX , que se definen en Wdm.h. Para obtener una lista de marcas que se pueden usar con IoCreateFile, consulte CreateFile.

[in] ShareAccess

Especifica el tipo de acceso compartido al archivo que el autor de la llamada requiere, como cero o uno, o una combinación de las marcas. Consulte el parámetro ShareAccess de IoCreateFileEx para obtener más detalles y para obtener la lista de marcas.

[in] Disposition

Especifica un valor que determina la acción que se va a realizar, en función de si el archivo ya existe. Consulte el parámetro Disposition de IoCreateFileEx para obtener la lista de valores posibles.

[in] CreateOptions

Especifica las opciones que se van a aplicar al crear o abrir el archivo. Este parámetro es una combinación compatible de las marcas enumeradas y descritas en el parámetro CreateOptions de IoCreateFileEx.

[in, optional] EaBuffer

En el caso de los controladores intermedios y del dispositivo, este parámetro debe ser un puntero NULL .

[in] EaLength

En el caso de los controladores intermedios y del dispositivo, este parámetro debe ser cero.

[in] CreateFileType

Los controladores deben establecer este parámetro en CreateFileTypeNone.

[in, optional] InternalParameters

Los controladores deben establecer este parámetro en NULL.

[in] Options

Especifica las opciones que se usarán durante la creación de la solicitud de creación. Consulte el parámetro Options de IoCreateFileEx para obtener la lista de opciones posibles.

Valor devuelto

IoCreateFile devuelve STATUS_SUCCESS o un estado de error adecuado. Valor NTSTATUS. Consulte la sección Valor devuelto de IoCreateFileEx para obtener una lista de posibles códigos de retorno.

Comentarios

La rutina IoCreateFileEx es similar a la rutina IoCreateFile , pero proporciona una mayor funcionalidad que la rutina IoCreateFile , incluido el acceso a parámetros de creación adicionales (ECP), objetos de dispositivo e información de transacciones.

Las llamadas posteriores pueden usar el identificador obtenido por IoCreateFile 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 IoCreateFile:

Como nombre de ruta de acceso completo, proporcionado en el miembro ObjectName de la entrada ObjectAttributes
Como pathname relativo al archivo de directorio representado por el identificador en el miembro RootDirectory de la entrada ObjectAttributes

Algunas marcas y combinaciones de marcas desiredAccess tienen los siguientes efectos:

Para que un autor de llamada sincronice una finalización de E/S esperando a que se devuelva FileHandle, se debe establecer la marca SYNCHRONIZE. De lo contrario, un autor de llamada que sea un dispositivo o controlador intermedio debe sincronizar una finalización de E/S mediante un objeto de evento.
Si solo se establecen las marcas 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 extenderá 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 y SYNCHRONIZE, el autor de la llamada no puede leer ni escribir directamente ningún dato en el archivo mediante el fileHandle devuelto: es decir, todas las operaciones del archivo se producen a través del buscapersonas del sistema en respuesta a las instrucciones y a los accesos a datos. Los controladores intermedios y de dispositivo no deben establecer la marca FILE_EXECUTE en DesiredAccess.

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 la llamada original de IoCreateFile no especifica FILE_SHARE_READ, FILE_SHARE_WRITE o FILE_SHARE_DELETE, no se puede realizar ninguna otra operación abierta en el archivo: es decir, el autor de la llamada original tiene acceso exclusivo al archivo.

Para que un archivo compartido se abra correctamente, el desiredAccess solicitado al archivo debe ser compatible con las especificaciones DesiredAccess y ShareAccess de todas las aperturas anteriores que aún no se han publicado con ZwClose. Es decir, el DesiredAccess especificado en IoCreateFile para un archivo determinado no debe entrar en conflicto con los accesos a los que otros abiertores del archivo no se han permitido.

El valor Disposition FILE_SUPERSEDE requiere que el autor de la llamada tenga acceso DELETE a un objeto de archivo existente. Si es así, una llamada correcta a IoCreateFile con FILE_SUPERSEDE en un archivo existente elimina ese archivo y, a continuación, lo vuelve a crear. Esto implica que, si otro subproceso ya ha abierto el archivo, abrió el archivo especificando un parámetro de ShareAccesscon 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 disposición FILE_OVERWRITE_IF y FILE_SUPERSEDE son similares. Si se llama a IoCreateFile con un archivo existente y cualquiera de estos valores Disposition , el archivo se reemplazará.

La sobrescritura de 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 la entrada de ShareAccess.
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 IoCreateFile no puede deshabilitar las marcas de FileAttributes existentes, pero puede habilitar marcas adicionales para el mismo archivo.

El valor de createOptions FILE_DIRECTORY_FILE 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 del sistema de archivos en particular. 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 valor CreateOptions o Disposition incoherente, se producirá un error en la llamada a IoCreateFile .

La marca CreateOptions FILE_NO_INTERMEDIATE_BUFFERING impide que el sistema de archivos realice cualquier 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 las rutinas ZwXxxFile , incluidas las siguientes:

Cualquier ByteOffset opcional pasado a ZwReadFile o ZwWriteFile debe ser una parte integral del tamaño del sector.
La longitud pasada a ZwReadFile o ZwWriteFile debe ser una parte integral 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 alinearse de acuerdo con el requisito de alineación del dispositivo subyacente. Esta información se puede obtener llamando a IoCreateFile para obtener un identificador para el objeto de archivo que representa el dispositivo físico y, a continuación, llamando a ZwQueryInformationFile con ese identificador. Para obtener una lista de los valores del sistema FILE_XXX_ALIGNMENT, consulte DEVICE_OBJECT.
Las llamadas a ZwSetInformationFile con el parámetro FileInformationClass establecido en FilePositionInformation deben especificar un desplazamiento que sea una parte integral del tamaño del sector.

Los FILE_SYNCHRONOUS_IO_ALERT CreateOptions y FILE_SYNCHRONOUS_IO_NONALERT, que se excluyen mutuamente como sus nombres sugieren, especifican que todas las operaciones de E/S del archivo deben ser sincrónicas siempre y cuando se produzcan a través del objeto de archivo al que hace referencia el FileHandle devuelto. Todas las E/S de este tipo de archivo se serializan en todos los subprocesos mediante el identificador devuelto. Con cualquiera de estas opciones CreateOptions, se debe establecer la marca DesiredAccess SYNCHRONIZE para que el administrador de E/S use el objeto de archivo como un objeto de sincronización. Con cualquiera de estos conjuntos CreateOptions , el administrador de E/S mantiene el "contexto de posición de archivo" para el objeto de archivo, un desplazamiento de posición de archivo interno y actual. Este desplazamiento se puede usar en llamadas a ZwReadFile y ZwWriteFile. Su posición también se puede consultar o establecer con ZwQueryInformationFile y ZwSetInformationFile.

Si no se especifica la marca CreateOptions FILE_OPEN_REPARSE_POINT y IoCreateFile intenta abrir un archivo con un punto de reanálisis, se produce el procesamiento normal del punto de reanálisis para el archivo. Si, por otro lado, se especifica la marca FILE_OPEN_REPARSE_POINT, no se produce el procesamiento de reanálisis normal y IoCreateFile intenta abrir directamente el archivo de punto de reanálisis. En cualquier caso, si la operación de apertura se realizó correctamente, IoCreateFile devuelve STATUS_SUCCESS; de lo contrario, la rutina devuelve un código de error NTSTATUS. IoCreateFile nunca devuelve STATUS_REPARSE.

La marca CreateOptions FILE_OPEN_REQUIRING_OPLOCK elimina el tiempo entre abrir el archivo y solicitar un interbloqueo que podría permitir que un tercero abra el archivo y obtenga una infracción de uso compartido. Una aplicación puede usar la marca FILE_OPEN_REQUIRING_OPLOCK en IoCreateFile y, a continuación, solicitar cualquier interbloqueo. Esto garantiza que un propietario de oplock recibirá una notificación de cualquier solicitud abierta posterior que provoque una infracción de uso compartido.

En Windows 7, si existen otros identificadores en el archivo cuando una aplicación usa la marca FILE_OPEN_REQUIRING_OPLOCK, 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 la marca FILE_OPEN_REQUIRING_OPLOCK 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 bloqueo de operación. Del mismo modo, si esta llamada se realiza correctamente, pero se produce un error en la solicitud de interbloqueo posterior, una aplicación que usa esta marca debe cerrar su identificador después de detectar que se ha producido un error en la solicitud de interbloqueo.

La marca FILE_OPEN_REQUIRING_OPLOCK está disponible en Windows 7, Windows Server 2008 R2 y versiones posteriores de Windows. Los sistemas de archivos de Microsoft que implementan esta marca en Windows 7 son NTFS, FAT y exFAT.

La marca CreateOptions , FILE_RESERVE_OPFILTER, permite que una aplicación solicite un oplock de nivel 1, lote o filtro para evitar que otras aplicaciones obtengan infracciones de recursos compartidos. Sin embargo, FILE_RESERVE_OPFILTER solo es útil para los interbloqueos de filtro. Para usarlo, debe seguir estos pasos:

Emita una solicitud de creación con CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess de exactamente FILE_READ_ATTRIBUTES y ShareAccess de exactamente FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Si ya hay identificadores abiertos, se produce un error en la solicitud de creación con STATUS_OPLOCK_NOT_GRANTED y también se produce un error en el siguiente bloqueo de operación solicitado.
- Si abre con más acceso o menos uso compartido también provocará un error de 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.

El paso 3 hace que esto sea práctico solo para los interbloqueos de filtro. El identificador abierto en el paso 3 puede tener un desiredAccess que contenga un máximo de FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL y aún no interrumpen un interbloqueo de filtro. Sin embargo, cualquier DesiredAccess mayor que FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE interrumpirá un interbloqueo de nivel 1 o por lotes y hará que el FILE_RESERVE_OPFILTER marca sea inútil para esos tipos de interbloqueo.

Las opciones IO_NO_PARAMETER_CHECKING marca pueden ser útiles si un controlador emite una solicitud de creación en modo kernel en nombre de una operación iniciada por una aplicación en modo de usuario. Dado que la solicitud se produce dentro de un contexto de modo de usuario, el administrador de E/S, de forma predeterminada, sondea los valores de parámetro proporcionados, lo que puede provocar una infracción de acceso si los parámetros son direcciones en modo kernel. Esta marca permite al autor de la llamada invalidar este comportamiento predeterminado y evitar la infracción de acceso.

Para crear solicitudes que se originan en modo de usuario, si el controlador establece IO_NO_PARAMETER_CHECKING y IO_FORCE_ACCESS_CHECK en el parámetro Options de IoCreateFile , también debe establecer OBJ_FORCE_ACCESS_CHECK en el parámetro ObjectAttributes . Para obtener información sobre esta marca, consulta el miembro Attributes de OBJECT_ATTRIBUTES.

NTFS es el único sistema de archivos de Microsoft que implementa FILE_RESERVE_OPFILTER.

Las rutinas de controlador que se ejecutan en un contexto de proceso distinto del del proceso del sistema deben establecer el atributo OBJ_KERNEL_HANDLE para el parámetro ObjectAttributes de IoCreateFile. Esto restringe el uso del identificador devuelto por IoCreateFile a los procesos que solo se ejecutan en modo kernel. De lo contrario, el proceso puede acceder al identificador en cuyo contexto se ejecuta el controlador. Los controladores pueden llamar a InitializeObjectAttributes para establecer el atributo OBJ_KERNEL_HANDLE como se indica a continuación.

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)