Movatterモバイル変換

dup(2) — Linux manual page

NAME \|LIBRARY \|SYNOPSIS \|DESCRIPTION \|RETURN VALUE \|ERRORS \|STANDARDS \|HISTORY \|NOTES \|SEE ALSO \|COLOPHON

dup(2)                     System Calls Manualdup(2)

NAME top

       dup, dup2, dup3 - duplicate a file descriptor

LIBRARY top

       Standard C library (libc,-lc)

SYNOPSIS top

#include <unistd.h>int dup(intoldfd);int dup2(intoldfd, intnewfd);#define _GNU_SOURCE/* See feature_test_macros(7) */#include <fcntl.h>/* Definition ofO_*constants */#include <unistd.h>int dup3(intoldfd, intnewfd, intflags);

DESCRIPTION top

       Thedup() system call allocates a new file descriptor that refers       to the same open file description as the descriptoroldfd.  (For       an explanation of open file descriptions, seeopen(2).)  The new       file descriptor number is guaranteed to be the lowest-numbered       file descriptor that was unused in the calling process.       After a successful return, the old and new file descriptors may be       used interchangeably.  Since the two file descriptors refer to the       same open file description, they share file offset and file status       flags; for example, if the file offset is modified by usinglseek(2) on one of the file descriptors, the offset is also       changed for the other file descriptor.       The two file descriptors do not share file descriptor flags (the       close-on-exec flag).  The close-on-exec flag (FD_CLOEXEC; seefcntl(2)) for the duplicate descriptor is off.dup2()       Thedup2() system call performs the same task asdup(), but       instead of using the lowest-numbered unused file descriptor, it       uses the file descriptor number specified innewfd.  In other       words, the file descriptornewfd is adjusted so that it now refers       to the same open file description asoldfd.       If the file descriptornewfd was previously open, it is closed       before being reused; the close is performed silently (i.e., any       errors during the close are not reported bydup2()).       The steps of closing and reusing the file descriptornewfd are       performedatomically.  This is important, because trying to       implement equivalent functionality usingclose(2) anddup() would       be subject to race conditions, wherebynewfd might be reused       between the two steps.  Such reuse could happen because the main       program is interrupted by a signal handler that allocates a file       descriptor, or because a parallel thread allocates a file       descriptor.       Note the following points:       •  Ifoldfd is not a valid file descriptor, then the call fails,          andnewfd is not closed.       •  Ifoldfd is a valid file descriptor, andnewfd has the same          value asoldfd, thendup2() does nothing, and returnsnewfd.dup3()dup3() is the same asdup2(), except that:       •  The caller can force the close-on-exec flag to be set for the          new file descriptor by specifyingO_CLOEXECinflags.  See the          description of the same flag inopen(2) for reasons why this          may be useful.       •  Ifoldfd equalsnewfd, thendup3() fails with the errorEINVAL.

RETURN VALUE top

       On success, these system calls return the new file descriptor.  On       error, -1 is returned, anderrno is set to indicate the error.

ERRORS top

EBADFoldfd isn't an open file descriptor.EBADFnewfd is out of the allowed range for file descriptors (see              the discussion ofRLIMIT_NOFILEingetrlimit(2)).EBUSY(Linux only) This may be returned bydup2() ordup3()              during a race condition withopen(2) anddup().EINTRThedup2() ordup3() call was interrupted by a signal; seesignal(7).EINVAL(dup3())flags contain an invalid value.EINVAL(dup3())oldfd was equal tonewfd.EMFILEThe per-process limit on the number of open file              descriptors has been reached (see the discussion ofRLIMIT_NOFILEingetrlimit(2)).ENOMEMInsufficient kernel memory was available.

STANDARDS top

dup()dup2() POSIX.1-2008.dup3() Linux.

HISTORY top

dup()dup2() POSIX.1-2001, SVr4, 4.3BSD.dup3() Linux 2.6.27, glibc 2.9.

NOTES top

       The error returned bydup2() is different from that returned byfcntl(...,F_DUPFD, ...)whennewfd is out of range.  On some       systems,dup2() also sometimes returnsEINVALlikeF_DUPFD.       Ifnewfd was open, any errors that would have been reported atclose(2) time are lost.  If this is of concern, then—unless the       program is single-threaded and does not allocate file descriptors       in signal handlers—the correct approach isnot to closenewfd       before callingdup2(), because of the race condition described       above.  Instead, code something like the following could be used:           /* Obtain a duplicate of 'newfd' that can subsequently              be used to check for close() errors; an EBADF error              means that 'newfd' was not open. */           tmpfd = dup(newfd);           if (tmpfd == -1 && errno != EBADF) {               /* Handle unexpected dup() error. */           }           /* Atomically duplicate 'oldfd' on 'newfd'. */           if (dup2(oldfd, newfd) == -1) {               /* Handle dup2() error. */           }           /* Now check for close() errors on the file originally              referred to by 'newfd'. */           if (tmpfd != -1) {               if (close(tmpfd) == -1) {                   /* Handle errors from close. */               }           }

COLOPHON top

       This page is part of theman-pages (Linux kernel and C library       user-space interface documentation) project.  Information about       the project can be found at        ⟨https://www.kernel.org/doc/man-pages/⟩.  If you have a bug report       for this manual page, see       ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.       This page was obtained from the tarball man-pages-6.15.tar.gz       fetched from       ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on       2025-08-11.  If you discover any rendering problems in this HTML       version of the page, or you believe there is a better or more up-       to-date source for the page, or you have corrections or       improvements to the information in this COLOPHON (which isnot       part of the original manual page), send a mail to       man-pages@man7.orgLinux man-pages 6.15            2025-05-17dup(2)

Pages that refer to this page:bpf(2), fcntl(2), fcntl_locking(2), F_DUPFD(2const), F_GETFL(2const), F_GETLEASE(2const), F_GETSIG(2const), flock(2), getrlimit(2), kcmp(2), lseek(2), open(2), pidfd_getfd(2), syscalls(2), fileno(3), getdtablesize(3), posix_spawn(3), epoll(7), pipe(7), signal-safety(7), unix(7)