ref: 41e27b2d10c6a60c49931332e8677438736a1e36
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)