_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.
Valor retornado
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âmetro inválido, 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 de arquivo é inválido ou o arquivo não está aberto para gravação; ENOSPC, o que significa que não há espaço suficiente no dispositivo para a operação; ou EINVAL, o que significa que buffer foi um ponteiro nulo ou que uma odd count de bytes foi passada 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, confira Estado global no 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.