_dup, _dup2

Cria um segundo descritor de arquivo para um arquivo aberto (_dup) ou reatribui um descritor de arquivo (_dup2).

Sintaxe

int _dup( int fd );
int _dup2( int fd1, int fd2 );

Parâmetros

fd, fd1
Descritores de arquivo que fazem referência ao arquivo aberto.

fd2
Qualquer descritor de arquivo.

Retornar valor

_dup retorna um novo descritor de arquivo. _dup2 retorna 0 para indicar êxito. Se ocorrer um erro, cada função retornará -1 e definirá errno como EBADF se o descritor de arquivo for inválido ou se EMFILE não houver mais descritores de arquivo disponíveis. Quando passado um descritor de arquivo inválido, a função também invoca o manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro.

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

Comentários

As funções _dup e _dup2 associam um segundo descritor de arquivo com um arquivo aberto. Essas funções podem ser usadas para associar um descritor de arquivo predefinido, como stdout, com um arquivo diferente. As operações no arquivo podem ser realizadas usando um descritor de arquivo. O tipo de acesso permitido para o arquivo não é afetado pela criação de um novo descritor. _dup retorna o próximo descritor de arquivo disponível para o arquivo. _dup2 força fd2 para se referir ao mesmo arquivo como fd1. Se fd2 está associado com um arquivo aberto no momento da chamada, esse arquivo é fechado.

_dup e _dup2 aceitam descritores de arquivo como parâmetros. Para passar um fluxo (FILE *) para uma dessas funções, use _fileno. A rotina fileno retorna o descritor de arquivo associado no momento a determinado fluxo. O exemplo a seguir mostra como associar stderr (definido como FILE * em stdio.h) com um descritor de arquivo:

int cstderr = _dup( _fileno( stderr ));

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
_dup	<io.h>
_dup2	<io.h>

Não há suporte para o console em aplicativos UWP (Plataforma Universal do Windows). Os identificadores de fluxo padrão associados ao console, stdin, stdout e stderr, devem ser redirecionados antes que as funções em tempo de execução C possam usá-los em aplicativos UWP. Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// crt_dup.c
// This program uses the variable old to save
// the original stdout. It then opens a new file named
// DataFile and forces stdout to refer to it. Finally, it
// restores stdout to its original state.

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

int main( void )
{
   int old;
   FILE *DataFile;

   old = _dup( 1 );   // "old" now refers to "stdout"
                      // Note:  file descriptor 1 == "stdout"
   if( old == -1 )
   {
      perror( "_dup( 1 ) failure" );
      exit( 1 );
   }
   _write( old, "This goes to stdout first\n", 26 );
   if( fopen_s( &DataFile, "data", "w" ) != 0 )
   {
      puts( "Can't open file 'data'\n" );
      exit( 1 );
   }

   // stdout now refers to file "data"
   if( -1 == _dup2( _fileno( DataFile ), 1 ) )
   {
      perror( "Can't _dup2 stdout" );
      exit( 1 );
   }
   puts( "This goes to file 'data'\n" );

   // Flush stdout stream buffer so it goes to correct file
   fflush( stdout );
   fclose( DataFile );

   // Restore original stdout
   _dup2( old, 1 );
   puts( "This goes to stdout\n" );
   puts( "The file 'data' contains:" );
   _flushall();
   system( "type data" );
}

This goes to stdout first
This goes to stdout

The file 'data' contains:
This goes to file 'data'

Confira também

E/S de baixo nível
_close
_creat, _wcreat
_open, _wopen