Topic : The ATARI Compendium
Author : Scott Sanders / JAY Software
Version : 1.25 (20/6/2003)
Subject : Documentation
Nodes : 1117
Index Size : 32614
HCP-Version : 6
Compiled on : Atari
@charset : UTF-8
@lang : en
@default :
@help : %About
@options : +g -i -t4 +y +z
@width : 100
View Ref-FileThe TOSFile SystemGEMDOS is responsible for interaction between applications and file-based
devices. Floppy and hard disk drives as well as CD-ROM, WORM, and
Magneto-Optical drives are all accessed using GEMDOS calls.
MultiTOSPrior to the advent of MultiTOS, Atari programmers were limited to the
TOS file system for file storage and manipulation. With the introduction
of MultiTOS, it is now possible for developers to create custom file
systems so that almost any conceivable disk format becomes accessible.
As a default, MultiTOS will manage files between the TOS file system and
alternative file systems to maintain backward compatibility. Applicationswhich wish to support extra file system features may do so. The Pdomain()call may be used to instruct MultiTOS to stop performing translations on
filenames, etc. Other calls such as Dpathconf() can be used to determine
the requirements of a particular file system.
The explanation of the file system contained herein will limit itself to
the TOS file system.
Drive IdentifiersEach drive connected to an Atari system is given a unique alphabetic
identifier which is used to identify it. Drive 'A' is reserved for the
first available floppy disk drive (usually internal) and drive 'B' for the
second floppy disk drive. If only one floppy drive exists, two letters
will still be reserved and GEMDOS will treat drive 'B' as a pseudo-drive
and request disk swaps as necessary. This feature is automatically handled
by GEMDOS and is transparent to the application.
Drives 'C' through 'P' are available for use by hard disk drives. One letter
is assigned per hard drive partition so a multiple-partition drive will be
assigned multiple letters. MultiTOS extends drive letter assignments to 'Z'
drive. Drive 'U' is a special drive reserved for MultiTOS and is unavailable
for assignment.
The amount of free storage space remaining on a drive along with a drive's
basic configuration can be determined using the Dfree() call.
GEMDOS FilenamesUnder GEMDOS, each file located on a device is given a filename upon its
creation which serves to provide identification for the file. The filename
has two parts consisting of a name from one to eight characters long and
an optional file extension of up to three characters long. If a file
extension exists, the two components are separated by a period. The
extension should serve to identify the format of the data whereas the name
itself should identify the data itself.
Filenames may be changed after creation with the function Frename();
however, under no circumstances may two files with the same filename
reside in the same directory.
All GEMDOS functions ignore the alphabetic case of file and pathnames.
The following characters are legal filename characters:
Legal GEMDOS Filename Characters
A-Z, a-z, 0-9
! @ # $ % ^ & ( )
+ - = ~ ` ; ' " ,
< > | [ ] ( ) _
GEMDOS DirectoriesTo further organize data, GEMDOS provides file directories (or folders).
Each drive may contain any number of directories which, in turn, may
contain files and additional directories. This organization creates a
tree-like structure of files and folders. A file's location in this tree
is called the path.
Directory names follow the same format as GEMDOS filenames with a maximum
filename length of 8 characters and an optional 3 character extension. The
first directory of a disk which contains all subdirectories and files is
called the root directory.
The Dcreate() and Ddelete() system calls are used to create and delete
subdirectories.
Each sub-directory contains a special directory named '..' which refers to
its parent directory. In addition, each sub-directory contains a directory
named '.' which refers to itself. The root directory contains neither of
these sub-directories.
GEMDOS Path SpecificationsTo access a file, a complete path specification must be composed of the
drive letter, directory name(s), and filename. A file named 'TEST.PRG'
located in the 'SYSTEM' directory on drive 'C' would have a path
specification like the following:
C:\SYSTEM\TEST.PRG
The drive letter is the first character followed by a colon. Each
directory and subdirectory is surrounded by backslashes. If 'TEST.PRG'
were located in the root directory of 'C' the path specification would
be:
C:\TEST.PRG
The drive letter and colon may be omitted causing GEMDOS to reference the
default drive as follows:
\TEST.PRG
A filename by itself will be treated as the file in the default directory
and drive. The current GEMDOS directory and drive may be found with the
functions Dgetpath() and Dgetdrv() respectively. They may be changed with
the functions Dsetpath() and Dsetdrv().
WildcardsThe GEMDOS functions Fsfirst() and Fsnext() are used together to enumerate
files of a given path specification. These two functions allow the use of
wildcard characters to expand their search parameters.
The '?' character is used to represent exactly one unknown character. The
'*' character is used to represent any number of unknown characters. The
following table gives some examples of the uses of these characters.
Filename Found Not Found
*.* All files None
*.GEM TEST.GEM TEST.G
ATARI.GEM ATARI.IMG
ATARI.GEMA?ARI.? ATARI.O ADARI.IMG
ADARI.C ATARI.GEMATARI.??? ATARI.GEM ATARI.O
ATARI.IMG ATARI.C
Disk Transfer Address (DTA)When using Fsfirst() and Fsnext() to build a list of files, TOS uses the
Disk Transfer Address (DTA) to store information about each file found.
The format for the DTA structure is as follows:
typedef struct
{
BYTE d_reserved[21]; /* Reserved - Do Not Change */
BYTE d_attrib; /* GEMDOS File Attributes */
UWORD d_time; /* GEMDOS Time */
UWORD d_date; /* GEMDOS Date */
LONG d_length; /* File Length */
char d_fname[14]; /* Filename */
} DTA;
When a process is started, its DTA is located at a point where it could
overlay potentially important system structures. To avoid overwriting
memory a process wishing to use Fsfirst() and Fsnext() should allocate
space for a new DTA and use Fsetdta() to instruct the OS to use it. The
original location of the DTA should be saved first, however. Its location
can be found with the call Fgetdta(). At the completion of the operation
the old address should be replaced with Fsetdta().
File AttributesEvery TOS file contains several attributes which define it more specifically.
File attributes are specified when a file is created with Fcreate() and can
be altered later with Fattrib().
The 'read-only' attribute bit is set to prevent modification of a file. This
bit should be set at the user's discretion and not cleared unless the user
explicitly requests it.
If the 'hidden' attribute is set, the file will not be listed by the
desktop or file selector. These files may still be accessed in a normal
manner but will not be present in an Fsfirst() or Fsnext() search unless
the correct Fsfirst() bits are present.
The 'system' attribute is unused by TOS but remains for MS-DOS compatibility.
The 'volume label' attribute should be present on a maximum of one file
per drive. The file which has it set should be in the root directory and
have a length of 0. The filename indicates the volume name of the drive.
The 'archive' attribute is a special bit managed by TOS which indicates
whether a file has been written to since it was last backed up. Any time
a Fcreate() call creates a file or Fwrite() is used on a file, the Archive
bit is set. This enables file backup applications to know which files
have been modified since the last backup. They are responsible for
clearing this bit when backing up the file.
File Time/Date StampWhen a file is first created a special field in its directory entry is
updated to contain the date and time of creation. Fdatime() can be used to
access or modify this information as necessary.
File MaintenanceNew files should be created with Fcreate(). When a file is successfully
created a positive file handle is returned by the call. That handle is
what is used to identify the file for all future operations until the file
is closed. After a file is closed its handle is invalidated.
Files which are already in existence should be opened with Fopen(). As
with Fcreate(), this call returns a positive file handle upon success
which is used in all subsequent GEMDOS calls to reference the file.
Each process is allocated an OS dependent number of file handles. If an
application attempts to open more files than this limit allows, the open
or create call will fail with an appropriate error code. File handles may
be returned to the system by closing the open file with Fclose().
Fopen() may be used in read, write, or read/write mode. In read mode,
Fread() may be used to access existing file contents. In write mode, any
original information in the file is not cleared but the data may be
overwritten with Fwrite(). In read/write mode, either call may be used
interchangeably.
Every file has an associated file position pointer. This pointer is used
to determine the location for the next read or write operation. This
pointer is expressed as a positive offset from the beginning of the file
(position 0) which is set upon first creating or opening a file. The
pointer may be read or modified with the function Fseek().
Existing files may be deleted with the GEMDOS call Fdelete().
File/Record LockingFile and record locking allow portions or all of a file to be locked against
access from another computer over a network or another process in the same
system.
All versions of TOS have the ability to support file and record locking but
not all have the feature installed. If the '_FLK' cookie is present in the
system cookie jar then the Flock() call is present. This call is used to
create locks on individual sections (usually records) in a file.
Locking a file in use, when possible, is recommended to prevent other
processes from modifying the file at the same time.
Special File HandlesSeveral special file handles are available for access through the standard
Fopen()/Fread()/Fwrite() calls. They are as follows:
Name Handle Filename Device
GSH_BIOSCON 0xFFFF CON: Console (screen). Special characters
such as the carriage return, etc. are
interpreted.
GSH_BIOSAUX 0xFFFE AUX: Modem (serial port). This is the
ST-compatible port for machines with
more than one.
GSH_BIOSPRN 0xFFFD PRN: Printer (attached to the Centronics
Parallel port).
GSH_BIOSMIDIIN 0xFFFC Midi In
GSH_BIOSMIDIOUT 0xFFFB Midi Out
GSH_CONIN 0x00 - Standard Input (usually directed to
GSH_BIOSCON)
GSH_CONOUT 0x01 - Standard Output (usually directed to
GSH_BIOSCON)
GSH_AUX 0x02 - Auxillary (usually directed to
GSH_BIOSAUX)
GSH_PRN 0x03 - Printer (usually directed to
GSH_BIOSPRN)
None 0x04 - Unused
None 0x05 - Unused
None 0x06 User- User Process File Handles
and up Specified
These files may be treated like any other GEMDOS files for input/output
and locking. Access to these devices is also provided with GEMDOS character
calls (see later in this chapter).
File RedirectionInput and output to a file may be redirected to an alternate file handle.
For instance you may redirect the console output of a TOS process to the
printer.
File redirection is handled by the use of the Fforce() call. Generally
you will want to make a copy of the file handle with Fdup() prior to
redirecting the file so that it may be restored to normal operation when
complete.