<!-- Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005, 2008, 2009, 2013 The President and Fellows of Harvard College. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE UNIVERSITY OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. --> <html> <head> <title>dup2</title> <body bgcolor=#ffffff> <h2 align=center>dup2</h2> <h4 align=center>OS/161 Reference Manual</h4> <h3>Name</h3> <p> dup2 - clone file handles </p> <h3>Library</h3> <p> Standard C Library (libc, -lc) </p> <h3>Synopsis</h3> <p> <tt>#include <unistd.h></tt><br> <br> <tt>int</tt><br> <tt>dup2(int </tt><em>oldfd</em><tt>, int </tt><em>newfd</em><tt>);</tt> </p> <h3>Description</h3> <p> <tt>dup2</tt> clones the file handle <em>oldfd</em> onto the file handle <em>newfd</em>. If <em>newfd</em> names an already-open file, that file is closed. </p> <p> The two handles refer to the same "open" of the file -- that is, they are references to the same object and share the same seek pointer. Note that this is different from opening the same file twice. </p> <p> dup2 is most commonly used to relocate opened files onto <tt>STDIN_FILENO</tt>, <tt>STDOUT_FILENO</tt>, and/or <tt>STDERR_FILENO</tt>. </p> <p> Both filehandles must be non-negative, and, if applicable, smaller than the maximum allowed file handle number. </p> <p> The call (like all system calls) should be atomic; for single-threaded processes this is trivial. Multithreaded processes should never e.g. see an intermediate state where <em>newfd</em> has been closed but <em>oldfd</em> has not yet been cloned onto it. Similarly, if two threads attempt e.g. <tt>dup2(3, 4)</tt> and <tt>dup2(4, 3)</tt> simultaneously, the results must be equivalent to one of the calls completing before the other starts. </p> <p> Using dup2 to clone a file handle onto itself has no effect. </p> <p> (The "2" in "dup2" arises from the existence of an older and less powerful Unix system call "dup".) </p> <h3>Return Values</h3> <p> <tt>dup2</tt> returns <em>newfd</em>. On error, -1 is returned, and <A HREF=errno.html>errno</A> is set according to the error encountered. </p> <h3>Errors</h3> <p> The following error codes should be returned under the conditions given. Other error codes may be returned for other cases not mentioned here. <table width=90%> <tr><td width=5% rowspan=3> </td> <td width=10% valign=top>EBADF</td> <td><em>oldfd</em> is not a valid file handle, or <em>newfd</em> is a value that cannot be a valid file handle.</td></tr> <tr><td valign=top>EMFILE</td> <td>The process's file table was full, or a process-specific limit on open files was reached.</td></tr> <tr><td valign=top>ENFILE</td> <td>The system's file table was full, if such a thing is possible, or a global limit on open files was reached.</td></tr> </table> </p> </body> </html>