<chapter>
<title>The NitrOS-9 File System</title>
<section>
<title>Introduction to the Unified Input/Output System</title>
<para>
NitrOS-9 has a unified input/output system in which data transfers to
ALL I/O devices are performed in almost exactly the same manner,
regardless of the particular hardware devices involved. It may seem
that the different operational characteristics of the I/O devices
might make this difficult. After all, line printers and disk drives
behave much differently. However, these differences can mostly be
overcome by defining a set of standardized
<emphasis>logical functions</emphasis> for
all devices and by making all I/O devices conform to these
conventions, using software routines to eliminate hardware
dependencies wherever possible. This produces a much simpler and
more versatile input/output system.
</para>
<para>
NitrOS-9's unified I/O system is based upon logical entities called
&quot;I/O paths&quot;. Paths are analogous to &quot;software I/O channels&quot; which
can be routed from a program to a mass-storage file, any other I/O
device, or even another program. Another way to say the same thing
is that paths are files, and all I/O devices behave as files.
</para>
<para>
Data transferred through paths may be processed by NitrOS-9 to
conform to the hardware requirements of the specific I/O device
involved. Data transfers can be either bidirectional (read/write)
or unidirectional (read only or write only), depending on the device
and/or how the path was established.
</para>
<para>
Data transferred through a path is considered to be a stream of
8-bit binary bytes that have no specific type or value: what the
data actually represents depends on how it is used by each program.
This is important because it means that NitrOS-9 does not require data
to have any special format or meaning.
</para>
<para>
Some of the advantages of the unified I/O system are:
</para>
<itemizedlist mark="square">
<listitem><para>
Programs will operate correctly regardless of the particular I/O
devices selected and used when the program is actually executed.
</para></listitem>
<listitem><para>
Programs are highly portable from one computer to another, even
when the computers have different kinds of I/O devices.
</para></listitem>
<listitem><para>
I/O can be redirected to alternate files or devices when the
program is run, without having to alter the program.
</para></listitem>
<listitem><para>
New or special device driver routines can easily be created and
installed by the user.
</para></listitem>
</itemizedlist>
</section>

<section id="sec3.1">
<title>Pathlists: How Paths Are Named</title>
<para>
Whenever a path is established (or &quot;opened&quot;), NitrOS-9 must be given
a description of the &quot;routing&quot; of the path. This description is
given in the form of a character string called a &quot;pathlist&quot;. It
specifies a particular mass-storage file, directory file, or any
other I/O device. NitrOS-9 &quot;pathlists&quot; are
similar to &quot;filenames&quot; used
by other operating systems.
</para>
<para>
The name &quot;pathlist&quot; is used instead
of &quot;pathname&quot; or &quot;filename&quot;
because in many cases it is a list consisting of more than one name
to specify a particular I/O device or file. In order to convey all
the information required, a pathlist may include a device name, one
or more directory file names and a data file name. Each name within
a pathlist is separated by slash &quot;/&quot; characters.
</para>
<para>
Names are used to describe three kinds of things:

<itemizedlist>
<listitem><para>Names of Physical I/O Devices</para></listitem>
<listitem><para>Names of Regular Files</para></listitem>
<listitem><para>Names of Directory Files</para></listitem>
</itemizedlist>


Names can have one to 29 characters, all of which are used for
matching. They may be composed of any combination of the following characters:
</para>

<simplelist>
<member>uppercase letters: A - Z</member>
<member>lowercase letters: a - z</member>
<member>decimal digits: 0 - 9</member>
<member>underscore: _</member>
<member>period: . (cannot be the first character)</member>
</simplelist>

<para>
Here are examples of <emphasis>legal</emphasis> names:
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="2.5in"/>
<colspec colwidth="2.5in"/>
<tbody>
<row>
<entry>raw.data.2</entry>
<entry>projectreview.backup</entry>
</row>
<row>
<entry>reconciliation.report</entry>
<entry>X042953</entry>
</row>
<row>
<entry>RJJones</entry>
<entry>22search.bin</entry>
</row>
</tbody>
</tgroup>
</informaltable>

Here are examples of <emphasis>illegal</emphasis> names:

