_write_write

将数据写入文件。Writes data to a file.

语法Syntax

int _write(
   int fd,
   const void *buffer,
   unsigned int count
);

参数Parameters

fdfd
可向其中写入数据的文件的文件描述符。File descriptor of file into which data is written.

bufferbuffer
要写入的数据。Data to be written.

countcount
字节数。Number of bytes.

返回值Return Value

如果成功,则 _write返回写入的字节数。If successful, _write returns the number of bytes written. 如果磁盘上剩余的实际空间小于函数尝试写入磁盘的缓冲区的大小,则 _write将失败,并且不会将任何缓冲区的内容刷新到磁盘。If the actual space remaining on the disk is less than the size of the buffer the function is trying to write to the disk, _write fails and does not flush any of the buffer's contents to the disk. 返回值-1 表示错误。A return value of -1 indicates an error. 如果传递的参数无效,则此函数将调用无效参数处理程序,如参数验证中所述。If invalid parameters are passed, this function invokes the invalid parameter handler, as described in Parameter Validation. 如果允许执行继续, 则该函数将返回-1, 并将errno设置为以下三个值之一:Ebadf ( , 这意味着文件描述符无效或文件未打开以进行写入;ENOSPC, 这意味着设备上没有足够的空间用于操作;或EINVAL, 这意味着缓冲区为空指针, 或在 Unicode 模式下传递到文件的奇数字节If execution is allowed to continue, the function returns -1 and errno is set to one of three values: EBADF, which means the file descriptor is invalid or the file is not opened for writing; ENOSPC, which means there is not enough space left on the device for the operation; or EINVAL, which means that buffer was a null pointer or that an odd count of bytes was passed to be written to a file in Unicode mode.

有关这些代码及其他返回代码的详细信息,请参阅 errno、_doserrno、_sys_errlist 和 _sys_nerrFor more information about these and other return codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

如果在文本模式下打开该文件, 则会在输出中将每个换行符替换为回车换行符。If the file is opened in text mode, each line feed character is replaced with a carriage return-line feed pair in the output. 此替换不会影响返回值。The replacement doesn't affect the return value.

在 Unicode 转换模式下打开该文件时(例如,如果使用 _open_sopen打开Fd ,并使用包含 _O_WTEXT_O_U16TEXT_O_U8TEXT的模式参数打开,或者通过使用fopen和 mode 参数,其中包括ccs = UNICODEccs = utf-utf-16leccs = utf-8,或者模式通过使用 _setmode更改为 UNICODE 转换模式时,缓冲区被解释为指向包含utf-16数据的wchar_t数组。When the file is opened in Unicode translation mode—for example, if fd is opened by using _open or _sopen and a mode parameter that includes _O_WTEXT, _O_U16TEXT, or _O_U8TEXT, or if it's opened by using fopen and a mode parameter that includes ccs=UNICODE, ccs=UTF-16LE, or ccs=UTF-8, or if the mode is changed to a Unicode translation mode by using _setmodebuffer is interpreted as a pointer to an array of wchar_t that contains UTF-16 data. 尝试在此模式下写入奇数个字节会导致参数验证错误。An attempt to write an odd number of bytes in this mode causes a parameter validation error.

备注Remarks

_Write函数将缓冲区中的计数字节写入与fd关联的文件中。The _write function writes count bytes from buffer into the file associated with fd. 写入操作从与给定文件相关联的文件指针(如果有)的当前位置开始执行。The write operation begins at the current position of the file pointer (if any) associated with the given file. 如果文件处于打开状态以供追加,则该操作从该文件的当前末尾位置开始执行。If the file is open for appending, the operation begins at the current end of the file. 写入操作完成后, 文件指针将按写入的字节数增加。After the write operation, the file pointer is increased by the number of bytes written.

写入在文本模式下打开的文件时, _write会将 CTRL + Z 字符视为文件的逻辑端。When writing to files opened in text mode, _write treats a CTRL+Z character as the logical end of file. 写入设备时, _write会将缓冲区中的 CTRL + Z 字符视为输出终止符。When writing to a device, _write treats a CTRL+Z character in the buffer as an output terminator.

要求Requirements

例程所返回的值Routine 必需的标头Required header
_write_write <io.h><io.h>

有关其他兼容性信息,请参阅 兼容性For additional compatibility information, see Compatibility.

示例Example

// crt__write.c
//
// This program opens a file for output and uses _write to write
// some bytes to the file.

#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <errno.h>
#include <share.h>

char buffer[] = "This is a test of '_write' function";

int main( void )
{
   int         fileHandle = 0;
   unsigned    bytesWritten = 0;

   if ( _sopen_s(&fileHandle, "write.o", _O_RDWR | _O_CREAT,
                  _SH_DENYNO, _S_IREAD | _S_IWRITE) )
      return -1;

   if (( bytesWritten = _write( fileHandle, buffer, sizeof( buffer ))) == -1 )
   {
      switch(errno)
      {
         case EBADF:
            perror("Bad file descriptor!");
            break;
         case ENOSPC:
            perror("No space left on device!");
            break;
         case EINVAL:
            perror("Invalid parameter: buffer was NULL!");
            break;
         default:
            // An unrelated error occured
            perror("Unexpected error!");
      }
   }
   else
   {
      printf_s( "Wrote %u bytes to file.\n", bytesWritten );
   }
   _close( fileHandle );
}
Wrote 36 bytes to file.

请参阅See also

低级别 I/OLow-Level I/O
fwritefwrite
_open、_wopen_open, _wopen
_read_read
_setmode_setmode