Función WriteFile (fileapi.h)

Para cancelar todas las operaciones de E/S asincrónicas pendientes, use:

• cancelIo: esta función cancela solo las operaciones emitidas por el subproceso de llamada para el identificador de archivo especificado.
• CancelIoEx: esta función cancela todas las operaciones emitidas por los subprocesos para el identificador de archivo especificado.

Las operaciones de E/S que se cancelan se completan con el error ERROR_OPERATION_ABORTED.

La función WriteFile de puede producir un error con ERROR_NOT_ENOUGH_QUOTA, lo que significa que el búfer del proceso de llamada no se pudo bloquear en páginas. Para obtener más información, vea SetProcessWorkingSetSize.

Si otro proceso bloquea parte del archivo y la operación de escritura se superpone a la parte bloqueada, writeFile produce un error.

Al escribir en un archivo, la hora de última escritura no se actualiza completamente hasta que se hayan cerrado todos los identificadores usados para escribir. Por lo tanto, para garantizar una hora de última escritura precisa, cierre el identificador de archivo inmediatamente después de escribir en el archivo.

El acceso al búfer de salida mientras una operación de escritura usa el búfer puede provocar daños en los datos escritos desde ese búfer. Las aplicaciones no deben escribir en, reasignar ni liberar el búfer de salida que usa una operación de escritura hasta que se complete la operación de escritura. Esto puede ser especialmente problemático cuando se usa un identificador de archivo asincrónico. Puede encontrar información adicional sobre los identificadores de archivos sincrónicos frente a asincrónicos más adelante en la sección sincronización y posición de archivo y de E/S asincrónica y asincrónica.

Tenga en cuenta que es posible que las marcas de tiempo no se actualicen correctamente para un archivo remoto. Para garantizar resultados coherentes, use E/S sin búfer.

El sistema interpreta cero bytes para escribir como especificar una operación de escritura nula y writeFile no trunca ni extiende el archivo. Para truncar o extender un archivo, use la función SetEndOfFile.

Los caracteres se pueden escribir en el búfer de pantalla mediante WriteFile con un identificador para la salida de la consola. El comportamiento exacto de la función viene determinado por el modo de consola. Los datos se escriben en la posición actual del cursor. La posición del cursor se actualiza después de la operación de escritura. Para obtener más información sobre los identificadores de consola, vea CreateFile.

Al escribir en un dispositivo de comunicaciones, el comportamiento de WriteFile viene determinado por el tiempo de espera de comunicación actual establecido y recuperado mediante las funciones setCommTimeouts y GetCommTimeouts. Los resultados imprevisibles pueden producirse si no se pueden establecer los valores de tiempo de espera. Para obtener más información sobre los tiempos de espera de comunicación, vea COMMTIMEOUTS.

Aunque una escritura de un solo sector es atómica, no se garantiza que una escritura de varios sectores sea atómica a menos que use una transacción (es decir, el identificador creado es un identificador de transacción; por ejemplo, un identificador creado mediante CreateFileTransacted). Es posible que las escrituras de varios sectores que se almacenan en caché no siempre se escriban en el disco de inmediato; por lo tanto, especifique FILE_FLAG_WRITE_THROUGH en CreateFile para asegurarse de que se escribe una escritura en todo el sector en el disco sin posibles retrasos en el almacenamiento en caché.

Si escribe directamente en un volumen que tiene un sistema de archivos montado, primero debe obtener acceso exclusivo al volumen. De lo contrario, corre el riesgo de provocar daños en los datos o inestabilidad del sistema, ya que las escrituras de la aplicación pueden entrar en conflicto con otros cambios procedentes del sistema de archivos y dejar el contenido del volumen en un estado incoherente. Para evitar estos problemas, se han realizado los siguientes cambios en Windows Vista y versiones posteriores:

• Una escritura en un identificador de volumen se realizará correctamente si el volumen no tiene un sistema de archivos montado o si se cumple una de las condiciones siguientes:
  • Los sectores en los que se va a escribir son sectores de arranque.
  • Los sectores que se van a escribir para residir fuera del espacio del sistema de archivos.
  • Ha bloqueado o desmontado explícitamente el volumen mediante FSCTL_LOCK_VOLUME o FSCTL_DISMOUNT_VOLUME.
  • El volumen no tiene ningún sistema de archivos real. (En otras palabras, tiene montado un sistema de archivos RAW).
• Una escritura en un identificador de disco se realizará correctamente si se cumple una de las condiciones siguientes:
  • Los sectores que se van a escribir no se encuentran dentro de las extensiones de un volumen.
  • Los sectores que se van a escribir para estar dentro de un volumen montado, pero se ha bloqueado o desmontado explícitamente el volumen mediante FSCTL_LOCK_VOLUME o FSCTL_DISMOUNT_VOLUME.
  • Los sectores que se van a escribir se encuentran dentro de un volumen que no tiene ningún sistema de archivos montado que no sea RAW.