<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="3.1in"/>
<colspec colwidth="2.0in"/>
<tbody>
<row>
<entry>max*min</entry>
<entry>(* is not a legal character)</entry>
</row>
<row>
<entry>.data</entry>
<entry>(does not start with a letter)</entry>
</row>
<row>
<entry>open orders</entry>
<entry>(cannot contain a space)</entry>
</row>
<row>
<entry>this.name.obviously.has.more.than.29.characters</entry>
<entry>(too long)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</section>

<section id="sec3.2">
<title>I/O Device Names</title>
<para>
Each physical input/output device supported by the system must
have a unique name. The actual names used are defined when the
system is set up and cannot be changed while the system is running.
The device names used for the Color Computer are:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="0.7in"/>
<colspec colwidth="2in"/>
<tbody>
<row>
<entry>TERM</entry>
<entry>Video display/keyboard</entry>
</row>
<row>
<entry>P</entry>
<entry>Printer port</entry>
</row>
<row>
<entry>D0</entry>
<entry>Disk drive unit zero</entry>
</row>
<row>
<entry>D1</entry>
<entry>Disk drive unit one</entry>
</row>
<row>
<entry>PIPE</entry>
<entry>Pipes</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
Device names may only be used as the first name of a pathlist,
and must be preceded by a slash &quot;/&quot; character to indicate that the
name is that of an I/O device. If the device is not a disk or
similar device the device name is the only name allowed. This is
true for devices such as terminals, printers, etc. Some examples of
of pathlists that refer to I/O devices are:
</para>

<simplelist>
<member>/TERM</member>
<member>/P</member>
<member>/D1</member>
</simplelist>

<para>
I/O device names are actually the names of the &quot;device descriptor
modules&quot; kept by NitrOS-9 in an internal data structure called the
&quot;module directory&quot; (See the NitrOS-9 System Programmer's manual for more
information about device driver and descriptor modules). This
directory is automatically set up during NitrOS-9's system start up
sequence, and updated as modules are added or deleted while the
system is running.
</para>
</section>

<section id="sec3.3">
<title>Multifile Devices And Directory Files</title>
<para>
Multifile devices are mass storage devices (usually disk systems)
that store data organized into separate logical entities called
&quot;files&quot;. Each file has a name which is entered in a directory file.
Every multifile device has a master directory (called the &quot;root
directory&quot;) that includes the names of the files and sub-directories
stored on the device. The root directory is created automatically
when the disk is initialized by the <command>format</command> command.
</para>
<para>
Pathlists that refer to multifile devices may have more than one
name. For example, to refer to the file &quot;mouse&quot; whose name appears
in the root directory of device &quot;D1&quot; (disk drive one) the following
pathlist is used:
</para>
<para>

/d1/mouse

</para>
<para>
When NitrOS-9 is asked to create a path, it uses the names in the
pathlist sequentially from left to right to search various
directories to obtain the necessary routing information. These
directories are organized as a tree-structured hierarchy. The
highest-level directory is called the &quot;device directory&quot;, which
contains names and linkages to all the I/O devices on a given
system. If any of the devices are of a multifile type they each
have a root directory, which is the next-highest level.
</para>
<para>
The diagram below is a simplified file system tree of a typical
NitrOS-9 system disk. Note that device and directory names are capitalized
and ordinary file names are not. This is a customary (but
not mandatory) practice which allows you to easily identify directory
files using the short form of the <command>dir</command> command.
</para>
<literallayout class="monospaced">
                      System Device Directory
              +---------------------------------+
              !            !          !         !
              D0          TERM        P         D1
              !                                 !
              !                                 !
              !                                 !
      D0 Root Directory                 D1 Root Directory
  +----------------------+           +----------------------+
  !           !          !           !          !           !
DEFS      startup      CMDS        file1      file2        file3
  !                      !
  !                      !
  !                      !
--+--         +-----+----+-----+-----+ 
  !           !     !    !     !     !
OS9Defs     copy  list  dir   del  backup
</literallayout>
<para>
The device names in this example system are &quot;TERM&quot;,
&quot;P&quot;, &quot;D0&quot; and
&quot;D1&quot;. The root directory of device
&quot;D0&quot; includes two directory
files, <filename class="directory">DEFS</filename> and <filename class="directory">CMDS</filename>, and one ordinary file &quot;startup&quot;. Notice that
device &quot;D1&quot; has in its root directory three ordinary files. In
order to access the file &quot;file2&quot; on
device &quot;d1&quot;, a pathlist having
two names must be used:
<screen>
list /d1/file2
</screen>
To construct a pathlist to access the file &quot;dir&quot; on device
&quot;d0&quot; it is necessary to include in the pathlist the name of the
intermediate directory file <filename class="directory">CMDS</filename>. For example, to copy this file
requires a pathlist having three names to describe the &quot;from&quot; file:
<screen>
copy /d0/cmds/dir temp
</screen>
</para>
</section>

