ref: bd6c2aad586814b091ce5aca9d41cf2c51adb37b
dir: /man/2/sys-dup/
.TH SYS-DUP 2
.SH NAME
dup, fildes \- duplicate an open file descriptor
.SH SYNOPSIS
.EX
include "sys.m";
sys := load Sys Sys->PATH;
dup: fn(oldfd, newfd: int): int;
fildes: fn(fd: int): ref FD;
.EE
.fi
.SH DESCRIPTION
The Limbo programming language and its libraries
manage I/O via references to instances of abstract data type,
.BR FD ,
called a
.IR "Limbo file descriptor",
or simply `file descriptor' when the context is understood.
.B FD
holds an integer-valued file descriptor, the form used
by the operating system, in a structure that can be reference counted
and garbage collected.
When the
.B FD
value is reclaimed, the system automatically closes the associated integer file descriptor.
There are occasions when a program must access the underlying
integer file descriptor, such as when rearranging the standard input
and output for a new subprocess.
.PP
The
.B dup
call takes a valid integer file descriptor,
.IR oldfd ,
referring to an open file,
and
returns a new integer file descriptor referring to the same file.
If
.I newfd
is in the range of legal file descriptors,
.B dup
will use that for the new file descriptor
(closing any old file associated with
.IR newfd );
if
.I newfd
is \-1 the system chooses the lowest available file descriptor.
If a suitable file descriptor cannot be found,
.B dup
returns \-1.
.PP
.B Fildes
duplicates the integer file descriptor
.IR fd ,
as if by
.BI "sys->dup(" fd ",-1"),
and returns a reference to the new descriptor as an
.B FD
value,
making it usable by other functions in
.BR Sys ,
such as
.IR sys-print (2)
and
.IR sys-read (2).
(Note that as described above, the newly-allocated file descriptor will be closed automatically when the
.B FD
value is reclaimed.)
.B Fildes
returns nil
if it cannot duplicate
.IR fd .
.SH SEE ALSO
.IR sys-intro (2),
.IR sys-open (2)