| 术语 | writefile |
| 释义 | WriteFile 语法： C++ BOOL WINAPI WriteFile( __in HANDLE hFile, __in LPCVOID lpBuffer, __in DWORD nNumberOfBytesToWrite, __out_opt LPDWORD lpNumberOfBytesWritten, __inout_opt LPOVERLAPPED lpOverlapped ); WriteFile函数 数据写入到指定的文件或输入/输出(I / O)设备。发生在写入文件指针所指定的位置，如果处理指的是寻求设备。 此功能是专为同步和异步操作。对于纯粹为异步操作设计了一个类似的功能，见WriteFileEx。 参数 hFile [in] 句柄到文件或I / O设备(例如，一个文件，文件流，物理磁盘，卷，控制台缓冲区，磁带驱动器，插座，通信资源，邮筒，或管道)。 该hFile参数必须已创建的写访问。有关更多信息，请参阅通用访问权限和文件安全性和访问权限。 异步写入操作，hFile可以是任何处理与使用FILE_FLAG_OVERLAPPEDCreateFile国旗或套接字处理套接字或接受函数返回的功能打开。 lpBuffer [in] 甲到缓冲区包含要写入到文件或设备的数据指针。 这个缓冲区必须始终有效写操作的时间。调用者不能使用此缓冲区，直到写入操作完成。 nNumberOfBytesToWrite [in] 的字节数写入文件或设备。 为零值指定一个空写操作。一个空的行为写操作依赖于底层的文件系统或通信技术。 管写通过网络被限制为65,535每写字节操作。欲了解更多有关管道，请参见备注部分。 lpNumberOfBytesWritten [指出，可选] 一个指针变量接收书面当使用同步hFile参数的字节数。 WriteFile设置此值为0之前，做任何工作或错误检查。使用NULL如果这是一个异步操作，以避免潜在的错误结果这个参数。 此参数可以是NULL只有当lpOverlapped参数不是NULL。 有关详细信息，请参见备注部分。 lpOverlapped [中，指出，可选] 一个OVERLAPPED结构的指针则需要的hFile参数开幕，FILE_FLAG_OVERLAPPED，否则此参数可以为NULL。 对于hFile，支持字节偏移，如果您使用此参数，您必须指定偏移量开始写入文件或设备一个字节。这抵消通过设置指定的偏移和OVERLAPPED结构OffsetHigh成员。对于hFile不支持字节偏移，偏移量和OffsetHigh被忽略。 若要写入文件结尾，同时指定胶印，作为0xFFFFFFFF的OVERLAPPED结构OffsetHigh成员。这在功能上等同先前调用CreateFile函数打开hFile使用FILE_APPEND_DATA访问。 如需有关lpOverlapped和FILE_FLAG_OVERLAPPED，请参见备注部分和同步和文件位置的信息条不同的组合。 返回值 如果函数成功，返回值为非零(真)。 如果函数失败，或正在完成异步返回值是零(假)。为了获得更多错误信息，调用GetLastError函数。 注意：GetLastError函数代码ERROR_IO_PENDING不是一个失败，它指定等待写入操作完成异步。有关更多信息，请参见备注。 备注 在WriteFile函数返回时，有下列情形之一发生： 的字节数的要求编写的。 读操作发布的管道的读结束缓冲空间(如果写被封锁)。有关更多信息，请参阅管道部分。 异步处理正在使用和正在发生的异步写入。 发生错误。 在WriteFile函数可能会失败，ERROR_INVALID_USER_BUFFER或ERROR_NOT_ENOUGH_MEMORY每当有太多的异步I / O请求。 要取消所有挂起的异步I / O操作，请使用： CancelIo，此功能取消由指定的文件句柄调用线程，只发给操作。 CancelIoEx，此功能取消了指定的文件处理线程发出的所有业务。 使用CancelSynchronousIo功能取消未完成的同步I / O操作。 I / O操作是取消与错误完全ERROR_OPERATION_ABORTED。 在WriteFile函数可能会失败，ERROR_NOT_ENOUGH_QUOTA，这意味着调用进程的缓冲区无法锁定页面。有关更多信息，请参阅SetProcessWorkingSetSize。 如果该文件的一部分，是由另一个进程锁定和写入操作锁定部分重叠，WriteFile失败。 当写入一个文件，最后写入时间没有完全更新，直到所有句柄书写已被关闭。因此，为了确保准确的最后写入时间，立即关闭后，以书面文件的文件句柄。 访问输出缓冲区写操作时使用的缓冲区可能导致从该缓冲区写的数据损坏。应用程序不能写入，重新分配，或免费的输出缓冲区中写入操作使用，直到写入操作完成。这可以是特别问题时，使用异步文件句柄。 Additional information regarding synchronous versus asynchronous file handles can be found later in the Synchronization and File Position section and Synchronous and Asynchronous I/O . 请注意，时间戳可能无法更新远程文件正确。为了确保一致的结果，使用缓冲I / O的 该系统解释零字节写指定一个空写操作和WriteFile不会截断或扩展文件。为了截断或扩展文件，请使用SetEndOfFile功能。 字符可以写入使用WriteFile屏幕缓冲区的句柄控制台输出。该函数的具体行为是由控制台模式。该数据写入到当前光标位置。光标的位置是更新后的写操作。欲了解更多有关游戏机手柄，看到CreateFile信息。 当写入通讯设备，在WriteFile行为由目前的通信超时的设置和使用SetCommTimeouts和GetCommTimeouts检索功能。可能会发生不可预知的结果，如果您不设置超时值。如需有关信息通信的时间超时，请COMMTIMEOUTS。 虽然单一部门写是原子，一个多部门写不能保证是原子，除非您使用的交易(即，处理营造的交易处理，例如，创建一个句柄使用CreateFileTransacted)。多部门写道，缓存可能并不总是被写入磁盘马上，因此，指定CreateFile FILE_FLAG_WRITE_THROUGH全方位，以确保整个多部门写的潜力没有被写入缓存延迟到磁盘。 如果您直接写信给量，有一个安装的文件系统，必须首先获取独占访问量。 Otherwise, you risk causing data corruption or system instability, because your application's writes may conflict with other changes coming from the file system and leave the contents of the volume in an inconsistent state.为了避免这些问题，以下修改过的Windows Vista和更高版本： 阿写卷上的处理会成功，如果卷没有挂载的文件系统，或者如果下列条件之一： 各部门要写入的启动扇区。 各部门要写入居住以外的文件系统空间。 您有明确锁定或卸除使用FSCTL_LOCK_VOLUME或FSCTL_DISMOUNT_VOLUME音量。 该卷并没有实际的文件系统。 (换句话说，它有一个RAW文件系统的安装。) 磁盘上的写入将成功处理如果下列条件之一： 各部门要写入不属于一个卷的程度。 各部门要写入属于一装入的卷，但是您必须明确地锁定或卸除使用FSCTL_LOCK_VOLUME或FSCTL_DISMOUNT_VOLUME音量。 各部门要写入属于一个没有安装的文件系统容量比其他的RAW。 有成功与使用FILE_FLAG_NO_BUFFERINGCreateFile打开文件的工作严格要求。详情请参阅文件缓冲。 如果hFile开幕时FILE_FLAG_OVERLAPPED，下列条件实际上是： 该lpOverlapped参数必须指向一个有效的和独特的OVERLAPPED结构，否则，函数可以错误地报告写操作完成。 在lpNumberOfBytesWritten参数应设置为NULL。要获得写入的字节数，使用GetOverlappedResult函数。如果hFile参数与我联系/ O完成端口，您也可以由调用GetQueuedCompletionStatus函数写入的字节数。 同步和文件位置 如果hFile与FILE_FLAG_OVERLAPPED打开，它是一个异步的文件句柄，否则是同步的。使用重叠结构的规则是每一个稍有不同，如前所述。 注意：如果文件或设备是开放的异步I / O的后续调用WriteFile功能，如使用该处理一般立即返回，但也表现就可以阻止执行同步。有关更多信息，请参阅http://support.microsoft.com/kb/156932。 与异步文件处理工作的几点思考： WriteFile可能会返回写操作前完成。在这种情况下，WriteFile返回FALSE并GetLastError函数返回ERROR_IO_PENDING，允许调用进程继续在系统写操作完成。 该lpOverlapped参数必须是NULL，并应考虑到以下事实使用： 虽然活动在OVERLAPPED结构指定的设置和重置由系统自动，偏移是OVERLAPPED结构中指定不自动更新。 WriteFile重置事件一无信号状态时，它开始的I / O操作。 OVERLAPPED结构中指定的事件设置为信号状态时，写操作完成，在此之前，写操作被认为是悬而未决。 由于写的偏移是OVERLAPPED结构中指定的操作开始，和WriteFile可能会返回之前，系统级写操作完成(写待定)，无论是抵销或任何其他部分的结构应该修改，释放，或由应用程序重复使用，直到事件发出信号(即写完成)。 与同步的文件处理工作的几点思考： 如果lpOverlapped为NULL，则写上当前文件位置操作开始和WriteFile不会返回，直到操作完成，系统更新前WriteFile返回文件指针。 如果lpOverlapped不为NULL，写的偏移中指定的OVERLAPPED结构和WriteFile不会返回，直到操作开始写操作完成。该系统更新前WriteFile重叠的回报所抵消。 有关更多信息，请参阅CreateFile和同步和异步I / O。 管道 如果一个匿名管道正在使用和读取处理已经关闭，当WriteFile尝试写入使用管道的相应写处理，该函数返回FALSE，GetLastError返回ERROR_BROKEN_PIPE。 如果管道缓冲区满时，应用程序使用WriteFile函数写入到管道，在写操作可能无法完成立即。写操作将完成读操作时(使用ReadFile函数)，使更多的系统缓冲区空间的管道可用。 当写入无阻塞，字节模式管处理缓冲区空间不足，WriteFile返回TRUE与* lpNumberOfBytesWritten“nNumberOfBytesToWrite。 欲了解更多有关管道信息，请管。 交易业务 如果绑定到文件处理事务，那么该文件写入交易。有关更多信息，请参阅关于交互式NTFS。 实例 对于一些例子，请参见创建和使用读取或写入一个临时文件，并打开文件。 下面的C + +示例演示如何使部门的非缓冲文件写入。大小变量是原始数据的大小块您在写入文件感兴趣。对于有关缓冲额外的规则文件I /输出，请参阅文件缓冲。 #include #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)))) void main() { // Function code DWORD BytesPerSector; // obtained from the GetFreeDiskSpace function. DWORD Size; // buffer size of your data to write // ... obtain data here // 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. LPBYTE Buffer = (LPBYTE) malloc(SizeNeeded); // Error checking of your choice. if ( !Buffer ) { goto cleanup; } // Actual alignment happens here. void * BufferAligned = ROUND_UP_PTR(Buffer, BytesPerSector); // Add code using BufferAligned here. cleanup: if ( Buffer ) { // Replace with corresponding free routine. free(Buffer); } } 要求： 最低支持：client－Windows 2000专业版 最低支持server－Windows 2000服务器 HeaderWinBase.h(头文件：winuser.h) LibraryKernel32.lib DLLKernel32.dll 参见 CancelIo CancelIoEx CancelSynchronousIo CreateFile CreateFileTransacted 文件管理函数 GetLastError函数 GetOverlappedResult GetQueuedCompletionStatus ReadFile SetEndOfFile WriteFileEx 如果有任何问题和意见，请发送给微软(wsddocfb@microsoft.com) 生成日期：2009年9月3日 ＝＝英文原文＝＝WriteFile Function Writes data to the specified file or input/output (I/O) device. Writes occur at the position specified by the file pointer, if the handle refers to a seeking device. This function is designed for both synchronous and asynchronous operation. For a similar function designed solely for asynchronous operation, see WriteFileEx . Syntax C++ BOOL WINAPI WriteFile( __in HANDLE hFile, __in LPCVOID lpBuffer, __in DWORD nNumberOfBytesToWrite, __out_opt LPDWORD lpNumberOfBytesWritten, __inout_opt LPOVERLAPPED lpOverlapped ); Parameters hFile [in] A handle to the file or I/O device (for example, a file, file stream, physical disk, volume, console buffer, tape drive, socket, communications resource, mailslot, or pipe). The hFile parameter must have been created with the write access. For more information, see Generic Access Rights and File Security and Access Rights . For asynchronous write operations, hFile can be any handle opened with the CreateFile function using the FILE_FLAG_OVERLAPPED flag or a socket handle returned by the socket or accept function. lpBuffer [in] A pointer to the buffer containing the data to be written to the file or device. This buffer must remain valid for the duration of the write operation. The caller must not use this buffer until the write operation is completed. nNumberOfBytesToWrite [in] The number of bytes to be written to the file or device. A value of zero specifies a null write operation. The behavior of a null write operation depends on the underlying file system or communications technology. Pipe write operations across a network are limited to 65,535 bytes per write. For more information regarding pipes, see the Remarks section. lpNumberOfBytesWritten [out, optional] A pointer to the variable that receives the number of bytes written when using a synchronous hFile parameter. WriteFile sets this value to zero before doing any work or error checking. Use NULL for this parameter if this is an asynchronous operation to avoid potentially erroneous results. This parameter can be NULL only when the lpOverlapped parameter is not NULL. For more information, see the Remarks section. lpOverlapped [in, out, optional] A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise this parameter can be NULL. For an hFile that supports byte offsets, if you use this parameter you must specify a byte offset at which to start writing to the file or device. This offset is specified by setting the Offset and OffsetHigh members of the OVERLAPPED structure. For an hFile that does not support byte offsets, Offset and OffsetHigh are ignored. To write to the end of file, specify both the Offset and OffsetHigh members of the OVERLAPPED structure as 0xFFFFFFFF. This is functionally equivalent to previously calling the CreateFile function to open hFile using FILE_APPEND_DATA access. For more information about different combinations of lpOverlapped and FILE_FLAG_OVERLAPPED, see the Remarks section and the Synchronization and File Position section. Return Value If the function succeeds, the return value is nonzero (TRUE). If the function fails, or is completing asynchronously, the return value is zero (FALSE). To get extended error information, call the GetLastError function. Note The GetLastError code ERROR_IO_PENDING is not a failure; it designates the write operation is pending completion asynchronously. For more information, see Remarks. Remarks The WriteFile function returns when one of the following conditions occur: The number of bytes requested is written. A read operation releases buffer space on the read end of the pipe (if the write was blocked). For more information, see the Pipes section. An asynchronous handle is being used and the write is occurring asynchronously. An error occurs. The WriteFile function may fail with ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests. To cancel all pending asynchronous I/O operations, use either: CancelIo —this function cancels only operations issued by the calling thread for the specified file handle. CancelIoEx —this function cancels all operations issued by the threads for the specified file handle. Use the CancelSynchronousIo function to cancel pending synchronous I/O operations. I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED. The WriteFile function may fail with ERROR_NOT_ENOUGH_QUOTA, which means the calling process's buffer could not be page-locked. For more information, see SetProcessWorkingSetSize . If part of the file is locked by another process and the write operation overlaps the locked portion, WriteFile fails. When writing to a file, the last write time is not fully updated until all handles used for writing have been closed. Therefore, to ensure an accurate last write time, close the file handle immediately after writing to the file. Accessing the output buffer while a write operation is using the buffer may lead to corruption of the data written from that buffer. Applications must not write to, reallocate, or free the output buffer that a write operation is using until the write operation completes. This can be particularly problematic when using an asynchronous file handle. Additional information regarding synchronous versus asynchronous file handles can be found later in the Synchronization and File Position section and Synchronous and Asynchronous I/O . Note that the time stamps may not be updated correctly for a remote file. To ensure consistent results, use unbuffered I/O. The system interprets zero bytes to write as specifying a null write operation and WriteFile does not truncate or extend the file. To truncate or extend a file, use the SetEndOfFile function. Characters can be written to the screen buffer using WriteFile with a handle to console output. The exact behavior of the function is determined by the console mode. The data is written to the current cursor position. The cursor position is updated after the write operation. For more information about console handles, see CreateFile . When writing to a communications device, the behavior of WriteFile is determined by the current communication time-out as set and retrieved by using the SetCommTimeouts and GetCommTimeouts functions. Unpredictable results can occur if you fail to set the time-out values. For more information about communication time-outs, see COMMTIMEOUTS . Although a single-sector write is atomic, a multi-sector write is not guaranteed to be atomic unless you are using a transaction (that is, the handle created is a transacted handle; for example, a handle created using CreateFileTransacted ). Multi-sector writes that are cached may not always be written to the disk right away; therefore, specify FILE_FLAG_WRITE_THROUGH in CreateFile to ensure that an entire multi-sector write is written to the disk without potential caching delays. If you write directly to a volume that has a mounted file system, you must first obtain exclusive access to the volume. Otherwise, you risk causing data corruption or system instability, because your application's writes may conflict with other changes coming from the file system and leave the contents of the volume in an inconsistent state. To prevent these problems, the following changes have been made in Windows Vista and later: A write on a volume handle will succeed if the volume does not have a mounted file system, or if one of the following conditions is true: The sectors to be written to are boot sectors. The sectors to be written to reside outside of file system space. You have explicitly locked or dismounted the volume by using FSCTL_LOCK_VOLUME or FSCTL_DISMOUNT_VOLUME . The volume has no actual file system. (In other words, it has a RAW file system mounted.) A write on a disk handle will succeed if one of the following conditions is true: The sectors to be written to do not fall within a volume's extents. The sectors to be written to fall within a mounted volume, but you have explicitly locked or dismounted the volume by using FSCTL_LOCK_VOLUME or FSCTL_DISMOUNT_VOLUME. The sectors to be written to fall within a volume that has no mounted file system other than RAW. There are strict requirements for successfully working with files opened with CreateFile using FILE_FLAG_NO_BUFFERING. For details see File Buffering . If hFile was opened with FILE_FLAG_OVERLAPPED, the following conditions are in effect: The lpOverlapped parameter must point to a valid and unique OVERLAPPED structure, otherwise the function can incorrectly report that the write operation is complete. The lpNumberOfBytesWritten parameter should be set to NULL. To get the number of bytes written, use the GetOverlappedResult function. If the hFile parameter is associated with an I/O completion port, you can also get the number of bytes written by calling the GetQueuedCompletionStatus function. Synchronization and File Position If hFile is opened with FILE_FLAG_OVERLAPPED, it is an asynchronous file handle; otherwise it is synchronous. The rules for using the OVERLAPPED structure are slightly different for each, as previously noted. Note If a file or device is opened for asynchronous I/O, subsequent calls to functions such as WriteFile using that handle generally return immediately, but can also behave synchronously with respect to blocked execution. For more information, see http://support.microsoft.com/kb/156932 . Considerations for working with asynchronous file handles: WriteFile may return before the write operation is complete. In this scenario, WriteFile returns FALSE and the GetLastError function returns ERROR_IO_PENDING, which allows the calling process to continue while the system completes the write operation. The lpOverlapped parameter must not be NULL and should be used with the following facts in mind: Although the event specified in the OVERLAPPED structure is set and reset automatically by the system, the offset that is specified in the OVERLAPPED structure is not automatically updated. WriteFile resets the event to a nonsignaled state when it begins the I/O operation. The event specified in the OVERLAPPED structure is set to a signaled state when the write operation is complete; until that time, the write operation is considered pending. Because the write operation starts at the offset that is specified in the OVERLAPPED structure, and WriteFile may return before the system-level write operation is complete (write pending), neither the offset nor any other part of the structure should be modified, freed, or reused by the application until the event is signaled (that is, the write completes). Considerations for working with synchronous file handles: If lpOverlapped is NULL, the write operation starts at the current file position and WriteFile does not return until the operation is complete, and the system updates the file pointer before WriteFile returns. If lpOverlapped is not NULL, the write operation starts at the offset that is specified in the OVERLAPPED structure and WriteFile does not return until the write operation is complete. The system updates the OVERLAPPED offset before WriteFile returns. For more information, see CreateFile and Synchronous and Asynchronous I/O . Pipes If an anonymous pipe is being used and the read handle has been closed, when WriteFile attempts to write using the pipe's corresponding write handle, the function returns FALSE and GetLastError returns ERROR_BROKEN_PIPE. If the pipe buffer is full when an application uses the WriteFile function to write to a pipe, the write operation may not finish immediately. The write operation will be completed when a read operation (using the ReadFile function) makes more system buffer space available for the pipe. When writing to a nonblocking, byte-mode pipe handle with insufficient buffer space, WriteFile returns TRUE with *lpNumberOfBytesWritten < nNumberOfBytesToWrite. For more information about pipes, see Pipes . Transacted Operations If there is a transaction bound to the file handle, then the file write is transacted. For more information, see About Transactional NTFS . Examples For some examples, see Creating and Using a Temporary File and Opening a File for Reading or Writing . The following C++ example shows how to align sectors for unbuffered file writes. The Size variable is the size of the original data block you are interested in writing to the file. For additional rules regarding unbuffered file I/O, see File Buffering . #include #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)))) void main() { // Function code DWORD BytesPerSector; // obtained from the GetFreeDiskSpace function. DWORD Size; // buffer size of your data to write // ... obtain data here // 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. LPBYTE Buffer = (LPBYTE) malloc(SizeNeeded); // Error checking of your choice. if ( !Buffer ) { goto cleanup; } // Actual alignment happens here. void * BufferAligned = ROUND_UP_PTR(Buffer, BytesPerSector); // Add code using BufferAligned here. cleanup: if ( Buffer ) { // Replace with corresponding free routine. free(Buffer); } } Requirements Minimum supported clientWindows 2000 Professional Minimum supported serverWindows 2000 Server HeaderWinBase.h (include Windows.h) LibraryKernel32.lib DLLKernel32.dll See Also CancelIo CancelIoEx CancelSynchronousIo CreateFile CreateFileTransacted File Management Functions GetLastError GetOverlappedResult GetQueuedCompletionStatus ReadFile SetEndOfFile WriteFileEx Send comments about this topic to Microsoft Build date: 9/3/2009 ＝＝原始网址＝＝http://msdn.microsoft.com/en-us/library/aa365747(VS.85).aspx\n |
| 随便看 |
|
windows api函数参考手册包含2258条windows api函数文档，详细介绍nodejs、java、rust调用windows api的方法技巧，是学习windows api编程的入门中文文档。