Si hFile se abrió con FILE_FLAG_OVERLAPPED, se aplican las condiciones siguientes:

• El parámetro lpOverlapped debe apuntar a una estructura de superpuesta válida y única, de lo contrario, la función puede notificar incorrectamente que la operación de escritura está completa.
• El parámetro lpNumberOfBytesWritten debe establecerse en NULL. Para obtener el número de bytes escritos, use la función GetOverlappedResult. Si el parámetro hFile está asociado a un puerto de finalización de E/S, también puede obtener el número de bytes escritos llamando a la función GetQueuedCompletionStatus.

sincronización y posición de archivo

• writeFile puede devolver antes de que se complete la operación de escritura. En este escenario, WriteFile devuelve FALSE y la función getLastError devuelve ERROR_IO_PENDING, lo que permite que el proceso de llamada continúe mientras el sistema completa la operación de escritura.
• El parámetro lpOverlapped no debe ser NULL y debe usarse teniendo en cuenta los siguientes hechos:
  • Aunque el sistema establece y restablece automáticamente el evento especificado en el estructura SUPERPUESTA, el desplazamiento especificado en la estructura SUPERPUESTA no se actualiza automáticamente.
  • WriteFile restablece el evento a un estado no asignado cuando comienza la operación de E/S.
  • El evento especificado en la estructura superpuesta se establece en un estado señalado cuando se completa la operación de escritura; hasta ese momento, la operación de escritura se considera pendiente.
  • Dado que la operación de escritura se inicia en el desplazamiento especificado en la estructura superpuesta y WriteFile puede devolver antes de que se complete la operación de escritura en el nivel del sistema (pendiente de escritura), ni el desplazamiento ni ninguna otra parte de la estructura se deben modificar, liberar o reutilizar mediante la aplicación hasta que se señale el evento (es decir, la escritura se completa).

• Si lpOverlapped es NULL, la operación de escritura se inicia en la posición del archivo actual y WriteFile no devuelve hasta que se complete la operación y el sistema actualiza el puntero de archivo antes de WriteFile.
• Si lpOverlapped no es NULL, la operación de escritura se inicia en el desplazamiento especificado en la estructura superpuesta y WriteFile no devuelve hasta que se complete la operación de escritura. El sistema actualiza los campos SUPERPUESTOs interno e interno y el puntero de archivo antes de WriteFile.

canalizaciones de

Si el búfer de canalización está lleno cuando una aplicación usa la función WriteFile para escribir en una canalización, es posible que la operación de escritura no finalice inmediatamente. La operación de escritura se completará cuando una operación de lectura (mediante la función readFile ) hace que haya más espacio de búfer del sistema disponible para la canalización.

Al escribir en un controlador de canalización sin bloqueo, en modo de bytes con espacio de búfer insuficiente, WriteFile devuelve TRUE con *lpNumberOfBytesWritten<nNumberOfBytesToWrite.

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

Operaciones de transacción de

Ejemplos

Para obtener algunos ejemplos, vea Crear y usar un archivo temporal y Abrir un archivo para leer o escribir.

#include <windows.h>

#define ROUND_UP_SIZE(Value,Pow2) ((SIZE_T) ((((ULONG)(Value)) + (Pow2) - 1) & (~(((LONG)(Pow2)) - 1))))

#define ROUND_UP_PTR(Ptr,Pow2)  ((void *) ((((ULONG_PTR)(Ptr)) + (Pow2) - 1) & (~(((LONG_PTR)(Pow2)) - 1))))

int main()
{
   // Sample data
   unsigned long bytesPerSector = 65536; // obtained from the GetFreeDiskSpace function.
   unsigned long size = 15536; // Buffer size of your data to write.
   
   // Ensure you have one more sector than Size would require.
   size_t sizeNeeded = bytesPerSector + ROUND_UP_SIZE(size, bytesPerSector);
   
   // Replace this statement with any allocation routine.
   auto buffer = new uint8_t[SizeNeeded];
   
   // Actual alignment happens here.
   auto bufferAligned = ROUND_UP_PTR(buffer, bytesPerSector);

   // ... Add code using bufferAligned here.
   
   // Replace with corresponding free routine.
   delete buffer;
}

Requisitos

Consulte también

CancelIo

CancelIoEx

CancelSynchronousIo

CreateFile

CreateFileTransacted

funciones de administración de archivos

GetLastError

GetOverlappedResult

GetQueuedCompletionStatus

ReadFile

SetEndOfFile

WriteFileEx