_dup, _dup2

Creates a second file descriptor for an open file (_dup), or reassigns a file descriptor (_dup2).

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

Parameters

• fd, fd1
  File descriptors referring to open file.

• fd2
  Any file descriptor.

Return Value

_dup returns a new file descriptor. _dup2 returns 0 to indicate success. If an error occurs, each function returns –1 and sets errno to EBADF if the file descriptor is invalid or to EMFILE if no more file descriptors are available. In the case of an invalid file descriptor, the function also invokes the invalid parameter handler, as described in Parameter Validation.

For more information about these and other return codes, see _doserrno, errno, _sys_errlist, and _sys_nerr.

Remarks

The _dup and _dup2 functions associate a second file descriptor with a currently open file. These functions can be used to associate a predefined file descriptor, such as that for stdout, with a different file. Operations on the file can be carried out using either file descriptor. The type of access allowed for the file is unaffected by the creation of a new descriptor. _dup returns the next available file descriptor for the given file. _dup2 forces fd2 to refer to the same file as fd1. If fd2 is associated with an open file at the time of the call, that file is closed.

Both _dup and _dup2 accept file descriptors as parameters. To pass a stream (FILE *) to either of these functions, use _fileno. The fileno routine returns the file descriptor currently associated with the given stream. The following example shows how to associate stderr (defined as FILE * in Stdio.h) with a file descriptor:

int cstderr = _dup( _fileno( stderr ));

Requirements

The console is not supported in Windows Store apps. The standard stream handles that are associated with the console—stdin, stdout, and stderr—must be redirected before C run-time functions can use them in Windows Store apps. For more compatibility information, see Compatibility.

Example

// 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'

See Also

Reference

Low-Level I/O

_close

_creat, _wcreat

_open, _wopen