<section id="sec3.4">
<title>Creating and Using Directories</title>
<para>
It is possible to create a virtually unlimited number of levels
of directories on a mass storage device using the <command>makdir</command> command.
Directories are a special type of file (see <xref linkend="sec3.8.1"/>). They can be
processed by the same I/O functions used to access regular files
which makes directory-related processing fairly simple.
</para>
<para>
To demonstrate how directories work, assume that the disk in
drive one (&quot;d1&quot;) has been freshly formatted so that it has a root
directory only. The <command>build</command> command can be used to create a text file
on &quot;d1&quot;. The <command>build</command> command will print out &quot;?&quot; as a prompt to
indicate that it is waiting for a text line to be entered. It will
place each line into the text file until an empty line with only a
carriage return is entered, as shown below:
</para>
<screen>
OS9: build /d1/file1
? This is the first file that
? we created.
? [ENTER]
</screen>

<para>
The <command>dir</command> command will now indicate the existence of the new file:
</para>

<screen>
OS9: dir /d1

   Directory of /d1  15:45:29
file1
</screen>

<para>
The <command>list</command> command can be used to display the text stored in the
file:
</para>

<screen>
OS9: list /d1/file1

This is the first file
that we created.
</screen>

<para>
The <command>build</command> command again is again used to create two more text
files:
</para>

<screen>
OS9: build /d1/file2
? This is the second file
? that we created.
? [ENTER]

OS9: build /d1/file3
? This is another file.
? [ENTER]
</screen>

<para>
The <command>dir</command> command will now show three file names:
</para>

<screen>
OS9: dir /d1
   Directory of /D1  15:52:29
file1           file2           file3
</screen>

<para>
To make a new directory in this directory, the <command>makdir</command> command is
used. The new directory will be called <filename class="directory">NEWDIR</filename>. Notice that
throughout this manual directory names are always capitalized. This
is <emphasis>not</emphasis> a requirement of NitrOS-9 (see <xref linkend="sec3.1"/>) . Rather, it is a
practice popular with many NitrOS-9 users because it allows easy identification
of directory files at all times (assuming all other file names use
lower-case letters).
</para>

<screen>
OS9: makdir /D1/NEWDIR
</screen>

<para>
The directory file <filename class="directory">NEWDIR</filename> is now a file listed in D1's root
directory:
</para>

<screen>
OS9: dir /D1

   Directory of /D1  16:04:31
file1           file2           file3          NEWDIR
</screen>

<para>
Now we will create a new file and put in the new directory, using
the <command>copy</command> command to duplicate <filename>file1</filename>:
</para>
<screen>
OS9: copy /d1/file1 /d1/newdir/file1.copy
</screen>
<para>
Observe that the second pathlist now has three names: the name of
the root directory (&quot;D1&quot;), the name of the next lower directory
(<filename class="directory">NEWDIR</filename>), then the actual file name (<filename class="directory">file1.copy</filename>). Here's what
the directories look like now:
</para>
<screen>
          D1 Root Directory
    +---------+--------+--------+
    !         !        !        !
  NEWDIR    file1    file2    file3
    !
    !
file1.copy
</screen>
<para>
The <command>dir</command> command can now show the files in the new directory:
</para>
<screen>
OS9: dir /D1/NEWDIR

   Directory of /D1/NEWDIR
file1.copy
</screen>
<para>
It is possible to use <command>makdir</command> to create additional new directories
within <filename class="directory">NEWDIR</filename>, and so on, limited only by available disk
space.
</para>
</section>

<section id="sec3.5">
<title>Deleting Directory Files</title>
<para>
The <command>del</command> command cannot be used to directly delete a directory
file. If a directory file that still contained file names were to
be deleted, NitrOS-9 would have no way to access the files or to return
their storage to the unallocated storage pool. Therefore, the
following sequence must be performed to delete a directory file:
</para>
<para>
1. All file names in the directory must be deleted.
</para>
<para>
2. The <command>attr</command> command is used to turn off the files directory
attrribute (-d option), making it an ordinary file (see <xref linkend="sec3.8"/>).
</para>
<para>
3. The file may now be deleted using the <command>del</command> command.
</para>
<para>
A simpler alternative is to use the <command>deldir</command> command to automatically
perform all these steps for you.
</para>
</section>

