_fdopen, _wfdopen

Associa um fluxo com um arquivo que foi aberto anteriormente para E/S de nível inferior.

Sintaxe

FILE *_fdopen(
   int fd,
   const char *mode
);
FILE *_wfdopen(
   int fd,
   const wchar_t *mode
);

Parâmetros

fd
Descritor de arquivo do arquivo aberto.

mode
Tipo de acesso do arquivo.

Valor retornado

Cada uma dessas funções retorna um ponteiro para o fluxo aberto. Um valor de ponteiro nulo indica um erro. Quando ocorre um erro, o manipulador de parâmetro inválido é invocado, conforme descrito em Validação do parâmetro. Se a execução puder continuar, errno será definido como EBADF, que indica um descritor de arquivo inválido ou EINVAL, que indica que mode é um ponteiro nulo.

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

Comentários

A função _fdopen associa um fluxo de E/S com o arquivo que é identificado por fde, portanto, permite que um arquivo seja aberto para a E/S de nível inferior que será armazenada em buffer e formatada. A função _wfdopen é uma versão de caractere largo da função _fdopen; o argumento mode para _wfdopen é uma cadeia de caracteres larga. Caso contrário, _wfdopen e _fdopen comportam-se de modo idêntico.

Os descritores de arquivo passados para _fdopen são de propriedade do fluxo FILE * retornado. Se _fdopen for bem-sucedido, não chame _close no descritor de arquivo. Chamar fclose no FILE * retornado também fecha o descritor de arquivo.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar isso, confira Estado global no CRT.

A cadeia de caracteres mode especifica o tipo de acesso ao arquivo solicitado para o arquivo:

mode	Access
"r"	Abre para leitura. Se o arquivo não existir ou não puder ser encontrado, a chamada fopen falhará.
"w"	Abre um arquivo vazio para gravação. Se o arquivo determinado existir, seus conteúdos são destruídos.
"a"	Abre para gravação no final do arquivo (anexando). Cria o arquivo se ele não existir.
"r+"	Abre para leitura e gravação. O arquivo deve existir.
"w+"	Abre um arquivo vazio para leitura e gravação. Se o arquivo existir, seus conteúdos são destruídos.
"a+"	Abre para leitura e conexão. Cria o arquivo se ele não existir.

Quando um arquivo é aberto com o tipo de acesso "a" ou "a+", todas as operações de gravação ocorrem no fim do arquivo. O ponteiro de arquivo pode ser reposicionado usando fseek ou rewind, mas sempre é movido de volta para o final do arquivo antes que qualquer operação de gravação seja realizada. Assim, os dados existentes não podem ser substituídos. Quando o tipo de acesso "r+", "w+" ou "a+" é especificado, são permitidas leitura e gravação (diz-se que o arquivo está aberto para "atualização"). No entanto, quando você muda entre leitura e gravação, deve haver uma operação fflush, fsetpos, fseek ou rewind intermediária. Você poderá especificar a posição atual para a operação fsetpos ou fseek, se desejar.

Além dos valores acima, os seguintes caracteres também podem ser incluídos para mode especificar o modo de conversão para caracteres de nova linha:

Modificador mode	Comportamento
t	Abra no modo de texto (convertido). Neste modo, combinações de CR-LF (retorno de carro – avanço de linha) são convertidas em LFs (avanços de uma linha) na entrada e caracteres de LF são convertidos em combinações de CR-LF na saída. Além disso, Ctrl+Z é interpretado como um caractere de fim do arquivo na entrada.
b	Abre no modo binário (não convertido). Todas as conversões do modo t são suprimidas.
c	Habilite o sinalizador de confirmação para o filename associado de modo que os conteúdos do buffer de arquivo sejam gravados diretamente no disco, se fflush ou _flushall for chamado.
n	Redefina o sinalizador de confirmação para o filename como "no-commit". Esse sinalizador é o padrão. Também substitui o sinalizador de confirmação global se você vincular o programa a Commode.obj. O padrão do sinalizador de confirmação global é "no-commit", a menos que você vincule explicitamente seu programa a Commode.obj.

As topções , c, e n mode são extensões da Microsoft para fopen e _fdopen. Não os use se quiser preservar a portabilidade ANSI.

Se t ou b não for fornecido em mode, o modo de conversão padrão será definido pela variável global _fmode. Se t ou b for prefixado para o argumento, a função falha e retorna NULL. Para saber mais sobre os modos de texto e binário, consulte E/S de texto e arquivo de modo binário.

Caracteres válidos para a cadeia de caracteres mode usada em fopen e _fdopen correspondem aos argumentos oflag usados em _open e _sopen, conforme mostrado nesta tabela:

Caracteres mode na cadeia de caracteres	Valor oflag equivalente para _open e _sopen
a	_O_WRONLY | _O_APPEND(geralmente _O_WRONLY | _O_CREAT | _O_APPEND)
a+	_O_RDWR | _O_APPEND(geralmente _O_RDWR | _O_APPEND | _O_CREAT)
r	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY(geralmente _O_WRONLY | _O_CREAT | _O_TRUNC)
w+	_O_RDWR(geralmente _O_RDWR | _O_CREAT | _O_TRUNC)
b	_O_BINARY
t	_O_TEXT
c	Nenhum
n	Nenhum

Requisitos

Função	Cabeçalho necessário	Cabeçalho C++
_fdopen	<stdio.h>	<cstdio>
_wfdopen	<stdio.h> ou <wchar.h>	<cstdio>

Para obter mais informações sobre as convenções de conformidade e de nomenclatura de padrões na biblioteca de runtime C, confira Compatibilidade.

Mapeamentos de rotina de texto genérico

Rotina <tchar.h>	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tfdopen	_fdopen	_fdopen	_wfdopen

Exemplo

// crt_fdopen.c
// This program opens a file by using low-level
// I/O, then uses _fdopen to switch to stream
// access. It counts the lines in the file.

#include <stdlib.h>
#include <stdio.h>
#include <fcntl.h>
#include <io.h>
#include <share.h>

int main( void )
{
   FILE *stream;
   int  fd, count = 0;
   char inbuf[128];

   // Open a file.
   if( _sopen_s( &fd, "crt_fdopen.txt", _O_RDONLY, _SH_DENYNO, 0 ) )
      exit( 1 );

   // Get stream from file descriptor.
   if( (stream = _fdopen( fd, "r" )) == NULL )
      exit( 1 );

   while( fgets( inbuf, 128, stream ) != NULL )
      count++;

   // After _fdopen, close by using fclose, not _close.
   fclose( stream );
   printf( "Lines in file: %d\n", count );
}

Entrada: crt_fdopen.txt

Line one
Line two

Saída

Lines in file: 2

Confira também

E/S de fluxo
_dup, _dup2
fclose, _fcloseall
fopen, _wfopen
freopen, _wfreopen
_open, _wopen