_write

Grava dados em um arquivo.

Sintaxe

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

Parâmetros

fd
O descritor de arquivo do arquivo em que os dados são gravados.

buffer
Dados a serem gravados.

count
Quantidade de bytes.

Retornar valor

Em caso de êxito, _write retorna a quantidade de bytes gravados. Se o espaço restantes em disco for menor que o tamanho do buffer que a função está tentando gravar no disco, _write falha e não libera o conteúdo do buffer para o disco. Um valor retornado de -1 indica que há um erro. Se parâmetros inválidos forem passados, essa função invocará o manipulador de parâmetros inválidos, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, a função retornará -1 e errno será definida como um dos três valores: EBADF, o que significa que o descritor do arquivo é inválido ou o arquivo não está aberto para gravação, , o que significa que não há espaço suficiente no dispositivo para a operação, ou , o que significa que foi um ponteiro nulo, ENOSPCou EINVALque buffer um ímpar count de bytes foi passado no modo Unicode.

Para obter mais informações sobre esses e outros códigos de retorno, confira errno, _doserrno, _sys_errlist e _sys_nerr.

Se o arquivo for aberto no modo de texto, cada caractere de avanço de linha será substituído por um par carro de retorno na saída. Essa substituição não afeta o valor retornado.

Quando o arquivo é aberto no modo de conversão Unicode (por exemplo, se fd for aberto com o uso de _open ou _sopen e um parâmetro de modo que inclua _O_WTEXT, _O_U16TEXT ou _O_U8TEXT, ou se ele for aberto com uso de fopen e um parâmetro de modo que inclua , ccs=UNICODE, ccs=UTF-16LE ou ccs=UTF-8 se o modo for alterado para um modo de conversão Unicode com o uso de _setmode—buffer é interpretado como ponteiro para uma matriz de wchar_t que contém dados UTF-16. Tentar gravar uma quantidade ímpar de bytes nesse modo gera um erro de validação de parâmetro.

Comentários

A função _write grava count bytes de buffer no arquivo associado a fd. A operação de gravação começa na posição atual do ponteiro de arquivo (se houver) associado ao arquivo em questão. Se o arquivo estiver aberto para anexação, a operação começa no final do arquivo. Após a operação de gravação, o ponteiro do arquivo aumenta de acordo com a quantidade de bytes gravados.

Quando ele grava em arquivos abertos no modo de texto, _write trata um caractere CTRL+Z como o final lógico do arquivo. Quando ele grava em um dispositivo, _write trata um caractere CTRL+Z no buffer como um terminador de saída.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Requisitos

Rotina	Cabeçalho necessário
_write	<io.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// 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 occurred
            perror("Unexpected error!");
      }
   }
   else
   {
      printf_s( "Wrote %u bytes to file.\n", bytesWritten );
   }
   _close( fileHandle );
}

Wrote 36 bytes to file.

Confira também

E/S de baixo nível
fwrite
_open, _wopen
_read
_setmode