<section id="sec3.6">
<title>Additional Information About Directories</title>
<para>
The NitrOS-9 directory system is very useful because it allows each
user to privately organize files as desired (by project, function,
etc.), without affecting other files or other user's files. Another
advantage of the hierarchical directory system is that files with
identical names can be kept on the same device as long as the names
are in different directories. For example, you can have a set of
test files to check out a program using the same file names as the
program's actual working files. You can then run the program with
test data or actual data simply by switching directories.
</para>
<para>
Here are some important characteristics relating to use of directory
files:
</para>
<itemizedlist>
<listitem><para>
Directories have the same ownership and security attributes
and rules as regular files.
</para></listitem>
<listitem><para>
The name of a given file appears in exactly one directory.
</para></listitem>
<listitem><para>
Files can only be added to directories when they are created.
</para></listitem>
<listitem><para>
A file and the directory in which its name is kept must reside on
the same device.
</para></listitem>
</itemizedlist>
</section>

<section id="sec3.7">
<title>Using and Changing Working Directories</title>
<para>
Each program (process) has two &quot;working directories&quot; associated
with it at all times: a &quot;data directory&quot; and an &quot;execution
directory&quot;. The working directory mechanism allows the name searching
involved in pathlist processing to start at any level (subtree)
of the file system hierarchy. Any directory that the user has
permission to access (see <xref linkend="sec3.8"/>) can be made a working directory.
</para>
<para>
The rules used to determine whether pathlists refer to the
current working directory or not are simple:
</para>
<para>
---&gt; When the first character of a pathlist IS a &quot;/&quot;,
processing of the pathlist starts at the device directory,
e.g., the first name MUST be a device name.
</para>
<para>
---&gt; When the first character of a pathlist IS NOT a &quot;/&quot;,
processing of the pathlist starts at the current working
directory.
</para>
<para>
Notice that pathlists starting with a &quot;/&quot;
<emphasis>must</emphasis> be complete, in
other words, they must have all names required to trace the pathlist
from the device directory down through all intermediate directories
(if any). For example:
</para>
<informalexample>
<para>
/d2/JOE/WORKINGFILES/testresults
</para>
</informalexample>
<para>
On the other hand, use of the current working directory allows
all names in the file hierarchy tree to be implied instead of
explicitly given. This not only makes pathlists shorter, but allows
NitrOS-9 to locate files faster because (typically) fewer directories
need be searched. For example, if the current working directory is
<filename class="directory">/D1/PETE/GAMES</filename> and a pathlist is given such as:
</para>
<para>
baseball
</para>
<para>
the actual pathlist <emphasis>implied</emphasis> is:
</para>
<para>
/D1/PETE/GAMES/baseball
</para>
<para>
Pathlists using working directories can also specify additional
lower-level directories. Referring to the example above, the
pathlist:
</para>
<para>
ACTION/racing
</para>
<para>
implies the complete pathlist:
</para>
<para>
/D1/PETE/GAMES/ACTION/racing
</para>

<section id="sec3.7.1">
<title>Automatic Selection of Working Directories</title>
<para>
Recall that two working directories are referred to as the
&quot;current execution directory&quot; and the &quot;current data directory&quot;. The
reason two working directories are maintained is so that files
containing
<emphasis>programs</emphasis> can be organized in different directories than
files containing <emphasis>data</emphasis>.
NitrOS-9 automatically selects either working
directory, depending on the usage of the pathlist:
</para>
<para>
---&gt; NitrOS-9 will search the execution directory when it attempts to
load files into memory assumed to be executable programs. This
means that programs to be run as commands or loaded into
memory must be in the current execution directory.
</para>
<para>
---&gt; The data directory is used for all other file references (such
as text files, etc.)
</para>
<para>
Immediately after startup, NitrOS-9 will set the data directory to be
(the root directory of) the system disk drive (usually &quot;D0&quot;), and
the working directory to be a directory called <filename class="directory">cmds</filename> on the same
drive (<filename class="directory">/D0/cmds</filename>). On timesharing systems, the <command>login</command> command
selects the initial execution and data directories to the file names
specified in each user's information record stored in the system
password file(ref. <xref linkend="sec5.4.2"/>).
</para>
<para>
Here is an example of a <command>shell</command> command statement using the default
working directory notation, and its equivalent expansion:
</para>
<screen>
copy file1 file2
</screen>
<para>
If the current execution directory is <filename class="directory">/D0/CMDS</filename> and the current
data directory is <filename class="directory">/D0/JONES</filename>, the same command, fully expanded to
show complete pathlists implied is:
</para>
<screen>
OS9: /D0/CMDS/copy /D0/JONES/filel /D0/JONES/file2
</screen>
<para>
Notice that the first pathlist <command>copy</command> expands to the current working
directory pathlist because it is assumed to be an executable program
but the two other file names expand using the data directory because
they are not assumed to be executable.
</para>
</section>

