Topic : TOS - The Operating System
Author :
Version : tos.hyp (December 19, 2008)
Subject : Programmieren/Atari
Nodes : 3010
Index Size : 93790
HCP-Version : 5
Compiled on : Atari
@charset : atarist
@lang :
@default : Title
@help :
@options : +g -i -s +x +zz -t4
@width : 70
View Ref-File5.10.5 Fcntl TOS Name: »Fcntl« - Perform command operations on a given file.
Opcode: 260
Syntax: int32_t Fcntl ( int16_t fh, int32_t arg, int16_t cmd );
Description: The function performs various command operations on the
file with the handle fh. The parameter cmd describes
the desired operation, and can assume the following
values. (arg here depends on the selected command):
F_DUPFD (0): Duplicates the specified file handle. The following
applies for the new interval: arg <= Handle < 32. If no
free handles exist in the specified segment, the
error-message ENHNDL will be returned. A call of Fdup (handle) is therefore equivalent to Fcntl (handle, 6L,
F_DUPFD).
F_GETFD (1): This command returns the non-inheritance flag for the
handle fh. The flag is 0 when child processes started
with Pexec are to inherit the file handle, otherwise it
has the value 1 and the parameter arg is ignored.
F_SETFD (2): This command sets the non-inheritance flag for the
handle fh. arg specifies if child processes started
with Pexec will inherit the file handle; a value of 1
indicates they will not, a value of 0 that they will.
The default value for the flag is 0 for the standard
GEMDOS handles in the region 0...5 and 1 for all
others, i.e. non-standard handles.
F_GETFL (3): This command returns the file descriptor flags that can
be altered by the user. We are here dealing with the
parameter mode specified at Fopen, as long as this has
not been altered by another call of Fcntl. arg is
ignored.
F_SETFL (4): This command sets the file descriptor flags that can be
altered by the user to arg (the other bits are ignored,
and should be set to the value 0). It is not possible
to alter the read/write mode or the modes for file
sharing.
F_GETLK (5): The parameter arg is a pointer to an flock structure,
in which information about file locks are stored. If a
lock exists then it will be copied into the structure.
During this the element l_pid will hold the PID of the
locking process. If no lock exists, then the element
l_type will be set to the value F_UNLCK. For the case
that the lock is held by another computer in a network,
the element l_pid is set to a value defined by the NFS
(Network File System). For this value, 0x1000 <= l_pid <= 0xffff. One should note that normal PID's have a
value smaller than 1000.
F_SETLK (6): This command sets (l_type = F_RDLCK or F_WRLCK) or
lifts (l_type = F_UNLCK) an advisory lock on the
specified file. If this is a FIFO queue (First-In-
First-Out), the whole file must be processed at the
same time. For the case when the lock conflicts with
locks set by other processes, the value ELOCKED will be
returned. If one tries to lift a non-existent lock, the
value ENSLOCK will be returned. One should note that
read-locks may overlap, but write-locks may not. If a
locked file is closed, or the corresponding process
terminates, then all set locks will be lifted
automatically (i.e. reset).
F_SETLKW (7): Similar to F_SETLK, with the difference that if the
lock conflicts with those from other processes, then
ELOCKED is not returned but the locked process is
suspended until the locking from the other process is
lifted.
FSTAT (0x4600): Gets the extended attributes of a file. The parameter
arg returns a pointer to an XATTR structure that is
filled in with the file's extended attributes, as if an
Fxattr call had been made. This command is supported in
MagiC as of Version 3.0.
FIONREAD (0x4601): In the parameter arg a pointer to a LONG value is
returned which shows the number of bytes that may be
read currently from a specified file handle without
causing the process to block (wait for more input). The
returned value is not necessarily correct, as the exact
amount can only be estimated in some cases. The command
is supported in MagiC as of Version 3.0.
FIONWRITE (0x4602): Similar to FIONREAD, only here the number of bytes that
may be written at present is returned. The command is
supported in MagiC as of Version 3.0.
FUTIME (0x4603): No information available at present.
FTRUNCATE (0x4604): The parameter arg is a pointer to a LONG value that
contains the new length of the file to be truncated.
The command is supported in MagiC as of Version 3.0.
FIOEXECPT (0x4605): In the parameter arg a pointer to a LONG value is
returned which specifies whether the file is in an
exception state (1) or not (0).
The following commands are to be applied to all
terminal devices such as the console or a pseudo-
terminal:TIOCGETP (0x5400): This command returns via the parameter arg a pointer to
a sgttyb structure, in which the parameters of the
terminal are defined.
TIOCSETN (0x5401): With this command one can set a new sgttyb structure
which sets the parameters of the terminal. You should
first get the terminal control parameters, modify what
you wish to change, and then set them with this call.
TIOCGETC (0x5402): This command returns via the parameter arg a pointer to
a tchars structure in which the terminal control
characters are defined.
TIOCSETC (0x5403): With this command new terminal control characters can
be set. For this one passes a pointer in arg to a
tchars structure in which the control characters are
defined. If a character is set to 0 then the
corresponding function will be disabled.
TIOCGLTC (0x5404): This command returns via the parameter arg a pointer to
a ltchars structure in which extended terminal control
characters are defined.
TIOCSLTC (0x5405): With this command one can set new extended terminal
control characters. To do this, one passes in arg a
pointer to a ltchars structure in which the control
characters are defined. If a character is set to 0 then
the corresponding function will be disabled.
TIOCGPGRP (0x5406): This command returns via the parameter arg a pointer to
the process group ID of the terminal.
TIOCSPGRP (0x5407): With this command one can set the process group ID of
the terminal. To do this, one passes in the parameter
arg a pointer to the corresponding process group. If
processes from other groups should attempt to access
this terminal (read or write) then they will be sent
job control signals (SIGTSTP etc.).
TIOCFLUSH (0x5408): With this command one can specify the type of flushing.
For this, one passes a pointer in the parameter arg to
a LONG value that describes the desired type. The
following apply:
Value Meaning
0 Flush input and output
Bit 0 set Flush input
Bit 1 set Flush output
TIOCSTOP (0x5409): This command interrupts the output to the terminal
(similar to flow control with Control-S). The parameter
arg is ignored in this case.
TIOCSTART (0x540a): This command restarts output to the terminal again
(similar to flow control with Control-Q). The parameter
arg is ignored in this case.
TIOCGWINSZ (0x540b): With this command one can inquire the size of a text
window. For this a pointer to a winsize structure is
returned via the parameter arg. If an element of this
structure has the value 0, then it means that the
corresponding value is unknown.
TIOCSWINSZ (0x540c): With this command one can set the window size. For this
a pointer to a winsize structure is passed via the
parameter arg which contains the required information.
In this connection one should note that though the
kernel handles the call, it leaves its execution to
window managers. These also send the signal SIGWINCH if
necessary.
TIOCGXKEY (0x540d): This command returns the current definition of a system
key (function, cursor etc.). For this a pointer to the
xkey structure is passed in the parameter arg. The
element xk_num of the structure has to be filled with
the desired key:
xk_num Key
0-9 F1-F10
10-19 F11-F20 (reached via Shift)
20 Cursor up
21 Cursor down
22 Cursor to right
23 Cursor to left
24 Help
25 Undo
26 Insert
27 Clr/Home
28 Shift + cursor up
29 Shift + cursor down
30 Shift + cursor to right
31 Shift + cursor to left
The NULL-terminated string associated with the key (the
convention of the C language applies) is returned via
the element xk_def.
TIOCSXKEY (0x540e): With this command one can set the current definition of
a system key (function or cursor etc.). For this a
pointer to the xkey structure is passed in the
parameter arg, in which the elements xk_num and xk_def
must have been set already. After the execution of the
command, Fread returns the text string (instead of
ASCII-0) specified in xk_def. This translation only
happens, however, if the program has been set into the
MiNT domain with Pdomain and if the terminal is reading
characters using Fread. As the string passed in xk_def
has to be NULL-terminated, one can pass a maximum of 7
characters in this way.
TIOCIBAUD (0x5412): With this command one can set the Baud rate for input
to the terminal. For this a pointer is passed via the
parameter arg to a LONG value that specifies the Baud
rate.
TIOCOBAUD (0x5413): With this command one can set the Baud rate for output
from the terminal. For this a pointer is passed via the
parameter arg to a LONG value that specifies the Baud
rate.
TIOCCBRK (0x5414): This command clears bit 3 of the TSR register (the
break condition) of the MFP68901 peripheral component.
The parameter arg is ignored.
TIOCSBRK (0x5415): This command sets bit 3 of the TSR register of the
MFP68901 peripheral component. This causes a break
signal to be sent as soon as the transmit register is
empty. The parameter arg is ignored.
TIOCGFLAGS (0x5416): This command returns in the lower 16 bits of the LONG
pointed to by the parameter arg the terminal control
flags (i.e. the current stop-bit and data-bit
configuration). Valid mask values for arg are:
Mask Meaning
0x0001 1 stop-bit
0x0002 1.5 stop-bits
0x0003 2 stop-bits
0x0000 8 data-bits
0x0004 7 data-bits
0x0008 6 data-bits
0x000C 5 data-bits
TIOCSFLAGS (0x5417): This command sets new terminal control flags that are
passed via the parameter arg.
TIOCOUTQ (0x5418): This command returns in arg a pointer to a LONG value
in which the number of bytes in the output buffer is
stored.
TIOCSETP (0x5419): Functions in a similar way to TIOCSETN, but with the
difference that (if the terminal supports TIOCOUTQ) the
function only returns when the output buffer is empty.
TCURSOFF (0x6300): This command switches off the cursor of the terminal.
The parameter arg is ignored.
TCURSON (0x6301): This command switches on the cursor of the terminal.
The parameter arg is ignored.
TCURSBLINK (0x6302): This command switches on blinking of the terminal's
cursor. The blink rate can be set with TCURSSRATE. The
parameter arg is ignored.
TCURSSTEADY (0x6303): This command switches off blinking of the terminal's
cursor again. The parameter arg is ignored.
TCURSSRATE (0x6304): This command sets the blink rate of the terminal's
cursor. For this a pointer to a WORD value is passed in
arg which specifies after how many vertical blanks the
cursor is to be inverted.
TCURSGRATE (0x6305): This command obtains the cursor blink rate of the
terminal. This is returned in a WORD value to which arg points.
The following commands are applicable only for
processes (opened as files). To open your own process
as a file, you have to specify the path for Fopen as
'U:PROC\processname.-1'. Here the extension -1 selects
your own, and -2 the parent process.
PBASEADDR (0x5002): In the parameter arg a pointer to the address of the
GEMDOS basepage of the process opened as a file is
returned. The command is supported in MagiC from
Version 3.0 onwards.
PPROCADDDR (0x5001): In the parameter arg a pointer to the address of the
PCB (Process Control Block) is returned.
PCTXTSIZE (0x5003): In the parameter arg a pointer to a LONG value is
returned in which the length of the process context
structure is specified. Two of these structures lie in
memory before the PCB, whose address may be inquired
with PPROCADDR. The first structure is responsible for
the current process context, while the second contains
the stored context of the last system call.
PSETFLAGS (0x5004): This command sets the program flags (corresponding to
those in the program header. For this a pointer to a
LONG value is passed in arg whose lower 16 bits
represent the program flags.
PGETFLAGS (0x5005): This command obtains the current program flags. For
this a pointer to these flags is returned via the
parameter arg.
PTRACESFLAGS (0x5006): This command sets the process trace flags. A pointer to
a WORD value is passed in the parameter arg that
represents the flags:
P_ENABLE = 1 (Enable tracing)
P_DOS = 2 (Trace GEMDOS calls)
P_BIOS = 4 (Trace BIOS calls)
P_XBIOS = 8 (Trace XBIOS calls)
PTRACEGFLAGS (0x5007): This command obtains the current process trace flags. A
pointer to these flags is returned via the parameter
arg.
PTRACEGO (0x5008): (from MC-68020 processor on)
PTRACEFLOW (0x5009):PTRACESTEP (0x500a):PTRACE11 (0x500b): These functions should in future enable tracing of
processes. The process to be traced must be in the
'suspended' state for this; it will be reawakened by
the trace function. These functions are however not yet
implemented at present.
PLOADINFO (0x500c): This command returns in arg a pointer to the ploadinfo structure, in which the program name and command line
are stored.
PFSTAT (0x500d): This command corresponds to FSTAT. It obtains the
extended attributes of the program file belonging to
the process.
The following commands are applicable only to files
that represent shared memory:SHMGETBLK (0x4d00): This command returns the address of a memory block
allocated with SHMSETBLK (or a NULL-pointer in case of
error). For the sake of compatibility the parameter arg must be set to the value 0. Note: Different processes
may see the memory block at different positions in
their address space. For this reason a shared memory block may not contain absolute pointers to data! The
command is supported in MagiC as of Version 3.0.
SHMSETBLK (0x4d01): A pointer is passed in the parameter arg to a memory
block that was earlier allocated with Malloc/Mxalloc.
The memory is then offered for sharing under the
filename of the file with the handle fh. For this the
file must be created in the subdirectory U:\SHM. The
block is marked in such a way that it will not be
released at the termination of the process. The length
will be obtained and used both for the opened file as
well as entered in the directory. Invalid block
addresses lead to the error-code EIMBA or to a bus- or
address-error. The command is supported in MagiC as of
Version 3.0.
The following commands are of interest in connection
with CD-ROM's:CDROMREADOFFSET (0x4300): This command obtains the block number of the first
sector of the last session of a multi-session CD. The
parameter arg contains this block number after the
call.
CDROMPAUSE (0x4301): This command causes a CD-ROM to enter the pause state
when playing an audio CD.
CDROMRESUME (0x4302): This command causes a CD-ROM to resume playing of an
audio CD (pause is rescinded).
CDROMPLAYMSF (0x4303): This command starts audio playback. The parameter arg is a pointer to a cdrom_msf structure, in which the
start and end times are to be entered in MSF notation.
CDROMPLAYTRKIND (0x4304): This command starts audio playback. The parameter arg is a pointer to a cdrom_ti structure in which the start
and end positions are to be entered in track/index
notation. In most audio CD's from the POP world the
tracks are not subdivided any further. But many
classical CD's also have finer markings within tracks
as indices. Warning: Not every CD-ROM can access
directly indices other than 1!
CDROMREADTOCHDR (0x4305): This command allows one to obtain information about the
structure of a CD. The parameter arg is a pointer to a
cdrom_tochdr structure in which the first and last
track of the CD are entered.
CDROMREADTOCENTRY (0x4306): This command allows one to obtain further information
about the structure of a CD. The parameter arg is a
pointer to a cdrom_tocentry structure in which the
desired information is entered.
CDROMSTOP (0x4307): This command stops the corresponding drive.
CDROMSTART (0x4308): This command starts the corresponding drive, and may
also close the drawer.
CDROMEJECT (0x4309): This command serves for opening the drawer of the
corresponding drive.
CDROMVOLCTRL (0x430a): This command permits altering the volume and channel
assignments of the individual audio channels. The
parameter arg is a pointer to a cdrom_volctrl structure. The command is compatible to the
corresponding SunOS call. Warning: Altering the volume
is not possible with all devices!
CDROMSUBCHNL (0x430b): This command obtains the current position data, as well
as the audio state. The parameter arg is a pointer to a
cdrom_subchnl structure.
CDROMREADMODE2 (0x430c): This command enables reading of Mode-2 sectors. Such
sectors are used by XA-CDs (e.g.: Photo-CDs without
error correction or Video-CDs) and contain 2336 bytes.
The parameter arg is a pointer to a cdrom_read structure. Warning: Not all devices can read these
sector types, and not all drivers offer this function.
CDROMREADMODE1 (0x430d): This command enables reading of Mode-1 sectors. Such
sectors have a size of 2048 bytes and are used on
normal CD-ROMs. The parameter arg is a pointer to a
cdrom_read structure. Warning: Not all devices can read
these sector types, and not all drivers offer this
function.
CDROMPREVENTREMOVAL (0x430e): This command blocks the eject function of the
corresponding CD-ROM. This can be useful, for instance,
if the device is positioned in a public place and one
wants to prevent theft of the CD.
CDROMALLOWRMOVAL (0x430f): This command releases the eject function of the
corresponding CD-ROM once more.
CDROMAUDIOCTRL (0x4310): This command permits altering the volume and channel
assignments of the individual audio channels. The
parameter arg is a pointer to a cdrom_audioctrl structure. By setting the element set of this structure
to the value 0, one can inquire the current settings.
Warning: Altering the volume is not possible with all
devices!
CDROMREADDA (0x4311): This command permits the reading of Digital Audio (DA)
sectors. Such sectors have a size of 2352 bytes, and
contain per sector 588 samples in 16-bit stereo-PCM
format. The parameter arg is a pointer to a cdrom_read structure. Warning: Not all devices can read these
sector types, and not all drivers offer this function.
CDROMGETMCN (0x4313): This command obtains the Media Catalog Number, which
can be used theoretically to identify a CD easily.
Unfortunately this information is present in only very
few CDs. The parameter arg is a pointer to a cdrom_mcn structure.
CDROMGETTISRC (0x4314): This command obtains the Track International Standard
Recording Code, which should represent unique
identifiers for individual tracks. The parameter arg is
a pointer to a cdrom_tisrc structure.
Return value: The function can return the following results:
>= 0 : No error occurred (deviations see above).
EIHNDL : Invalid file handle.
EINVFN : Command cannot be executed with the handle
fh.
Availability: As of the first in MultiTOS integrated MiNT version
1.04, and MagiC as of Version 3.0.
Group: File functions.
See also: BindingFdupFlockFopenFxattrPgetpgrpPsetpgrpMetaioctlCD-ROM definitions