projects / unix-history / blame
| Commit | Line | Data |
|---|---|---|
| 931b8415 CL |
1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
| 2 | .\" All rights reserved. | |
| ff35cc74 | 3 | .\" |
| 931b8415 | 4 | .\" %sccs.include.redist.man% |
| ff35cc74 | 5 | .\" |
| 931b8415 CL |
6 | .\" @(#)dup.2 6.4 (Berkeley) %G% |
| 7 | .\" | |
| 8 | .Dd | |
| 9 | .Dt DUP 2 | |
| 10 | .Os BSD 4 | |
| 11 | .Sh NAME | |
| 12 | .Nm dup , | |
| 13 | .Nm dup2 | |
| 14 | .Nd duplicate an existing file descriptor | |
| 15 | .Sh SYNOPSIS | |
| 16 | .Fd #include <unistd.h> | |
| 17 | .Ft int | |
| 18 | .Fn dup "int oldd" | |
| 19 | .Ft int | |
| 20 | .Fn dup2 "int oldd" "int newd" | |
| 21 | .Sh DESCRIPTION | |
| 22 | .Fn Dup | |
| 23 | duplicates an existing object descriptor and returns its value to | |
| 24 | the calling process | |
| 25 | .Fa ( newd | |
| 26 | = | |
| 27 | .Fn dup oldd ) . | |
| 28 | The argument | |
| 29 | .Fa oldd | |
| 30 | is a small non-negative integer index in | |
| 936824e3 KM |
31 | the per-process descriptor table. The value must be less |
| 32 | than the size of the table, which is returned by | |
| 931b8415 CL |
33 | .Xr getdtablesize 2 . |
| 34 | The new descriptor returned by the call | |
| 35 | is the lowest numbered descriptor | |
| 36 | currently not in use by the process. | |
| 37 | .Pp | |
| 936824e3 | 38 | The object referenced by the descriptor does not distinguish |
| 931b8415 CL |
39 | between |
| 40 | .Fa oldd | |
| 41 | and | |
| 42 | .Fa newd | |
| 43 | in any way. | |
| 44 | Thus if | |
| 45 | .Fa newd | |
| 46 | and | |
| 47 | .Fa oldd | |
| 48 | are duplicate references to an open | |
| 936824e3 | 49 | file, |
| 931b8415 CL |
50 | .Xr read 2 , |
| 51 | .Xr write 2 | |
| 936824e3 | 52 | and |
| 931b8415 | 53 | .Xr lseek 2 |
| 28a14409 MK |
54 | calls all move a single pointer into the file, |
| 55 | and append mode, non-blocking I/O and asynchronous I/O options | |
| 56 | are shared between the references. | |
| 936824e3 KM |
57 | If a separate pointer into the file is desired, a different |
| 58 | object reference to the file must be obtained by issuing an | |
| 59 | additional | |
| 931b8415 | 60 | .Xr open 2 |
| 936824e3 | 61 | call. |
| 28a14409 | 62 | The close-on-exec flag on the new file descriptor is unset. |
| 931b8415 CL |
63 | .Pp |
| 64 | In | |
| 65 | .Fn dup2 , | |
| 66 | the value of the new descriptor | |
| 67 | .Fa newd | |
| 68 | is specified. If this descriptor is already | |
| 936824e3 | 69 | in use, the descriptor is first deallocated as if a |
| 931b8415 | 70 | .Xr close 2 |
| 936824e3 | 71 | call had been done first. |
| 931b8415 CL |
72 | .Sh RETURN VALUES |
| 73 | The value -1 is returned if an error occurs in either call. | |
| 936824e3 | 74 | The external variable |
| 931b8415 | 75 | .Va errno |
| 936824e3 | 76 | indicates the cause of the error. |
| 931b8415 CL |
77 | .Sh ERRORS |
| 78 | .Fn Dup | |
| 936824e3 | 79 | and |
| 931b8415 | 80 | .Fn dup2 |
| 936824e3 | 81 | fail if: |
| 931b8415 CL |
82 | .Bl -tag -width Er |
| 83 | .It Bq Er EBADF | |
| 84 | .Fa Oldd | |
| 85 | or | |
| 86 | .Fa newd | |
| 87 | is not a valid active descriptor | |
| 88 | .It Bq Er EMFILE | |
| 936824e3 | 89 | Too many descriptors are active. |
| 931b8415 CL |
90 | .El |
| 91 | .Sh SEE ALSO | |
| 92 | .Xr accept 2 , | |
| 93 | .Xr open 2 , | |
| 94 | .Xr close 2 , | |
| 95 | .Xr fcntl 2 , | |
| 96 | .Xr pipe 2 , | |
| 97 | .Xr socket 2 , | |
| 98 | .Xr socketpair 2 , | |
| 99 | .Xr getdtablesize 2 | |
| 100 | .Sh STANDARDS | |
| 101 | .Fn Dup | |
| 102 | and | |
| 103 | .Fn dup2 | |
| 104 | are expected to conform | |
| 105 | to IEEE Std 1003.1-1988 | |
| 106 | .Pq Dq Tn POSIX . |