<section id="sec3.7.2">
<title>Changing Current Working Directories</title>
<para>
The built-in shell commands <command>chd</command> and <command>chx</command> can be used to
independently change the current working data and execution
directories, respectively. These command names must be followed by
a pathlist that describes the new directory file. You must have
permission to access the directory according to normal file security
rules. Here are some examples:
</para>
<screen>
OS9: chd /D1/MY.DATAFILES

OS9: chx /D0/TESTPROGRAMS
</screen>
<para>
When using the <command>chd</command> or <command>chx</command> commands, pathlists work the same as they
do for regular files, except for the last name in the pathlist must
be a directory name. If the pathlist begins with a &quot;/&quot; , NitrOS-9 will
begin searching in the device directory for the new working
directory, otherwise searching will begin with the present directory.
 For example, the following sequence of commands set the
working directory to the same file:
</para>
<screen>
OS9: CHD /D1/SARAH
OS9: CHD PROJECT1

OS9: CHD /D1/SARAH/PROJECT1    (same effect as above)
</screen>
</section>

<section id="sec3.7.3">
<title>Anonymous Directory Names</title>
<para>
Sometimes is useful to be able to refer to the current directory
or the next higher-level directory, but its name (full pathlist) may
not be known. Because of this, special &quot;name substitutes&quot; are
available. They are:
</para>
<para>
<filename class="directory">.</filename> refers to the present working directory
</para>
<para>
<filename class="directory">..</filename> refers to the directory that contains the name of the present
directory (e.g., the next highest level directory)
</para>
<para>
<filename class="directory">...</filename> refers to directory two levels up, and so on
</para>
<para>
These can be used in place of pathlists and/or the first name in a
pathlist. Here are some examples:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="1.5in"/>
<colspec colwidth="3in"/>
<tbody>
<row>
<entry>OS9: dir .</entry>
<entry>lists file names in the working data directory</entry>
</row>
<row>
<entry>OS9: dir ..</entry>
<entry>lists names in the working data directory's parent directory.</entry>
</row>
<row>
<entry>OS9: del ../temp</entry>
<entry>deletes the file <filename>temp</filename> from the
working data directory's parent directory.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
The substitute names refer to either the execution or data
directories, depending on the context in which they are used.
For example, if <filename class="directory">..</filename> is used in a pathlist of a file which
will be loaded and/or executed, it will represent the parent
directory of the execution directory. Likewise, if <filename class="directory">.</filename> is used in a
pathlist describing a program's input file, it will represent the
current data directory.
</para>
</section>
</section>

