_dup, _dup2

Create a second handle for an open file (_dup), or reassign a file handle (_dup2).

int_dup( int handle );

int _dup2( int handle1, int handle2 );

Routine Required Header Compatibility
_dup <io.h> Win 95, Win NT
_dup2 <io.h> Win 95, Win NT

For additional compatibility information, see Compatibility in the Introduction.

Libraries

LIBC.LIB Single thread static library, retail version
LIBCMT.LIB Multithread static library, retail version
MSVCRT.LIB Import library for MSVCRT.DLL, retail version

Return Value

_dup returns a new file handle. _dup2 returns 0 to indicate success. If an error occurs, each function returns –1 and sets errno to EBADF if the file handle is invalid, or to EMFILE if no more file handles are available.

Parameters

handle, handle1

Handles referring to open file

handle2

Any handle value

Remarks

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

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

cstderr = _dup( _fileno( stderr ));

Example

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

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

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

   old = _dup( 1 );   /* "old" now refers to "stdout" */
                      /* Note:  file handle 1 == "stdout" */
   if( old == -1 )
   {
      perror( "_dup( 1 ) failure" );
      exit( 1 );
   }
   write( old, "This goes to stdout first\r\n", 27 );
   if( ( new = fopen( "data", "w" ) ) == NULL )
   {
      puts( "Can't open file 'data'\n" );
      exit( 1 );
   }

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

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

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

Output

This goes to stdout first
This goes to file 'data'

This goes to stdout

The file 'data' contains:

This goes to file 'data'

Low-level I/O Routines

See Also   _close, _creat, _open