Atari ST series Technical Reference Manual page 139

GEMDOS File System Functions
for that device. Then, after you finish the redirection, you
can change the handle back, using the temporary copy.
The second reason for duplicating a handle is that it
gives you a temporary copy that can be used to substitute for
another standard device. If you're going to replace the screen
output with output to the printer, for instance, you'll need
two handles for the printer, one for the standard list device,
and one for the standard output device.
To create a user-designated handle that duplicates one of
the standard file handles, use the Fdup() function:
int newhandle, handle;
newhandle = Fdup(handle);
where handle is one of the standard device handles (0-5). If
Fdup() is successful, it returns a user-designated file handle
(greater than five) that refers to the same file.
To redirect I/O from a standard device handle to a user-
designated one, use the function Fforce():
word status, standard, user;
status = Fforce(standard, user);
where standard is the file handle of the standard file, and user
is the handle of the user-designated file that replaces that
standard file. If the operation is successful, a 0 is returned in
status. Otherwise, a GEMDOS error code such as EIHNDL is
returned (see Appendix D).
131