<section id="sec3.8">
<title>The File Security System</title>
<para>
Every file (including directory files) has properties called
<emphasis>ownership</emphasis>
and <emphasis>attributes</emphasis> which determine who may access the file and
how it many be used.
</para>
<para>
NitrOS-9 automatically stores with each file the user number
associated with the process that created it. This user is considered
to be the &quot;owner&quot; of the file.
</para>
<para>
Usage and security functions are based on &quot;attributes&quot;, which
define how and by whom the file can be accessed. There are a total
of seven attributes, each of which can be turned &quot;off&quot; or
&quot;on&quot;
independently. The &quot;d&quot; attribute is used to indicate (when on) that
the file is a directory file. The other six attributes control
whether the file can be read, written to, or executed, by either the
owner or by the &quot;public&quot; (all other users). Specifically, these six
attributes are:
</para>
<para>
WRITE PERMISSION FOR OWNER: If on, the owner may write to the file
or delete it. This permission can be used to protect important
files from accidental deletion or modification.
</para>
<para>
READ PERMISSION FOR OWNER: If on, the owner is allowed to read
from the file. This can be used to prevent &quot;binary&quot; files from
being used as &quot;text&quot; files
</para>
<para>
EXECUTE PERMISSION FOR OWNER: If on, the owner can load the file into memory
and execute it. Note that the file <emphasis>must</emphasis> contain one or
more valid NitrOS-9 format memory modules in order to actually load
</para>
<para>
The following &quot;public permissions&quot; work the same way as
the &quot;owner permissions&quot; above but are applied to processes having
DIFFERENT user numbers than the file's owner.
</para>
<para>
WRITE PERMISSION FOR PUBLIC: If on, any other user may write to or
delete the file.
</para>
<para>
READ PERMISSION FOR PUBLIC: If on, any other user may read (and
possibly copy) the file.
</para>
<para>
EXECUTE PERMISSION FOR PUBLIC: If on, any other user may execute
the file.
</para>
<para>
For example, if a particular file had all permissions on except
&quot;write permit to public&quot; and &quot;read permit to public&quot;, the owner
would have unrestricted access to the file, but other users could
execute it, but not read, copy, delete, or alter it.
</para>

<section id="sec3.8.1">
<title>Examining and Changing File Attributes</title>
<para>
The <command>dir</command> command may be used to examine the security permissions
of the files in any particular directory when the &quot;e&quot; option is
used. An example using the <command>dir e</command> command to show the detailed
attributes of the files in the current working directory is:
</para>
<screen>
   Directory of .   2003/03/04 10:20

Owner  Last Modified    Attributes Sector Bytecount Name
----- ----------------- ---------- ------ --------- ----
   1  2002/05/29 14:02   --e--e-r      47        42 file1
   0  2002/10/12 02:15   ---wr-wr      48        43 file2
   3  2002/04/29 23:35   -s----wr      51        22 file3
   1  2003/01/06 16:19   d-ewrewr      6D       800 NEWDIR
</screen>

<para>
This display is fairly self-explanatory. The &quot;attributes&quot; column
shows which attributes are currently on by the presence or absence
of associated characters in the following format:
</para>
<para>
 dsewrewr
</para>

<para>
The character positions correspond to from left to right: directory;
sharable; public execute; public write; public read; owner execute;
owner write; owner read. The <command>attr</command> command is used to examine or
change a file's attributes. Typing <command>attr</command> followed by a file name
will result in the present attributes to be displayed, for example:
</para>

<screen>
OS9: attr file2
-s-wr-ewr
</screen>

<para>
If the command is used with a list of one or more attribute abbreviations,
the file's attributes will be changed accordingly (if
legal). For example, the command:
</para>
<screen>
OS9: attr file2 pw pr -e -pe
</screen>
<para>
enables public write and public read permissions and removes execute
permission for both the owner and the public.
</para>
<para>
The &quot;directory&quot; attribute behaves somewhat differently than the
read, write, and execute permissions. This is because it would be
quite dangerous to be able to change directory files to normal files,
and creation of a directory requires special initialization.
Therefore, the <command>attr</command> command
<emphasis>cannot</emphasis> be used to turn
the directory (d) attribute on (only <command>makdir</command> can), and can be used
to turn it off <emphasis>only</emphasis> if the directory is empty.
</para>
</section>
</section>

<section id="sec3.9">
<title>Reading and Writing From Files</title>
<para>
A single file type and format is used for all mass storage files.
Files store an ordered sequence of 8-bit bytes. NitrOS-9 is not usually
sensitive to the contents of files for most functions. A given file
may store a machine language program, characters of text, or almost
anything else. Data is written to and read from files exactly as
given. The file can be any size from zero up to the maximum
capacity of the storage device, and can be expanded or shortened as
desired.
</para>
<para>
When a file is created or opened a &quot;file pointer&quot; is established
for it. Bytes within the file are addressed like memory, and the
file pointer holds the &quot;address&quot; of the next byte in the file to be
written to or read from. The NitrOS-9 &quot;read&quot; and &quot;write&quot; service
functions always update the pointer as data transfers are performed.
Therefore, successive read or write operations will perform sequential data transfers.
</para>
<para>
Any part of a file can also be read or written in non-sequential
order by using a function called &quot;seek&quot; to reposition the file
pointer to any byte address in the file. This is used when random
access of the data is desired.
</para>
<para>
To expand a file, you can simply write past the previous end of
the file. Reading up to the last byte of a file will cause the next
&quot;read&quot; request to return an end-of-file status.
</para>

<section id="sec3.9.1">
<title>File Usage in NitrOS-9</title>
<para>
Even though there is physically only one type of file, the logical
usage of files in NitrOS-9 covers a broad spectrum. Because all
NitrOS-9 files have the same physical type, commands such as <command>copy</command>,
<command>del</command>, etc., can be used with any file regardless of its logical
usage. Similarly, a particular file can be treated as having a
different logical usage at different times by different programs. The
main usage of files covered in this section are:
</para>
<simplelist>
<member>TEXT</member>
<member>RANDOM ACCESS DATA</member>
<member>EXECUTABLE PROGRAM MODULES</member>
<member>DIRECTORIES</member>
<member>MISCELLANEOUS</member>
</simplelist>
</section>

<section id="sec3.9.2">
<title>Text Files</title>
<para>
These files contain variable-length sequences (&quot;lines&quot;) of ASCII
characters. Each line is terminated by a carriage return character.
Text files are used for program source code, procedure files,
messages, documentation, etc. The Text Editor operates on this file
format.
</para>
<para>
Text files are usually read sequentially, and are supported by
almost all high-level languages (such as BASIC09 READ and WRITE
statements). Even though is is possible to randomly access data at
any location within a text file, it is rarely done in practice
because each line is variable length and it is hard to locate the
beginning of each line without actually reading the data to locate
carriage return characters.
</para>
<para>
The content of text files may be examined using the <command>list</command>
command.
</para>
</section>

<section id="sec3.9.3">
<title>Random Access Data Files</title>
<para>
Random-access data files are created and used primarily from
within high-level languages such as Basic09, Pascal, C, and Cobol.
In Basic09 and Pascal, &quot;GET&quot;, &quot;PUT&quot;, and &quot;SEEK&quot; functions operate on
random-access files.
</para>
<para>
The file is organized as an ordered sequence of &quot;records&quot;. Each
record has exactly the same length, so given a record's numerical
index, the record's beginning address within the file can be
computed by multiplying the record number by the number of bytes
used for each record. Thus, records can be directly accessed in any
order.
</para>
<para>
In most cases, the high-level language allows each record to be
subdivided into &quot;fields&quot;. Each field generally has a fixed length
and usage for all records within the file. For example, the first
field of a record may be defined as being 25 text characters, the
next field may be two bytes long and used to hold 16-bit binary
numbers, etc.
</para>
<para>
It is important to understand that NitrOS-9 itself does not directly
process or deal with records other than providing the basic file
functions required by all high-level languages to create and use
random-access files.
</para>
</section>

<section id="sec3.9.4">
<title>Executable Program Module Files</title>
<para>
These files are used to hold program modules generated by the
assembler or <emphasis>compiled</emphasis> by high-level languages.
Each file may
contain <emphasis>one or more</emphasis> program modules.
</para>
<para>
NitrOS-9 program modules resident in memory have a standard module
format that, besides the object code, includes a &quot;module header&quot; and
a CRC check value. Program module(s) stored in files contain exact
binary copies of the programs as they will exist in memory, and not
one byte more. NitrOS-9 does not require a &quot;load record&quot;
system commonly used by other operating systems because NitrOS-9
programs are position-independent code and therefore do not have to
be loaded into specific memory addresses.
</para>
<para>
In order for NitrOS-9 to load the program module(s) from a file, the
file itself must have execute permission and each module
must have a valid module header and CRC check value. If a program
module has been altered in any way, either as a file or in memory,
its CRC check value will be incorrect And NitrOS-9 will refuse to load
the module. The <command>verify</command> command can be used to check the correctness
of the check values, and update them to corrected values if
necessary.
</para>
<para>
On Level One systems, if a file has two or more modules, they are
treated as independent entities after loading and reside at different memory regions.
</para>
<para>
Like other files that contain &quot;binary&quot; data, attempts to &quot;list&quot;
program files will result in the display of random characters on the
terminal giving strange effects. The <command>dump</command> command can be used to
safely examine the contents of this kind of file in hexadecimal and
controlled ASCII format.
</para>
</section>

<section id="sec3.9.5">
<title>Directory Files</title>
<para>
Directory files play a key role in the NitrOS-9 file system.  They can only be created by the <command>makdir</command> command, and
can be identified by the &quot;d&quot; attribute being set (see <xref linkend="sec3.8.1"/>). The
file is organized into 32-byte records. Each record can be a
directory entry. The first 29 bytes of the record is a string of
characters which is the file name. The last character of the name
has its sign bit (most significant bit) set. If the record is not
in use the first character position will have the value zero. The
last three bytes of the record is a 24-bit binary number which is
the logical sector number where the file header record (see <xref linkend="sec3.10"/>) is
located.
</para>
<para>
The <command>makdir</command> command initializes all records in a new directory
to be unused entries except for the first two entries. These
entries have the names <filename class="directory">.</filename> and <filename class="directory">..</filename> along with the logical sector
numbers of the directory and its parent directory, respectively (see <xref linkend="sec3.7.3"/>).
</para>
<para>
Directories cannot be copied or listed - the <command>dir</command> command is
used instead. Directories also cannot be deleted directly (see <xref linkend="sec3.5"/>).
</para>
</section>

<section id="sec3.9.6">
<title>Miscellaneous File Usage</title>
<para>
NitrOS-9's basic file functions are so versatile it is possible to
devise an almost unlimited number of special-purpose file formats
for particular applications, which do not fit into any of the three
previously discussed categories.
</para>
<para>
Examples of this category are COBOL Indexed Sequential (ISAM)
files and some special word processor file formats which allow
random access of text lines. As discussed in Sec.
3.9.1, most NitrOS-9 utility commands work with any file format including
these special types. In general, the <command>dump</command> command is the preferred
method for examining the contents of unusually formatted files.
</para>
</section>
</section>

<section id="sec3.10">
<title>Physical File Organization</title>
<para>
NitrOS-9's file system implements a universal logical organization
for all I/O devices that effectively eliminates most hardware-related
considerations for most applications. This section gives
basic information about the physical file structure used by NitrOS-9.
For more information, see the NitrOS-9 System Programmer's Manual.
</para>
<para>
Each NitrOS-9 file is comprised of one or more sectors  which are
the physical storage units of the disk systems. Each sector holds
exactly 256 data bytes, and disk is numbered sequentially starting
with sector zero, track zero. This number is called a &quot;logical
sector number&quot;, or <emphasis>LSN</emphasis>.
The mapping of logical sector numbers to
physical track/sector numbers is done by the disk driver module.
</para>
<para>
Sectors are the smallest allocatable physical unit on a disk
system, however, to increase efficiency on some larger-capacity disk.
systems, NitrOS-9 uses uniform-sized groups of sectors, called
<emphasis>clusters</emphasis>,
as the smallest allocatable unit. Cluster sizes are always an
integral power of two (2, 4, 8, etc.). One sector of each disk is
used as a <emphasis>bitmap</emphasis> (usually LSN 1),
in which each data bit corresponds
to one cluster on the disk. The bits are set and cleared to
indicate which clusters are in use (or defective), and which are
free for allocation to files.
</para>
<para>
The Color Computer disk system uses the following format:
</para>
<itemizedlist mark="square">
<listitem><para>
double density recording on two sides
</para></listitem>
<listitem><para>
40 tracks per disk
</para></listitem>
<listitem><para>
18 sectors per track
</para></listitem>
<listitem><para>
one sector per cluster
</para></listitem>
</itemizedlist>
<para>
Each file has a directory entry (see <xref linkend="sec3.9.5"/>) which includes the
file name and the logical sector number of the file's &quot;file descriptor
sector&quot;, which contains a complete description of the file
including:
</para>
<itemizedlist mark="square">
<listitem><para>
attributes
</para></listitem>
<listitem><para>
owner
</para></listitem>
<listitem><para>
date and time created
</para></listitem>
<listitem><para>
size
</para></listitem>
<listitem><para>
segment list (description of data sector blocks)
</para></listitem>
</itemizedlist>
<para>
Unless the file size is zero, the file will have one or more
sectors/clusters used to store data. The data sectors are grouped
into one or more contiguous blocks called &quot;segments&quot;.
</para>
</section>
</chapter>