@database "FreeMiNT for absolute beginners"
@options "-i -s +zz -t4 -d10"
@author "Draco (draco@atari.org)"
@$VER: mint.stg (9/1/2001)
@subject "Documentation/Manual"

@node "Main" "FreeMiNT for absolute beginners"
@line 1 70 0

@{B}                 FreeMiNT for absolute beginners@{b}

@line 1 70 0

        Preface

        I.    Getting started

              1. Filename and pathname convention
              2. Position of the mint.prg in the 'auto' folder
              3. Name of the FreeMiNT executable in the 'auto' folder
              4. Position of the associated files on the filesystem
              5. Important things to know about nohog.acc

        II.   The configuration

              1. The mint.cnf file

                 1.1 Commands

                     #               include
                     alias           ren
                     cd              set
                     echo            setenv
                     exec            sln

                 1.2. Control variables

                     FDC_HIDE_B=

                     FS_CACHE_SIZE=
                     FS_CACHE_PERCENTAGE=
                     FS_NEWFATFS=
                     FS_UPDATE=
                     FS_VFAT=
                     FS_VFAT_LCASE=
                     FS_WB_ENABLE=
                     FS_WRITE_PROTECT=

                     GEM=

                     GEMDOS_AUX=
                     GEMDOS_CON=
                     GEMDOS_PRN=

                     INIT=

                     KERN_BIOSBUF=
                     KERN_DEBUG_DEVNO=
                     KERN_DEBUG_LEVEL=
                     KERN_MPFLAGS=
                     KERN_SECURITY_LEVEL=
                     KERN_SLICES=

                     PROC_MAXMEM=

                     TPA_FASTLOAD=
                     TPA_INITIALMEM=

                 1.3. mint.cnf example

              2. The mint.ini file

              3. The keyboard.tbl file

              4. The unicode.tbl file

        III.  Understanding the concept of an 'init program'

        IV.   Understanding the concept of multiple filesystems

              1. Path and filename length
              2. Case sensitivity
              3. File ownership and access permissions
                 3.1. Regular file
                 3.2. Symbolic links
                 3.3. Number of links
              4. Wildcard expansion
              5. Filesystem cache

        V.    Understanding the memory protection mechanism

        VI.   Prioritization

        VII.  The problem of the memory fragmentation

        VIII. Supplying time zone information

              1. The TZ environment variable

        IX.   Tuning TOS programs for FreeMiNT

              1. The question of TOS debuggers

        X.    Appendices

              1. Unix user's manual
              2. Graphic shell
              3. Text shell
              4. Using tar & gzip
              5. Special keys
              6. Glossary

        XI.   Gratias

@line 1 70 0

@endnode


@node "Preface"
Preface
@line 1 70 0

If you're reading this, you are probably new to the FreeMiNT world,
so welcome. We hope you will find FreeMiNT useful. However, there
are several things to note, before you actually become a MiNTer.

@{B}FreeMiNT is free software@{b}
It comes with no warranty and no support. Although other MiNT users
and developers will probably do their best to solve all
"unsolveable problems" you can encounter, the first one, who has to
actually use the brain, is YOU. The FreeMiNT is created,
maintained, improved actively by its users for themselves.
You're given software, that has been developed for over 10
years. You don't pay your money, but you must be prepared to pay
with your creativity and intelligence.

@{B}FreeMiNT is an operating system@{b}
After you install the FreeMiNT successfully, you can expect your
computer to change its usual face - you will have to accommodate to
work in a different environment, and, furthermore, you will have to
actually @{B}understand@{b} what and why some things are different,
than under old TOS.

@{B}FreeMiNT is a multitasking operating system@{b}
With FreeMiNT you can use multiple programs running simultaneously.
This is a true, pre-emptive multitasking with adaptive
prioritization. There can be as much as 1000 processes (programs)
running simultaneously.

@{B}FreeMiNT is a multiuser operating system@{b}
With FreeMiNT you can configure your computer, so that you will be
able to share its resources with other people, without a risk of
loosing your valuable data. There is a lot of mechanisms
implemented at the operating system level to protect all the
resources from an unauthorized access.

@{B}FreeMiNT is an Un*x like OS@{b}
With FreeMiNT you're introduced to the great world of Unices, the
most advanced operating systems for all hardware platforms. The
FreeMiNT belongs to the same family as System V, FreeBSD, OpenBSD,
NeXT Step, HP/UX, Ultrix, Solaris, QNX, Linux. There is a number of
sophisticated programming tools, including the latest GNU C
compiler and special libraries, those have been prepared to help
you compiling Un*x programs. A large number of Un*x software has
been already compiled for FreeMiNT and is available in source and
binary form from FTP services.

@{B}FreeMiNT is the tradition@{b}
FreeMiNT is heritage of the Atari Corporation, the next generation
of TOS. It is actually the best they left for us.

This manual has been prepared to help you setting the FreeMiNT up.
However, it does not cover the detailed information on how to do
specific things, it is rather intended to lead you to understand
things, why they can happen, and to read other docs with more
understanding. There is a number of dedicated documentation files,
manuals, WWW pages on the Internet. There are also helpful people
on the USENET. The full system distribution takes several megabytes
on your hard disk, and you will be surprised to discover, how much
of this space is actually taken by documentation and various source
code.

As a last resort, you can always ask questions on the MiNT mailing
list @{B}mint@@fishpool.com@{b}. But before you do that, please read
all the supplied documentation carefully. This helps to make the
FreeMiNT list traffic reasonable. Also, asking your questions, try
to be specific as much as possible - generic cries like "It does
not work. What should I do?" are usually not answered, simply
because there is no specific answer to a generic question.


FreeMiNT is copyrighted by Atari Corporation. See the file COPYING
for terms and conditions.

All other trademarks and registered trademarks belong to their
respective owners.

@line 1 70 0

@endnode


@node "Getting started"
@next "The mint.cnf file"
Getting started
@line 1 70 0

This section is @{B}not@{b} a detailed instruction on how to
configure and setup a FreeMiNT system. Since the FreeMiNT is highly
customizable, we cannot provide a detailed setup information
without an assumption that you'd want to see the system to behave
in a certain manner - and this may be conflicting with your
requirements. So this section only provides a minimum information
on some more obscure things, which (the information) may help you
refining the system to behave as desired.

Filename and pathname convention

Position of the mint.prg in the 'auto' folder

Name of the FreeMiNT executable in the 'auto' folder

Position of the associated files on the filesystem

Important things to know about nohog.acc

@line 1 70 0

@endnode


@node "Filename and pathname convention"
@toc "Getting started"
Filename and pathname convention
@line 1 70 0

The writing convention for file an path names (also including drive
letters) in TOS was, that all these were written always in
UPPERCASE. For some reason, which will be discussed later, this
manner is no longer valid. In FreeMiNT all filenames should be
lowercase by default, although mixed casing is of course allowed,
when necessary. Basically you must remember that in FreeMiNT,
unlike in TOS, the letter casing you use to reference files and
folders, @{B}does@{b} matter.

Respecting that, we won't use pathnames like C:\MINT\MINT.CNF
preferring the form c:\mint\mint.cnf instead. This is different
from what the TOS (and even MultiTOS) documentation says,
eventhough it is called @{B}compatibility convention@{b} of storing
file- and pathnames. Such a form of a pathname is accepted by all
TOS derivatives, hence the name.

Apart from that there are yet some more, equally valid conventions.
One of them is similar to the convention discussed above, all the
difference is that files are dereferenced by pathnames relative to
the drive u:. So the above example may be also expressed as
u:\c\mint\mint.cnf. This is accepted by all MiNT derivatives,
including (for instance) MagiC.

The FreeMiNT, being an Un*x like OS, also accepts the slash
character ('/') as a separator in pathnames - where TOS only
accepted the backslash ('\'). The slash separator is automatically
forwarded by the FreeMiNT core to the actual filesystem drivers and
is considered identical to the backslash. The above example may be
expressed either as c:/mint/mint.cnf or u:/c/mint/mint.cnf.
This is (so far) only understood by FreeMiNT.

Finally, the so called Un*x convention is in use, which looks
similar to the one discussed above, with notable except it does not
use drive letters. Our example looks then like this:
/c/mint/mint.cnf. In this case the u: drive is automatically
assumed as the top directory referenced. However, and this is the
most important difference between this convention and those three
discussed above, this 'assumption' is made not by the FreeMiNT
kernel itself, but by the so called MiNT Library, which is linked
with almost all FreeMiNT specific programs. The library has (apart
from anything else) to convert such pathnames to the form directly
understood by the kernel. This task has been moved to the library,
and is not performed by the kernel itself, to reduce the total
system call overhead, which would be always imposed by the
conversion, even if no conversion is necessary at all in a
particular case.

In configuration files for system components like the AES or the
kernel itself, you should use the second convention (i.e. the
'u:\c\mint\mint.cnf' thing). The Un*x convention
('/c/mint/mint.cnf') should be only used with software ported
from Unices.

@line 1 70 0

@endnode


@node "Position of the mint.prg in the 'auto' folder"
@toc "Getting started"
mint.prg in the AUTO folder
@line 1 70 0

Unlike, for instance, the Linux/68k, the FreeMiNT does not need a
separate loader to be started. Or, strictly speaking, it does, but
this loader was shipped with each Atari computer. It is the TOS,
that is used to load and initialize the FreeMiNT kernel.

Since the FreeMiNT is usually booted from the auto folder sequence,
the auto folder sorting and physical order of its contents
@{B}does@{b} matter and @{B}has@{b} an influence on the FreeMiNT
operation.

The golden rule is: the FreeMiNT executable should be
@{B}definitely last@{b} program executed from the auto sequence. It
is so for the following reasons:

- auto folder programs are usually TOS extensions, so they will
  still work, if MiNT passes application calls down to the
  underlying system (TOS). At the other hand, if they're loaded
  after MiNT, they usually do not pass the call further down, so
  MiNT functions aren't extended - they simply aren't called at
  all, and don't work. And it is usually not worth to bypass MiNT
  code completely, because MiNT code is more advanced and
  sophisticated than most popular auto folder programs.

- MiNT provides several mechanisms to protect the environment from
  various forms of misuse, including network security. Hence, if
  the MiNT kernel is loaded as last program from the auto, we can
  be sure it has an ultimate control on the system resources.

- although MiNT will execute auto folder programs located after it,
  this way of loading system extensions is generally deprecated.
  The TOS extensions loaded from the auto should be replaced by
  MiNT compatible XDD device drivers and XFS filesystem drivers.
  When absolutely necessary to load a TSR after MiNT, you should
  use suitable commands provided by mint.cnf, gem.cnf or n_aes.cnf
  configuration scripts.

Another golden rule is to reduce the quantity of TSR programs
(whether they're started from the auto or not) to an absolute
minimum. There is a number of auto folder TOS programs, which do
not work anymore under MiNT or their usage is deprecated. A good
example is BigDOS (any version). It is a good replacement for
GEMDOS, but the TOS' one. The MiNT GEMDOS is much more
sophisticated, than these two taken together.

Also, there is a number of auto folder programs, those seem to work
under MiNT, but make the system unstable. A good (or rather a bad)
example is CKBD.PRG, which causes random system freezes. Such
programs definitely shouldn't be used with MiNT, because they are
either badly programmed or use programming techniques which are not
valid in a multitasking environment anymore.

Finally, there is software like HSMODEM, where the documentation
explicitly says it should be loaded after MiNT. In this case you
should verify such a statement on the MiNT mailing list
(mint@@fishpool.com). In the particular case of the HSMODEM, you
should load the software @{B}before@{b} MiNT (regardless of what
the HSMODEM documentation says), if you want the MiNT Network
package to work correctly. Or better use dedicated MiNT serial 
drivers instead of HSMODEM, which is now a bit outdated.

@line 1 70 0

@endnode


@node "Name of the FreeMiNT executable in the 'auto' folder"
@toc "Getting started"
Name of the MiNT binary
@line 1 70 0

The name of the FreeMiNT executable people have in the auto is
usually either mint.prg or mintnp.prg. Now surprise: this filename
does not matter, you can change it to banana.prg and it still will
work!

With one notable exception: you @{B}must@{b} rename the executable
to mintnp.prg or mntnp.prg (both forms are valid), if you want to
switch off the hardware memory protection mechanism (this changed
as of FreeMiNT 1.16.0, see the section The mint.ini file
somewhere within this document).

See the chapter
Understanding the memory protection mechanism for further details.

You may want to do so, if you're heavily using TOS software, that
is not compatible with the memory protected mode. However, we
recommend to do a little effort to find a replacement, if possible.

@line 1 70 0

@endnode


@node "Position of the associated files on the filesystem"
@toc "Getting started"
Associated files
@line 1 70 0

After the FreeMiNT is loaded, it performs a search for its
configuration file (mint.cnf) and other modules like extended
filesystem drivers (XFS) or extended device drivers (XDD).

All these system files have to be located in the subdirectory
/mint/ located on the boot drive (e.g. c:/mint/). This is the only 
place where the FreeMiNT 1.16 will search for its configuration files 
and modules.

You may remember as a practical rule, that the kernel loads all its
modules and configuration files from the same directory, where it has
found the mint.cnf file.

Optionally, you can put configuration files and modules also to the 
subdirectory, that is named after the FreeMiNT kernel version number. 
For example, the kernel version 1.16.0 accepts /mint/1-16-0/ as a 
folder, where you can store the appropriate files and modules. This 
allows to keep configuration files and modules for different kernel 
versions on the disk separately without a risk to mix them up.

Also, unlike it is with the auto folder stuff, the execution
sequence of the XDD and XFS modules does not matter - they can be
physically sorted in any order.

@line 1 70 0

@endnode


@node "Important things to know about nohog.acc"
@toc "Getting started"
nohog.acc
@line 1 70 0

The nohog accessory program, which you can find on some FTP sites,
get it along with older FreeMiNT distributions etc., is considered
a thing that fixes some problems with GEM while using it (the GEM)
with MiNT. Thus some people put the nohog.acc into their accessory
folder in order to use it as advertised.

                        @{B}THIS IS WRONG!@{0}

The nohog.acc is a very old program, that had been developed before
the first version of multitasking GEM has appeared. Thus, the "GEM"
the nohog.acc documentation is talking about, is the TOS' GEM in
ROM, which generally hasn't been written with multitasking in mind.
Since there are several versions of multitasking GEM available,
thus nobody (being normal) uses the old single-GEM under MiNT, and
that makes the nohog.acc useless.

Moreover, if the nohog.acc is used in conjunction with a
multitasking GEM, it may make the entire system extremely unstable.
So if you happen to load nohog.acc under Atari AES 4.x (the
MultiTOS' GEM distributed along with MultiTOS 1.04 and 1.08
respectively), or under N.AES, or under oAESis, please stop doing
it immediately and delete the nohog.acc file from your disk. This
will greatly improve the system's stability.

@line 1 70 0

@endnode


@node "The mint.cnf file"
@next "Understanding the concept of an 'init program'"
@prev "Getting started"
mint.cnf
@line 1 70 0

The mint.cnf file is one of corner stones for your FreeMiNT setup,
because it allows to set many important things up inside the
FreeMiNT kernel itself. Although it is usually possible - using
dedicated software - to change many settings later, on a "live"
system, the FreeMiNT configuration file defines a number of
defaults to make the system up and running at all. So, if you're
about to tune your setup, it is highly likely you'll have to edit
your mint.cnf file as one of the first steps.

@{B}NOTICE:
@{B}Older versions of MiNT had a limitation, that disallowed to use TAB
@{B}as a horizontal separator in the mint.cnf file. In the latest
@{B}versions of MiNT this limitation is gone, however, you're still
@{B}encouraged to use blank space as a separator for consistency.
@{b}

also

@{B}NOTICE:
@{B}Older versions of MiNT used different mint.cnf keywords. We
@{B}provide old names inside parentheses here. The old keywords
@{B}are still supported, however, we encourage you to switch now
@{B}because the old format will go away some day.
@{b}

The mint.cnf commands:

                     #               include
                     alias           ren
                     cd              set
                     echo            setenv
                     exec            sln

The mint.cnf control variables

                     FDC_HIDE_B=

                     FS_CACHE_SIZE=
                     FS_CACHE_PERCENTAGE=
                     FS_NEWFATFS=
                     FS_UPDATE=
                     FS_VFAT=
                     FS_VFAT_LCASE
                     FS_WB_ENABLE=
                     FS_WRITE_PROTECT=

                     GEM=

                     GEMDOS_AUX=
                     GEMDOS_CON=
                     GEMDOS_PRN=

                     INIT=

                     KERN_BIOSBUF=
                     KERN_DEBUG_DEVNO=
                     KERN_DEBUG_LEVEL=
                     KERN_MPFLAGS=
                     KERN_SECURITY_LEVEL=
                     KERN_SLICES=

                     PROC_MAXMEM=

                     TPA_FASTLOAD=
                     TPA_INITIALMEM=

Here is a mint.cnf example. You find the same file in the directory 
freemint/doc/examples/ in the FreeMiNT source distribution.

@line 1 70 0

@endnode


@pnode "#"

This is a comment. Everything in a text line,
that is after a hash character, is ignored
while doing interpretation mint.cnf commands.

@endnode


@pnode "echo"

The "echo" command prints its argument on the
screen. Example:

echo Starting system...

@endnode


@pnode "cd"

The "cd" command is used to change the directory
the FreeMiNT is considering current one. It is
usually best to use this command in the follo-
wing form:

cd u:\

just before starting the init program.

FreeMiNT 1.16.0 does this automatically.

@endnode


@pnode "exec"

This command can execute programs while the
mint.cnf file is being interpreted. Since, while
it is being done, the filesystem drivers have been
already loaded, the binary file to be executed
can be located on any valid filesystem (disk). The
only real restriction is that it cannot be a GEM
application, because while the mint.cnf file is
being interpreted, the GEM isn't yet active.

@endnode


@pnode "alias"

This command can create fake drives, which in fact
are folders on real ones:

alias r: u:/c/some/long/path

Be sure you do not create nested aliases!

@endnode


@pnode "include"

With this one another text file can be included
as a portion of the mint.cnf script:

include u:/c/mint/config.cnf

@endnode


@node "ren"
@prev "The mint.cnf file"
@toc "The mint.cnf file"
ren
@line 1 70 0

ren

This is a "rename" command. Use this, if you need to change the
default name a device is getting during a bootup:

ren u:/dev/modem2 u:/dev/ttyS1

The command isn't rather useful for use with regular ("real") files
stored on the disk. Also, be sure you know what you're doing while
using this, because if you misuse the command, software can have
problems finding system devices.

@line 1 70 0

@endnode


@node "sln"
@toc "The mint.cnf file"
sln
@line 1 70 0

This command creates so called symbolic links (also referenced as
symlinks) on the unified filesystem (u:/) and the device
filesystem (u:/dev). The syntax is:

sln u:/path/filename u:/path/linkname

Other internal filesystems, i.e. the process filesystem (u:/proc),
the shared memory filesystem (u:/shm) and pipe filesystem (u:/pipe)
do not allow to create symlinks on themselves.

Provided a disk filesystem does support symbolic links, you can
also create them with this command on regular partitions on your
hard drive, but in fact it is not a good idea, since the creation
will be attempted on each bootup. To create symlinks on the hard
drive you should use the GEM Desktop or shell commands.

@line 1 70 0

@endnode


@node "setenv"
@next "KERN_SECURITY_LEVEL="
@toc "The mint.cnf file"
setenv
@line 1 70 0

Unlike in TOS, the FreeMiNT software makes a heavy use of so called
@{B}environment variables@{b}. In fact, TOS is perhaps the one and
only operating system, where the environment variables have never
been used, though (and it may be a small suprise for some of its
users) the support for them has @{B}always@{b} existed, since (and
including) the earliest version possible to think of.

An environment variable is basically a human-readable string
"memorized" by the system under a name. These strings can be
retrieved and used by software to interrogate the system on certain
user-defined defaults, which have been set by the user.

The most important difference between environment variables and
other user-defineable settings is, that these former ones are
stored in the computer's memory exactly in the text form they have
been defined, while other settings are usually converted to a form
of binary data. A typical environment variable looks like this:

@{B}HOSTNAME=saturn@{b}

or

@{B}PATH=u:/c/mint;u:/d/programs@{b}

The environment variables usually control application software
(including shells), but do not control the system itself, which
actually maintains them only. Also, each user program (application)
usually receives a private copy of all the environment variables
known to the shell, so that any modifications done are local and do
not have an influence on other programs, unless they have been
explicitly started by the process that made the modification (we
say "unless they're its children"). Of course, since all programs
are started by a shell, a modification done by the shell influences
all programs - but only if they have been launched @{B}after@{b}
the modification has been made.

There are two "common" commands you can define an environment
variable, so if one fails, you can always try the other one:

@{B}setenv@{b}
This one is supported by the FreeMiNT kernel while executing the
mint.cnf file, by the Atari AES 4.10 (MultiTOS) while parsing the
gem.cnf file and by any text shell derived from the so called "C
shell" (csh). The syntax that assigns a 'value' to a variable named
'NAME' is: @{B}setenv NAME value@{b}

The other command used by N.AES in n_aes.cnf files and by any text
shell derived from the so called "Bourne shell" (of which the most
common one is bash) is @{B}export@{b}. To define a variable 'NAME'
with a value of 'value', you do the following:
@{B}export NAME=value@{b}

Neither one is 'better' or 'worse', exactly like neither type of
the shell mentioned above is really superior over the other, though
of course there always are some user preferences and habits.

See also:

Environment variables set by the kernel

@line 1 70 0

@endnode


@pnode "KERN_DEBUG_DEVNO="

determines the device for printing
the FreeMiNT kernel's debug messages.

default is 2 (/dev/console), maximum
is 9.

@endnode


@pnode "KERN_DEBUG_LEVEL="

controls verbosity of the FreeMiNT
kernel debug messages.

default is 1, maximum is 4.

Notice the distribution kernels
support only basic debug information.
Detailed reports are only generated
by special debug kernels.

@endnode


@node "KERN_SECURITY_LEVEL="
@prev "setenv"
@toc "The mint.cnf file"

@line 1 70 0

@{B}KERN_SECURIY_LEVEL=x@{0}
This keyword enables some additional security features implemented
at the kernel level of the operating system. The 'x' ranges from 0
to 2.

With 'KERN_SECURITY_LEVEL=1' the system blocks most of the BIOS/XBIOS
functions, which are critical for system's security, so that these
functions can be accessed only by software, that runs with
superuser privileges (so called 'root privileges'). If you have a
multiuser setup and allow people to access your computer via
network, so that they are actually able to login and run programs,
you should set the 'KERN_SECURITY_LEVEL=1' in your mint.cnf file, 
because otherwise nothing (perhaps except a loyalty or lack of 
knowledge) prevents them from reformatting your hard drive. The only 
person, who should be able to do that - and it is really the case 
after raising the security level to 1 - is you, i.e. the superuser.

With 'KERN_SECURITY_LEVEL=2' this protection is even more strict - so
strict that it can be actually inacceptable not only for TOS
programs, but also for Un*x programs those have been linked with
old versions of the MiNT Library (up to, and including, PL 47).
Hence do not enable this unless you're deadly sure your software is
compatible, because otherwise your users won't be able to use your
machine remotely. Obviously, the KGMD distribution (anno Domini
1995) is not compatible with the KERN_SECURITY_LEVEL=2.

With 'KERN_SECURITY_LEVEL=0' all these limitations are disabled.

@line 1 70 0

@endnode


@node "TPA_FASTLOAD="
@alias "FDC_HIDE_B="
@alias "FS_NEWFATFS="
@alias "FS_VFAT="
@alias "FS_VFAT_LCASE="
@alias "FS_WRITE_PROTECT="
@toc "The mint.cnf file"

@line 1 70 0

@{B}TPA_FASTLOAD=no@{b} or
@{B}TPA_FASTLOAD=yes@{b}
With 'TPA_FASTLOAD=yes' the real state of the 'fastload' bit in the
program header is ignored and all programs are loaded like it was
always set. With 'TPA_FASTLOAD=no' this bit is interpreted the same 
way as under TOS. The default is 'no'.

@{B}FDC_HIDE_B=no@{b} or
@{B}FDC_HIDE_B=yes@{b}
This 'hides' (removes from the list of valid system drives) the
floppy disk B:. Of course, this is only useful on systems, where
the floppy B: is not present physically. The default is 'no'.

@{B}FS_NEWFATFS=drive,drive,drive,...@{b}
Specifies the list of drives (hard disk partitions and floppies)
where the internal FAT filesystem should be used (otherwise the old
TOS filesystem is used). If the TOS FS is not present in the system
- i.e. it was not selected at the FreeMiNT kernel compile time -
this command has no effect, since the filesystem it wishes to
enable is enabled anyways. If there is no FAT filesystem structure
on a specifies partition, this command has no effect for this
parition either. The default is none, if the TOS FS is present, or
all otherwise.

@{B}FS_VFAT=drive,drive,drive,...@{b}
Specifies a list of FAT filesystem drives, where the Windows 95
VFAT extension should be enabled. This only works with the
NEWFAT filesystem (see above). The default is none.

@{B}FS_VFAT_LCASE=no@{b} or
@{B}FS_VFAT_LCASE=yes@{b}
This one forces the FAT filenames returned in lower case from
directory searches (like it is in the VFAT). The default is 'no'.

@{B}FS_WRITE_PROTECT=drive,drive,drive,...@{b}
Specifies a list of drives to enable the software write protection.
The defaultis none.

@line 1 70 0

@endnode


@node "FS_CACHE_SIZE="
@alias "FS_CACHE_PERCENTAGE="
@alias "FS_UPDATE="
@alias "FS_WB_ENABLE="
@toc "The mint.cnf file"

@line 1 70 0

@{B}FS_CACHE_SIZE=x@{b}
Specifies the amount of kilobytes, that will be allocated for
bufferring (caching) all disk operations. This significantly speeds
all the disk operations up, especially massive renaming, deleting
or moving directory entries. Since the filesystem cache is designed
especially to handle the FreeMiNT disk operations, you do not
need to use any external caching programs anymore. The default
value is 120.

@{B}FS_CACHE_PERCENTAGE=x@{b}
Defines the percentage of the aforementioned disk cache to be
filled with linear reads. Default is 5 (percent), which means, that
if you set the cache size to 1 MB, any read operation fetches a 50k
of non-cached data from the physical media.

@{B}FS_UPDATE=x@{b}
Specifies the amount of time (in seconds), after which the write
back cache units are written to the disk's magnetic media. The
default is 5 sec.

@{B}FS_WB_ENABLE=drive,drive,drive,...@{b}
Specifies the filesystems (partitions and floppies) where the
write-back cache has to be active. The default is none. The
write-back cache buffers all write operations in the memory, then
its contents is flushed to the disk on certain time intervals (see
UPDATE). This speeds the disk operations significantly up, but if
the system goes down before all cache units have been written out -
e.g. because of a power failure or crash - a data loss occurs. This
is also the reason to close the system by explicitly disposing a
shutdown command, because executing a shutdown sequence forces all
cache units to be written out immediately.

@{B}NOTICE:
@{B}The filesystem cache works only with 'true' FreeMiNT filesystems,
@{B}i.e. Minix FS, ext2 FS, FAT FS - and does NOT influence the old
@{B}TOSFS.
@{b}

@line 1 70 0

@endnode


@node "INIT="
@alias "GEM="
@toc "The mint.cnf file"

@line 1 70 0

@{B}INIT=file
@{B}GEM=file@{0}
This specifies the command you want the FreeMiNT to run at boot up
time. The 'file' should be a full path name.

Both INIT= and GEM= specify an initial program to run, but the way
the program is launched is different depending on whether you say
'GEM=' or 'INIT='. With the former ('GEM='), the application is
launched via the exec_os vector (see the Hitchiker's Guide to the
Bios). With the latter form, the application is launched directly
via Pexec(). Only one 'GEM=' or 'INIT=' line is permitted in the
configuration file.

When there is no INIT= nor GEM= command specified, the kernel
tries to execute a program called `sh' (or `sh.tos' on FAT file-
system) located in the same directory, as the mint.cnf file is.
When this is not available, the internal minimum shell will be
executed. If this fails as well - the shell is optional, so it
can be omitted while compiling the kernel - the system will halt.

In such a situation old MINT kernels executed the GEM in ROM.
This possibility has been retained: if you want to execute
the ROM AES, you have to put

GEM=ROM

in your mint.cnf file. However, remember, that you do it at your
own risk: ROM AES cannot be shutdown, and forces to switch the power 
off without flushing the filesystem caches, thus endangering the 
consistency of the data on your harddisk.

@line 1 70 0

@endnode


@node "PROC_MAXMEM="
@alias "TPA_INITIALMEM="
@toc "The mint.cnf file"

@line 1 70 0

@{B}TPA_INITIALMEM=x@{b}
This specifies the maximum amount of memory allocated for program's
TPA (i.e. this is everything over the size of the binary plus the
size of the BSS segment).

Unlike the PROC_MAXMEM, the TPA_INITIALMEM does not limit the amount 
of memory available for processes by explicit allocation. The 'x' is 
measured in kilobytes.

@{B}PROC_MAXMEM=x@{b}
Specifies the maximum amount of memory that may be used by a
process. The 'x' is measured in kilobytes.

WARNING: many users tend to understand this option wrong. They set 
PROC_MAXMEM=1024, and then complain that the system does not "see" 
more than 1 MB of the memory. The system obviously does, just the 
program the user uses to interrogate the total amount of memory 
doesn't, because such a program is a process, and is limited by this 
keyword to 1 MB.

Generally, don't use PROC_MAXMEM, unless you deadly know what you 
want or what you're doing. If you want to limit the initial TPA size, 
use TPA_INITIALMEM keyword.

@line 1 70 0

@endnode


@node "GEMDOS_AUX="
@alias "GEMDOS_CON="
@alias "GEMDOS_PRN="
@toc "The mint.cnf file"

@line 1 70 0

@{B}GEMDOS_AUX=file@{b}
@{B}GEMDOS_CON=file@{b}
@{B}GEMDOS_PRN=file@{b}
This specifies the file or device you want MiNT to use by default
for all output on the serial port, console and printer,
respectively (including debugging output generated by a special,
debug version of the FreeMiNT kernel). It should be a full
pathname, and is usually a device in u:/dev. For instance, the
obvious choice for console is u:/dev/console (the default). The
default for the printer is u:/dev/centr, which is the device
corresponding to the Centronics port.

@line 1 70 0

@endnode


@node "KERN_BIOSBUF="
@toc "The mint.cnf file"

@line 1 70 0

@{B}KERN_BIOSBUF=no@{b} or
@{B}KERN_BIOSBUF=yes@{b}
If 'KERN_BIOSBUF=yes' appears in your configuration file, then certain
optimizations in the FreeMiNT kernel concerning BIOS input and
output are used. These optimizations should normally be transparent
to user programs - and they usually are, but can be turned off with
'KERN_BIOSBUF=no', when needed. Especially 'KERN_BIOSBUF=no' may help 
GFA BASIC programs to run, but the best solution is to avoid using
GFA BASIC programs at all (unless you're deadly sure the program is
cleanly written and compiled with a patched version of the GFA
compiler). The default is 'yes' (optimizations on).

@line 1 70 0

@endnode


@node "KERN_SLICES="
@toc "The mint.cnf file"

@line 1 70 0

@{B}KERN_SLICES=x@{0}
Controls the number of 20ms time slices to give to processes before
they will be preempted. The default (2) is usually the best value;
a higher value (e.g. 3) will cause CPU intensive tasks to receive
more time, while a lower one (e.g. 1) will favour interactive tasks
slightly. Generally, the lower the value, your processes have
faster response time, but the general performance is worse.

A zero (0) is a forbidden value. If you set KERN_SLICES=0, the system
will silently change this to 1.

@line 1 70 0

@endnode


@node "mint.cnf example"
@toc "The mint.cnf file"

@line 1 70 0

# MiNT configuration file.
#
# The mint.cnf file is loaded, when the entire system is practically
# up, all device drivers and filesystem drivers have been loaded etc.
# If you want to control earlier settings, see mint.ini file.
#

# Edit this with a normal ASCII text editor. Lines starting with '#'
# are comments. Other lines are commands for MiNT to execute at boot
# up, or variables that control how MiNT behaves.

# For best results, the convention u:/drive/pathname should be used
# for all specified pathnames.

#
# Here are things you can change if you want to. There are
# reasonable defaults for all of these.
#

# Set current working directory to u: respective /
#
# FreeMiNT 1.16 does this automatically, this line is only required
# on previous versions (also on 1.16 alphas compiled before second
# half of July 2004).

cd u:/

# The "set" directive controls the behaviour of the mint.cnf parser.
# It accepts one of three parameters:
#
#set -q - silent output (+q for verbose output)
#set -v - print command lines (+v don't)
#set -c - control interpretation of escape sequences

# KERN_SLICES controls how long a process may run before being
# interrupted.
#
# The default value (2) is usually best, but if you tend to run
# very processor intensive applications in the foreground, you might
# want to put SLICES=3 (this makes CPU hogs get more time than they
# otherwise would).
#
# The smaller the SLICES value, your processes have faster response
# time but the general performance is worse.

KERN_SLICES=2

# KERN_DEBUG_LEVEL controls output of global debugging information.
# The higher the level, the more stuff MiNT will spew about about
# what it's doing.
#
# The average user doesn't want to hear about this stuff, so the
# default is 1, i.e. display ALERT messages only.
#
# KERN_DEBUG_DEVNO is the BIOS device number to which the info should 
# be sent.
#
# Devno can be: 0=printer, 1=aux/modem, 2=screen(console), 3=midi,
# 4=keybrd, 5=raw.
#
# The default is the console.

#KERN_DEBUG_LEVEL=1
#KERN_DEBUG_DEVNO=3

# KERN_BIOSBUF controls how BIOS I/O is performed. Normally, MiNT
# tries to buffer this to provide a (considerable) improvement in
# speed. However, some applications may get upset by this.
#
# BIOSBUF=no turns off all buffering for maximum compatibility. The
# default is YES.

#KERN_BIOSBUF=NO

# KERN_SECURITY_LEVEL= enables the appropriate security level:
#
# 0 - recommended for single user setups, like MultiTOS (default).
# 1 - recommended for multiuser setups, like KGMD.
# 2 - full protection, unsupported by software, thus discouraged.

KERN_SECURITY_LEVEL=1

# KERN_MPFLAGS controls the memory protection behaviour. Its argument
# is a bitfield. Only the bit 0 is defined: 1 means, that more strict
# model of the protection should be enabled. Some programs may
# refuse to run, so the default is 0.

#KERN_MPFLAGS=1

# TPA_FASTLOAD=YES forces fast loading (without zeroing all the
# memory) for all programs. This defines a default state, that can be 
# modified later via appropriate kernel calls (use MiNT Setter
# utility to toggle it later when neessary, without reboots).
#
# TPA_FASTLOAD=NO (default) means that the information from the
# program header will be used to decide (this is like TOS does).

#TPA_FASTLOAD=YES

# Set maximum additional TPA size for new processes
# (in kilobytes). The default is 1024.

#TPA_INITIALMEM=1024

# FS_NEWFATFS= enables the new FAT filesystem driver for selected FAT
# filesystems. The old TOS FS will be used otherwise.
#
# The default depends on whether the TOSFS driver is compiled into the
# kernel or not. If it is, all drives are TOSFS by default. If not,
# all drives are NEWFATFS by default and this keyword has no effect.

#FS_NEWFATFS=A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,V,W,X,Y,Z

# FS_VFAT= enables VFAT extension for selected drives specified in the
# NEWFATFS= command. The VFAT extension is disabled by default.

#FS_VFAT=A,J

# FS_VFAT_LCASE=YES tells the kernel to return lowercase filenames
# from VFAT directory searches. The default is NO.

#FS_VFAT_LCASE=YES

# FS_WB_ENABLE= enables write back cache for selected drives. The
# write back cache is disabled by default. Also, it does not have
# any effect for TOSFS drives.

#FS_WB_ENABLE=C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,V,W,X,Y,Z

# FS_CACHE_SIZE= specifies the size of disk cache in kilobytes for the
# internal caching module. Default is 128.

#FS_CACHE_SIZE=500

# FS_CACHE_PERCENTAGE specifies the size of the disk cache (in
# percents) to be filled with linear reads. The default is 5.

#FS_CACHE_PERCENTAGE=10

# FS_UPDATE= set update time for system update daemon in seconds
# default is 5, it isn't recommended to use a value less than 4.

#FS_UPDATE=10

# Software write protection on filesystem level.

#FS_WRITE_PROTECT=R,S

# FDC_HIDE_B= tells the MiNT to remove floppy drive B: from the
# system.
# It is useful on single floppy systems to get rid of "Insert
# disk B: into drive A:" messages from the AES. Default is NO.

#FDC_HIDE_B=YES

# PROC_MAXMEM= gives the maximum amount of memory that any process
# may use (in kilobytes). The default is to make this unlimited, but 
# if you have a lot of memory and/or programs that grab more memory
# than they should, try setting this.
#
# E.g. to limit processes to 4096K of memory, remove the '#' at the
# beginning of the next line.
#
# WARNING: the process will not be allowed to allocate memory beyond 
# the limit, and it won't "see" more memory as available from the
# system.
# Please understand that programs like "free" (or any other that
# interrogates the system how much memory is available) is a process 
# as well, thus it will undergo this limit too!
#
# Decent shells (desktops) allow you to limit the maximum amount of
# memory independently for each program.

#PROC_MAXMEM=4096

# Three commands, that define output files for RS-232, console and
# printer devices. The argument for each one must be a pathname.

#GEMDOS_AUX=u:/c/mint/aux.out
#GEMDOS_CON=u:/c/mint/con.out
#GEMDOS_PRN=u:/c/mint/prn.out

# End of kernel settings
#
# ---------------------- ************** ------------------------------
#
# Here are some commands that you can give to MiNT:
#
# alias d: path -- make a fake "drive" that actually points to the
#                  given path
# cd path       -- changes MiNT's default directory
# echo message  -- print something on the screen
# exec program  -- runs a program; you must give the complete path
#                  and file extensions (e.g. c:/bin/echo.prg)
# include file  -- include another portion of the MINT.CNF file.
# sln path link -- make a symbolic link named "link" pointing to
#                  "path". "link" must be on drive U: for this to work

# Examples follow
#
# Notice you have to adjust commands below for your filesystem
# structure.
#
# You could use "alias" to provide a quick way of getting at
# nested directories, e.g. if you do
#
# alias r: u:/c/some/long/path
#
# then clicking on drive r: puts you into the folder c:/some/long/path

# The "sln" command may be used to create "links" on drive U:. If
# u:/foo is a link to c:/bar, then u:/foo/foo.txt is another way
# of saying c:/bar/foo.txt. Judicious use of links can make
# re-arranging hard disks and directories painless (if you always
# use the names on drive u:, it doesn't matter where you put
# the actual directories).

# Setting up the root filesystem for UNIX environment

#sln g:/bin      u:/bin
#sln g:/boot     u:/boot
#sln g:/etc      u:/etc
#sln g:/home     u:/home
#sln g:/lib      u:/lib
#sln g:/mnt      u:/mnt
#sln g:/opt      u:/opt
#sln g:/root     u:/root
#sln g:/sbin     u:/sbin
#sln g:/tmp      u:/tmp
#sln g:/usr      u:/usr
#sln g:/var      u:/var

# PCONVERT and UNIXMODE variables control some internals of
# MiNT Library.
#
# FreeMiNT 1.16.0 sets these two below automatically.

setenv PCONVERT PATH,HOME,SHELL
setenv UNIXMODE /brUs

# Default path
#
# Default (on 1.16.0) is u:/

setenv PATH /boot/mint/bin;/sbin;/bin;/usr/sbin;/usr/bin

# Default path to search the SLBs (MagiC style 'shared
# libraries'). Default (on 1.16.0) is /c/mint

setenv SLBPATH ./;/c/mint

# Checking filesystem if necessary
# Note: you need a correct /etc/fstab

#exec u:/c/mint/bin/sh u:/c/mint/bin/fscheck.sh
#echo

# Alternative method, if you have e2fsck.ttp in /c/mint,
# and e: is your ext2fs drive.

#exec /c/mint/e2fsck.ttp -C 0 -p e:

# Set up time stuff. Note that you need MiNT Lib timezone package
# (installed along with the library) for this below to work.
#
# Such settings are valid if your clock ticks in UTC. For local
# time you have to add -l to the tzinit.

#setenv TZ 'Europe/London'
#exec u:/usr/sbin/tzinit
#exec u:/usr/sbin/tzinit -l

# The "exec" command is used to launch programs. Note that programs
# so launched are started before GEM is, so they must be TOS/TTP
# programs. Most commonly used for starting device drivers.

# Start Draconis to MiNT-Net gateway

#exec u:/boot/mint/mgw.prg
#echo

# Start Gluestik

#exec u:/boot/mint/gluestik.prg
#echo

# Default login variables. Leave them commented out, if you use
# UNIX style login. If you're using plain MultiTOS and want to
# run UNIX shells under TOSWIN, please uncomment it.

#setenv LOGNAME root
#setenv USER    root
#setenv HOME    /root
#setenv SHELL   /bin/bash

# These lines (with proper pathnames) are obligatory, if you're
# going to use N.AES and Thing Desktop, respectively.

#setenv AESDIR   u:/boot/mint/aes/
#setenv THINGDIR u:/boot/mint/aes/desktop

# The best option is to have INIT= command here, after all pathnames
# are already set up by commands above.

# If the MiNT is supposed to execute GEM, you should specify the full
# path and filename like that:

#GEM=u:/boot/mint/aes/xaaes.prg

# You can also request MiNT to execute the TOS AES residing in ROM.
# WARNING: this is not recommended, you should use a GEM version
# instead, that is multitasking friendly.

#GEM=ROM

# Otherwise, if your init program is not GEM, you should use INIT= as
# follows:

INIT=u:/boot/mint/init.prg

# If you leave both commands above commented out, the MiNT will
# attempt to execute a file called `sh.tos' found in the system
# directory (the same where the mint.cnf resides), and if this
# fails, the internal minimum shell will be executed.

# Before the MiNT executes the rest of the operating system, it is
# usually the best to change the current directory to the top
# directory of all filesystems.
#
# FreeMiNT 1.16.0 does this automatically.

cd u:/

#
# The "echo" command is really straightforward.
#

echo Setup complete, now booting the system...
echo

# End of mint.cnf file

@line 1 70 0

@endnode

@node "Environment variables set by the kernel"

@line 1 70 0

The FreeMiNT kernel 1.16.0, unlike previous versions, exports few 
environment variables on its own during startup. These are:

PATH
This is initially set to u:/

SYSDIR
Contains the full path to the system directory.

TERM
The kernel sets this to "st52" (the terminal type of the Atari ST 
console).

SLBPATH
This is set to the same value as $SYSDIR by default.

UNIXMODE
This is set to "/brUs".

PCONVERT
This is set to "PATH,HOME,SHELL"

@line 1 70 0

@endnode

@node "The mint.ini file"

@line 1 70 0

As of kernel version 1.16.0 the FreeMiNT uses an additional
configuration file, apart from the traditional mint.cnf. The
difference is, that the mint.cnf contains settings used to tune the
system, when everything is practically up, while the mint.ini file
declares some defaults @{B}before@{b} initialization.

The mint.ini file defines variables, which you can change inside
the kernel boot menu (hold down the left shift key while booting
FreeMiNT to get in). While exiting from the boot menu, the system
can overwrite the old mint.ini file with new one containing the
defaults you set, so that new settings will be used at every
bootup. When no mint.ini file is found, all these are set to 'YES'
by default.

There are six variables, which can be set to 'YES' or 'NO':

@{B}XFS_LOAD@{b} and @{B}XDD_LOAD@{b}
When set to 'NO', it will prevent the FreeMiNT kernel from loading
filesystem drivers (XFS) and device drivers (XDD) respectively from
the disk. This may be useful to bootup the system, eventhough
there's a broken driver installed.

@{B}EXE_AUTO@{b}
When set to 'NO', the auto folder programs appearing after mint.prg
will not be executed.

@{B}MEM_PROT@{b}
Enable the memory protection ('YES') or not ('NO'). This works
independently of the kernel name in the auto folder - in other
words the times of mintnp.prg are gone. Notice however, that the
kernel may disable the memory protection during initialization
anyways, when it detects, that the memory management unit is
already in use. This is the case on e.g. Centurbo 2 Falcons.

@{B}INI_SAVE@{b}
'YES' states, that the current mint.ini file will be overwritten
when leaving the boot menu by the user. This can be changed in the
menu itself as well.

@{B}INI_STEP@{b}
'YES' means, that the kernel will stop in certain points while
initialization and ask the user for confirmation.

There are also three variables which have numeric values:

@{B}DEBUG_DEVNO@{b} and @{B}DEBUG_LEVEL@{b}
Identical to the keyword for the mint.cnf file. These have been 
defined also here, for the debug facilities to be easier enabled 
before mint.cnf is interpreted.

@{B}BOOT_DELAY@{b}
Defines the time (measured in seconds) the kernel will wait for you 
to press SHIFT to enter the boot menu. After the time is passed, the 
kernel will continue booting. You can set this to 0, the boot menu 
will be disabled then (you wont' be able to enter it during bootup).

Notice that the mint.ini is a plain text file and being that can
obviously be edited with a text editor. The discouraging comment
you can see there ("do not edit") is mainly added to prevent users
from inserting own comments into the mint.ini file, because these
will go away once the mint.ini file is rewritten by the system.
This is so, because the mint.ini parser is not complicated, thus
everything that does not look like a known command, is ignored and
not preserved between read and writeout.

@line 1 70 0

@endnode

@node "The keyboard.tbl file"

@line 1 70 0

The optional keyboard.tbl file located in the system directory (i.e.
the same as mint.cnf is) contains the global keyboard translation
table. Example translation tables in source and object form, and
also a program that compiles them, are available along with the
kernel source distribution.

@line 1 70 0

@endnode

@node "The unicode.tbl file"

@line 1 70 0

The optional unicode.tbl file located in the system directory (i.e.
the same as mint.cnf is) contains supplemental data for the
default codepage tables, i.e. tables which map Unicode characters
into ASCII.

@line 1 70 0

@endnode


@node "Understanding the concept of an 'init program'"
@prev "The mint.cnf file"

@line 1 70 0

It may not be obvious for everyone, but a typical operating system
usually consists of at least two separate parts. One is the system
kernel, that is usually a library of very basic functions. The
other is a shell, the actual user interface. Of course, there
usually are more parts, but these two are the real corner stones.

Although both are seen on the process list as processes, a true one
is usually the shell, because the kernel is in fact never
explicitly scheduled for execution. Its code is only executed when
another process calls a system function in order to use services
offerred by the kernel.

In FreeMiNT the actual system binary (mint.prg) is the kernel. It
cannot run alone, because it does not contain any code that could
work as an operating system shell. The function of the mint.prg is
to setup the machine and rearrange its configuration for a
multitasking environment, setup the basic environment, which
involves for example reinitializing the memory management and
preparing the scheduler to run, then finally provide a number of
functions programs can use to manage the machine resources. After
all that is done, the kernel tries to find, execute and hand the
control off to an external program, which could take care on
further initialization and (possibly) responsibility for
interaction with the user. In Unices such a program is commonly
called 'init'.

@{B} It is very important to understand, that the 'init' program,
@{B} whatever it really is, is completely necessary for the system
@{B} to operate.
@{b}
In MultiTOS-like configuration of the FreeMiNT, the 'init' program
is GEM, or, strictly speaking, the multitasking AES. The GEM (AES)
is not a part of the FreeMiNT kernel binary, and, due to legal
reasons, it is not even a part of the FreeMiNT distributions. In
other words, to use the multitasking GEM, you must get its
distribution floppies separately.

@{B} Since the GEM is one of possible init programs, you cannot specify
@{B} a GEM application in INIT= or GEM= keywords, since at this stage
@{B} of the system initialization, the GEM is not yet active!
@{b}
To start the 'init' program, you must specify its full pathname in
the INIT= keyword of the mint.cnf file. For example,

INIT=u:/c/mint/init.prg

Alternatively, if your init program is GEM (as said above), you can
use the GEM= keyword, which is an instance of the aforementioned
INIT= keyword with slightly different meaning. It is generally no
place here to explain technical details, for now you just want to
know, that you use GEM= keyword if your init program is GEM, and
INIT= keyword otherwise. Notice, that only one of these two may be
used in one mint.cnf file!

@{B} The pathname given in INIT= or GEM= keyword must be accurate, and
@{B} it must point to a valid executable file. If starting the init
@{B} program fails, the FreeMiNT kernel halts the machine, and you have
@{B} nothing to do except rebooting to TOS to fix the configuration.
@{b}
Once started, the init program (whatever it is) takes the control
on the further boot process using own configuration files and/or
scripts. For example, the Atari GEM (the multitasking versions) and 
Geneva use gem.cnf file, while the Un*x-like init -known as 
'init.prg' or just 'init' - wants to execute shell scripts
present in /etc (u:/etc) directory. Hence you must refer to the
documentation of the init program you choose on how to setup it or
tune the configuration to your own requirements.

@line 1 70 0

@endnode


@node "Understanding the concept of multiple filesystems"
@next "Understanding the memory protection mechanism"

@line 1 70 0

The FreeMiNT implements so called virtual filesystem (VFS), which
means, that you're no longer limited to the old, PC-DOS like style
of storing data on the disks. Specifically, various filesystem
types may provide various features, like additional attributes,
long filenames etc. Using the VFS gives you an access to
virtually any type of data storage only provided there is a
filesystem driver available. A good example is ext2.xfs module,
which allows read/write access to disks used by the Linux operating
system, spin.xfs, which provides access to many types of CD-ROM
disks, and so on. Such a module is called XFS, which stands for
'eXtended File System driver'.

Of course, the VFS mechanism is not only for accessing weird
storage media, when urgently necessary. It is for example a
standard way of implementing ramdisks under FreeMiNT. Also, some
kinds of setup and some software may want to run on a specific kind
of a filesystem, although it is usually not so that you couldn't
use a different one - just using the proper XFS allows programs to
expand their full possibilities. At the other hand, some old TOS
programs may refuse to run, when started on a filesystem, that
differs badly from the TOS filesystem they know about.

Apart from such 'external' filesystem drivers, the FreeMiNT kernel
contains several XFS modules compiled into it. In fact, almost all
of them, except the FAT FS, are pseudo-filesystems, which serve as
the 'front end' for various FreeMiNT internals, and all are mounted
on u:, the main pseudo-drive.

  unifs    biosfs    pipefs    procfs    kernfs    ramfs    shmfs

The remaining entries in u: are other filesystems, mostly floppy
disks and hard drive partitions, ramdisks etc. Apart from symbolic
links (which usually point to real directories stored somewhere on
your disks), all these entries do not represent real folders, but
other filesystem drivers 'mounted' on u:. When you enter such a
'folder', the FreeMiNT kernel activates the appropriate XFS
requesting it to handle the storage type the folder represents.

Apart from the aforementioned pseudo-filesystems, the FreeMiNT
kernel also contains a 'real' XFS, being the default one to handle
hard and floppy disks. Currently it is FAT filesystem (so called
NEWFAT FS, to be differentiated from 'old FAT FS', i.e. the TOS
filesystem), which is able to read/write Atari and PC disks
containing FAT12, FAT16, FAT32 and VFAT filesystems. Thanks to
that, you can access disks formatted for TOS, PC-DOS, Windows 95
and Windows NT (provided your hard disk driver supports XHDI
version at least 1.25).

The following chapters discuss the most common differences between
various filesystems.

Path and filename length

Case sensitivity

File ownership and access permissions

Wildcard expansion

Filesystem cache

@line 1 70 0

@endnode


@node "unifs"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

@{B}unifs@{b} aka @{B}unified filesystem@{b}
This is what handles all references to the root directory of the
drive u:. The XFS allows to mount other filesystems on it, and
create symbolic links, but you cannot make hard links, create
folders the usual way, or use it as data storage for files.

The unified filesystem is considered the top directory (so called
'root filesystem' referenced as '/' by Un*x software) for all types
of regular and virtual files and directories present anywhere in
the system - and also outside it, if another machine is 'mounted'
locally via the Network File System (nfs).

In other words, all files accessible by the GEMDOS can be
referenced from the unifs. For example, a file like
@{B}mint.cnf@{b} present in the @{B}mint@{b} directory of the
drive c:, what is 'normally' referenced as

@{B}c:\mint\mint.cnf@{b}

can be also accessed via the unifs as

@{B}u:\c\mint\mint.cnf@{b} or
@{B}/c/mint/mint.cnf@{b}

because the drive c: is 'mounted' on the unified filesystem as a
folder.

@line 1 70 0

@endnode


@node "biosfs"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

@{B}biosfs@{b} aka @{B}BIOS filesystem@{b}
This one takes care on all references to the /dev directory. All
entries there are system devices actually active. You rather don't
do anything there manually.

@line 1 70 0

@endnode


@node "pipefs"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

@{B}pipefs@{b} aka @{B}pipeline filesystem@{b}
This is the /pipe folder. All entries there are FIFOs. They're
created by software wishing to use this way of interprocess
communication. As in the biosfs, no real use for a human, but
important for the software.

@line 1 70 0

@endnode


@node "procfs"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

@{B}procfs@{b} aka @{B}process filesystem@{b}
This is the /proc directory. Each entry there represents a process.
You cannot explicitly create anything there, entries are made
automatically by the system when you start a program, but you can
'delete' them. When you drag a file to the trashcan, the system
attempts to terminate the process represented by the 'file' you
dragged. Be sure you know what you're doing, before you try that!

The date and time associated with the proc directory entry provide
information on the date and time the process was started. The
attribute field symbolizes the actual (this is changing
continuously) state of that process. The size provides information
on the actual amount of memory the process has access to.

Notice: that last is usually just the amount of memory the process
took from the system resources, but in some cases it may be not
completely true. For example, if there is a 16k block of memory
shared by two processes, the size of this block will be added to
the process 'size' displayed in the proc directory for @{B}both@{b}
programs those are sharing it. So you can have an impression, that
either process is using a separate 16k block and the size of the
free memory was lowered by 32k, while in fact only 16k is being
utilized. As a result, in an extreme case, if you have a lot of
processes running, the total amount of the memory used by all of
them (as indicated on the proc directory listing) may be bigger
than the total amount of physical memory your machine is equipped.
This is not a bug, it is expected to work this way.

The speciality of the procfs is, that although it is an 8+3
filesystem, the first 8 characters of the filename do NOT matter.
It is only the numeric extension (process identifier) that uniquely
distincts a process from another, the human readable name has
visual purpose only.

Apart from user processes (i.e. your programs) appearing, you can
see there are entries for programs you never explicitly started.
These are system processes. Typically you can see the following
system processes:

        mint.000        FreeMiNT kernel itself
        init.001        your init program, as specified in mint.cnf
        update.002      so called update daemon, syncing disk caches
        ...             more entries here are processes started by
        ...             the init program according to its startup
        ...             scritps
        AESSYS.043      the GEM AES
        SCREEN.282      the GEM AES screen manager
        ...             more processes started by AES

The special thing about the first three as shown above is, that
neither one can be signalled (killed with a signal). Any signals
delivered to the process 0 (the kernel) turn back to hit the
sender. The processes 1 and 2 are proofed against SIGKILL and
SIGSTOP signals, and have caught the rest.

Of course, you should not rely on this example and assume that e.g
process number 002 is always the sysupdate daemon. The process
identifier often depends on the system configuration, and although
the init so far has always been pid 1, the pid 2 may be a process
started by MiNT Net for example, if that last is installed. The
update daemon may then have pid 3, or greater.

@line 1 70 0

@endnode


@node "shmfs"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

@{B}shmfs@{0} aka @{B}shared memory filesystem@{0}
This one is the /shm directory. Entries there (if any) represent
memory blocks, those have been explicitly requested to be shared
between two or more processes. As such structures are usually
temporary, you rarely see anything there. Also, the shmfs has
completely no use for a human.

@line 1 70 0

@endnode


@node "ramfs"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

@{B}ramfs@{b} aka @{B}ramdisk filesystem@{b}
This one is the /ram directory. This one is not really used by the
system, it is just a dynamic ramdisk. It previously used to be a
separate xfs module, however, has been integrated into the kernel
as of version 1.15.0. If you have a lot of RAM, you can use the
ramdisk as a temporary directory (/tmp), for speed reasons,
although since disk filesystems are cached, the /tmp located on a
partition is fast too.

@line 1 70 0

@endnode


@node "kernfs"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

@{B}kernfs@{b} aka @{B}kernel filesystem@{b}
This is the /kern directory. It has been added in FreeMiNT 1.15.5
mainly as an expanded replacement for /proc.

Files present in the /kern directory contain global information
about the system. These are:

@{B}/kern/buildinfo@{b}
This file provides information about the compiler, options and
flags which were used to compile the kernel, for example:

CC: gcc version 2.95.2 19991024 (release)
CFLAGS: -mshort -m68030 -O2 -fomit-frame-pointer
CDEFS: -DMULTITOS -DVERBOSE_BOOT -DTRAPS_PRIVATE -DCRYPTO_CODE
       -DBOOT_MENU -DONLY030 -DCPU030

Obviously, the definitions set in the FreeMiNT's config.h are not
taken here into account.

@{B}/kern/cookiejar@{b}
The cookie jar slots listed in the order they have been installed,
for example:

# Slots available: 1024
# Slots used:        20
0x5F435055 (_CPU): 0x0000001E
0x5F465055 (_FPU): 0x00060000
0x5F56444F (_VDO): 0x00030000
0x5F4D4348 (_MCH): 0x00030000
0x5F535749 (_SWI): 0x000000BF
0x5F534E44 (_SND): 0x0000001F
0x5F464443 (_FDC): 0x01415443
0x5F414B50 (_AKP): 0x00000001
0x5F494454 (_IDT): 0x0000112D
0x53435349 (SCSI): 0x00164D58
0x55534844 (USHD): 0x0000FBFA
0x58484449 (XHDI): 0x0016124C
0x4E564449 (NVDI): 0x00076D1C
0x46534D43 (FSMC): 0x0005E1F4
0x4D694E54 (MiNT): 0x0000010F
0x5F464C4B (_FLK): 0x00000000
0x504D4D55 (PMMU): 0x00000000
0x6E414553 (nAES): 0x002EA000
0x45644449 (EdDI): 0x0005EEE6
0x44485354 (DHST): 0x00000006

Each line, except the first two, contains the jar tag
hexadecimally, the same value in ASCII and the entry value in hex
respectively.

@{B}/kern/cpuinfo@{b}
Here the basic information about the CPU is provided, it may look
like this (Falcon030):

CPU:        68030
MMU:        68030
FPU:        68882
Clockspeed: 16 MHz
BogoMips:   3.96

The 'BogoMIPS' field contains an approximate information about the
CPU speed measured in million instructions per second. The rest
should be self explaining.

@{B}/kern/filesystems@{b}
This is a list of installed filesystem drivers.

@{B}/kern/hz@{b}
The system timer resolution in ticks per second.

@{B}/kern/loadavg@{b}
This is the current load average information. The first three
numbers provide the information about the average system load last
1, 5 and 15 minutes respectively. The fourth one, presented as a
fraction, is the number of the currently running processes relative
to the total number of processes, e.g. 4/25 means, that four
processes are running, out of 25 total. This is continuously
changing as processes are scheduled. The last number currently
always equals 0.

@{B}/kern/sysdir@{b}
This is the pathname to the FreeMiNT system directory, usually 
u:/c/mint.

@{B}/kern/time@{b}
Here is the information about the kernel time, i.e. the number of
seconds since January the 1st 1970, and the same number with
timezone value subtracted.

@{B}/kern/uptime@{b}
The system uptime and the total idling time in seconds.

@{B}/kern/version@{b}
The system name, version number and compile time.

@{B}/kern/welcome@{b}
The system welcome messages displayed at bootup.

@{B}/kern/devices@{b}
@{B}/kern/dma@{b}
@{B}/kern/meminfo@{b}
These are not yet implemented.

Folders inside the /kern provide an extended information about
processes separately for each one.

@line 1 70 0

@endnode


@node "Path and filename length"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

Old TOS filesystem supported 'short filenames', i.e. a directory
entry representing a file or folder could have maximum 12
characters (8 for the filename, 1 for the dot, 3 for the
extension, so called 8+3). The maximum length of a path name was
128 characters.

Modern filesystems may allow longer file and pathnames, for
example, NEWFAT FS supports up to 255 characters for the filename
and additional 259 character long pathnames. Under ext2.xfs the
pathnames have 'unlimited' length, which means, that they're
limited not by the filesystem driver, but by the DOS core inside
the FreeMiNT kernel. This 'unlimited' limit is actually 1024
characters (1 kilobyte). UNICODE characters and blank spaces in
filenames are also perfectly legal from the DOS point of view,
although it is of course up to the filesystem driver code to allow
or disallow them.

Nevertheless, programs written in pre-MultiTOS era, and some
written after the MultiTOS has been revealed too, cannot cope with
long filenames. The FreeMiNT provides various forms of filename
truncation mechanisms for such software, so that most even very old
programs could work on an XFS with long filenames. However, there
are programs which completely refuse to run on an extended
filesystem. Such software should be used on disks where long
filenames are disabled (e.g. NEWFAT without VFAT).

@line 1 70 0

@endnode


@node "Case sensitivity"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

There are three general methods of storing file/folder names on the
disk:

@{B}Case insensitive@{b}
All filenames are stored on the disk and appear on directory
listings with unified casing (all upper or all lower). Mixed casing
is not allowed, there is no difference between upper and lower case
letters. Names like "Program.App", "program.app", "PrOgRaM.aPp" are
considered identical. A reference name like "PROGRAM.APP" to a
file, which was saved as "program.app", is perfectly legal. An
example of such a filesystem is the TOS FS or NEWFAT without VFAT
extension.

@{B}Case preserving@{b}
This is similar to the case insensitive one, with a notable
exception, that the filename casing is preserved in the form used
by the creator of the file. For example, if you create a file
"Program.App", it will appear in directory listings as
"Program.App". However, it is only some sort of visual stuff, the
casing still does not matter when directory searching is performed.
Hence the "Program.App" file can be legally referenced as
"program.app", "PROGRAM.APP" or whatever. An example of such a
filesystem is the NEWFAT with VFAT or fnramfs.xfs (ramdisk). Also
all internal pseudo-filesystems in FreeMiNT, like unifs, biosfs
etc. are case preserving.

@{B}Case sensitive@{b}
Here casing just matters. If you save a file under a name like
"program.app", you cannot access it later as "PROGRAM.APP", because
these two names will be considered different. Also, a case
sensitive filesystem is simultaneously case preserving by nature.
An example of such a filesystem is ext2.xfs or minix.xfs.

@{B} NOTICE:
@{B} Because of the case preserving and case sensitive filesystems, the
@{B} old TOS convention of storing all path and filenames in UPPERCASE
@{B} is *** no longer valid ***. File- and pathnames should be
@{B} lowercase by default.
@{b}

@line 1 70 0

@endnode


@node "File ownership and access permissions"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

The FreeMiNT is an operating system with multiuser support, which
means, that it is possible to create a setup, which could grant -
in a controlled way - multiple users an access to system resources.
Specifically, in a network, multiple users may want to access the
machine at the same time. The operating system must set things up
to eliminate all (or at least, most) possible conflicts could
happen that time, especially it must protect 'private' files of an
user from an unauthorized access made by another user.

For example, if you're receiving e-mails, your mailbox exists
physically somewhere on a hard disk - as a data file. Of course,
you don't want your mailbox to be read by other people, do you?
So privacy of your e-mails is protected by the software installed
on the computer you keep the mailbox on (or, strictly speaking, it
is protected, unless the machine is running MS Windows, but we're
generally discussing Unices here, so this question is out of topic).

This is not only (but also) a question of using proper network
software, like safe (read: 'considered safe') servers and clients;
the problem must be solved at the operating system level, so that
an unauthorized access can be denied even if the application
software is badly or maliciously written.

To accomplish that, all Unices (including the FreeMiNT) implement a
concept of data ownership. All users are granted 'accounts',
identified by username and password from the human side, and by so
called UID (short for 'user identifier') from the software side.
Additionally, users (or strictly speaking, user identifiers, UIDs)
are distributed among groups. A group of UIDs has own common
identifier, so called GID ('group identifier'). When a file is
created, the UID and GID of the creator is stored on the disk to
mark the file's ownership. They appear in the directory listing as
in the following example:

-rw-r--r--   1 draco    wheel       96470 Feb 22  1998 lice.irc
---------- --- -------- -------- -------- ------------ --------
    |       |      |        |        |         |          |
  access    |     UID      GID    length    creation   filename
permission  |                                 time
            |
     number of links

Really, the UID and GID are just numbers. However, they are
associated with human readable names using databases stored in
files /etc/passwd and /etc/groups, respectively. These databases
are used to convert numeric UID/GID to names as shown above, when
it is needed to display them in human readable form.

Although there may be many groups of many users in the system,
there are in fact only three classes of access privileges:

@{B}user@{b} (u)
The actual one who created the file, and whose UID is associated
with the file's directory entry.

@{B}group@{b} (g)
All users, who belong to the same group as the creator of the file.

@{B}others@{b} (o)
All users, who belong to group(s) other than the creator of the
file.

@{B} NOTICE:
@{B} In any case, the system administrator (Superuser), i.e. the user
@{B} with UID 0 and GID 0, can override any attributes other users
@{B} could set.@{b}

The actual access is controlled by the 'access permission' field as
shown above. This is encoded on a 10-character field, where the
first one (from the left) indicates a directory (d), link (l),
character device (c), pipe (p) or regular file (-), and the other
ones are three subfields of three characters each, indicating the
access permissions for three aforementioned classes, i.e. the user,
groups and others:

                     - r w x r w x r w x
                     - - - - - - - - - -
                       | | | | | | | | |
user can read      ----+ | | | | | | | |
         write     ------+ | | | | | | |
         execute   --------+ | | | | | |
group can read     ----------+ | | | | |
          write    ------------+ | | | |
          execute  --------------+ | | |
others can read    ----------------+ | |
           write   ------------------+ |
           execute --------------------+

If the access is given, it appears in the directory as the
appropriate letter as shown above (r, w, or x respectively). If the
access is denied, there is a minus mark (-) instead. You change
permission codes and ownership with shell command @{B}chmod@{b} or
any decent GEM desktop - please experiment with it for a while -
but not on valuable files or system binaries! - to learn how does
it really work.

@{B} There are more permission marks, than the aforementioned 'r', 'w'
@{B} or 'x'. They're not discussed here for sake of simplicity, but
@{B} they do exist and have obviously special meaning. If you come
@{B} across a file with 'weird' access permission codes, do not touch
@{B} it, before you'll be absolutely sure what are you doing!@{b}

The way this works may be sometimes tricky. For instance, the read
and write permission (r/w) control an explicit and implicit data
reads and writes referring to the contents of the file.

However, and it may be important to know, operations on the
directory entry itself may depend on the ownership and permission
access of @{B}the directory the entry belongs to@{b} rather than
the ownership and permissions of the file the entry does represent.
So, if there is a file you don't have write access to, but it is
located in a directory, where you have the write access to, you can
delete the file, although you cannot overwrite its contents.

Symbolic links appear to always grant full permissions (lrwxrwxrwx)
but in fact the permission code of a symlink does not have any
meaning - when things are about an operation which requires
permission control, the link is dereferenced and the permission is
used as on the file the symlink points to.

The 'x' bit on a binary file or a shell script means an execution
ability, while the same bit on a folder (directory) means a
permission for entering the directory. A binary file with
permissions ---x--x--x cannot be read or written by anyone, but can
be run by everybody. When same permission codes are on a folder,
everybody can enter it and read/write/execute files in it, but
nobody can list the contents of this directory!

@{B} NOTICE:
@{B} On an Un*x filesystem, the 'x' flag (so called 'x-bit')
@{B} exclusively marks a binary file as executable REGARDLESS of the
@{B} filename extension, if any. In other words, the system won't
@{B} execute an *.app file, if all 'x-bits' of the appropriate
@{B} directory entry are cleared!@{b}

Of course, all this works as expected only on filesystems, which
support the data ownership and access permissions, i.e. on ext2 and
minix filesystem. Actually, when you do 'ls -l' from a text shell
on a FAT disk, the directories will look similar, but don't get
fooled! The FAT filesystem does not really support this stuff, all
you see is emulated by the FreeMiNT kernel for better compatibility
with Un*x software. Of course, since most of these access codes are
fake, there is no real data safety and no real access control on a
FAT disk.

@line 1 70 0

@endnode


@node "Wildcard expansion"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

This topic does not quite belong to the filesystem section, as the
manner the wildcards ('*' and '?' characters when used in
filenames) are expanded depends more on the DOS kernel and
libraries, than on filesystem drivers. However, as the new widcard
expansion regulae do come with the FreeMiNT and its extended
filesystems, the question has been put into this section.

Just to remind, on TOS, the question mark '?' matches any character
in the filename, that is at the same position and the asterisk '*'
matches any string, that starts at the same position. Asterisks are
expanded independently for the filename body and extension, so that
to match all files in a directory you supply the mask as '*.*'.

Un*x filesystems don't divide filenames into separate 'body' and
'extension' parts. The dot is no longer an important delimiter, and
it belongs to the filename as any other character. As a result,
also wildcards behave differently:

- a single question mark '?' does the same as in TOS, except it
  also matches the dot character and not only in regular files, but
  in directories too.
- a single asterisk '*' matches all files and directories in the
  specified directory, except these starting with a dot.
- the mask '*.*' matches all file and folder names which contain at
  least one dot inside.
- the mask '*.' matches all files and directories, which have a dot
  as the rightmost character. For example, filenames such as
  'datafile.' or 'data.file.' will be matched, but 'data.file' -
  won't.
- the mask '.*' maches all files and directories with filenames
  starting with a dot.

@{B}WARNINGS@{b}
That last also matches entries '.' and '..'! Eventhough you won't
be able to do anything to these entries themselves, however when an
operation is started, which is supposed to work recursively across
directories, and the mask specified matches the parent directory
entry ('..'), the command will first walk up to the topmost
directory in the system (i.e. u:/), then go down recursively
across its folders.

In other words @{B}this is likely to affect all files and folders@{b}
@{B}which are present in the system@{b} including devices, pipes,
processes, remote machines mounted via network filesystem,
everything. If you were unfortunate enough to dispose a 'delete'
operation in this manner with superuser (root) privileges, it will
wipe your harddisks destroying the system completely.

Many people reflexively add flags '-rf' ('operate recursively' and
'force') to any command rm they dispose. @{B}THIS IS A VERY WRONG@{b}
@{B}HABIT@{0} and in case of a mistake done with superuser privileges,
it may end up with a wiped hard drive. You have been warned.

The other common mistake is to add a superfluous space character
into the specified filemask. Since GNU tools usually accept
multiple arguments, the argument '* .o' (given instead of an '*.o')
will be accepted as two masks and interpreted as 'match all files
in the current directory and these ended with .o'. Again, the
command 'rm -rf * .o' destroys all entries in the current directory
(including subdirectories).

If you are not sure, what files will be matched by a mask you're
going to specify for a command, you can always use the command
'echo' supplying it with the mask. It will display all filenames
subjected to be matched.

There is a file called 'Unix horror stories' available on FTP
sites. The file (150k, plain text) consists of USENET postings made
by Unix administrators, and really many of the 'horrors' described
refer to the topic 'How have I managed to wipe my hard drive'.
Although many of the topics discussed there do not really
belong to FreeMiNT, you're encouraged to treat this as a lecture
for your spare time.

@line 1 70 0

@endnode


@node "Filesystem cache"
@toc "Understanding the concept of multiple filesystems"

@line 1 70 0

The filesystem cache is (physically) a memory area where all disk
operations are bufferred. The main goal of the cache is to reduce
the hard drive activity by avoiding as much explicit reads and
writes as it is only possible - write operations go to the cache
rather than directly to the media, also read operations will access
the cached data rather than hard drive sectors. As the memory
access is usually much faster than a disk access, this
significantly increases the general filesystem performance,
especially (but not only) when deleting/renaming/changing
attributes on multiple files at a time.

As said above, filesystem reads will first lookup the cache, then
access the physical media just when the requested data is not found
in it. A write operation will put data to the cache so that it is
available for subsequent read operations. Thus, a larger number of
interleaved read/write operations referring to the same chunk of
cached data - such as while renaming multiple files in one
directory - will at most result in a single disk access for reading
the chunk, and another disk access for writing the final result out
to the drive, instead of generating one read and one write per
single directory entry being updated.

Of course, when all writes go to the cache, the buffer finally
becomes full and gets emptied by writing a part of it back to the
physical media. Also the same is done in certain time intervals, so
that the media gets updated on regular basis.

There are several programs which provide filesystem cache
functionality to TOS. You don't need any of these anymore, because
a high performance caching module has been built into the FreeMiNT
kernel. Hence, when using FreeMiNT, it is advisable to deactivate
all external caching programs, read/write buffers, FAT caches and
so on, because these, in conjunction with the FreeMiNT built-in
cache, will @{B}slow down@{b} disk operations, rather than speeding
anything up.

The backside of the caching is, that written data resides for
some time in the cache only. This 'some time' is actually several
seconds, as configured in the mint.cnf file. If something bad
occurs by this time, like a power failure or system crash, the data
is never written back to the disk and a data loss occurs. This is
also the reason, why we need to close the system with shutdown
programs instead of just switching the power off - when the
shutdown is initiated, the system ensures that all the cached data
is written out to the media before performing a reboot or entering
a halted condition.

Refer to the FS_CACHE_SIZE= keyword in the chapter The mint.cnf file 
on how to activate and configure the FreeMiNT filesystem caches.

@line 1 70 0

@endnode


@node "regular file"
@alias "Regular file"
@toc "Filesystem cache"

@line 1 70 0

A 'regular' file is the same as a normal data file on TOS - a
number of data blocks on a disk, associated with a directory entry.
It is called 'regular', because apart from that there are also
'links', directories and 'special files', such as pipes or devices.

@line 1 70 0

@endnode


@node "number of links"
@alias "Number of links"
@toc "Filesystem cache"

@line 1 70 0

The leftmost number in a directory entry displayed by the command
ls is a number of directory entries associated with (linked to) the
file. This can have two different meanings:

Regular file
This is the number of directory entries associated with the file.
In other words, it is the number of hard links made to this file.

@{B}Directory@{b} (folder)
This is the number of directories created inside the directory.
Notice even an 'empty' folder contains two such entries, i.e. the
'.'(reference to the folder itself) and '..' (reference to the
parent directory of the folder). Thus, practically, the number in
question is the number of directories inside the folder @{B}plus@{b}
@{B}two@{0}.

@line 1 70 0

@endnode


@node "Understanding the memory protection mechanism"
@prev "Understanding the concept of multiple filesystems"

@line 1 70 0

The FreeMiNT, what is normal for Unices, but new to TOS-like
systems, has a concept of protecting the program's memory space
from unauthorized "intruders". Such an intruder is usually another
program, that went vegetables due to its bugs.

The hardware memory protection is implemented at the CPU level on a
"per process" basis, so that any memory a process hasn't allocated
is considered invalid for that process. Virtually, such memory does
not exist, and starts to do just after the process requests it from
the system using a Mxalloc() call, either implicitly or explicitly.
The memory protection serves for preventing an errant process from
destroying other programs running in parallel, or even the system
itself. At least, that's the theory.

In practice, apart from running the Un*x software, which usually is
perfectly compatible with memory protection, the FreeMiNT has to be
also compatible with TOS software. Either TOS lacks some features,
necessary for programs, or programmers lack knowledge, necessary to
write a decent program, just enough to say, that quite a lot of TOS
programs tend to enter supervisor mode and do things beyond the
system control. Under TOS it is perfectly okay, however, under
FreeMiNT there's a risk for a conflict with the resource protection
mechanisms - and the FreeMiNT, to be generally compatible with TOS
software, must allow that, relying on a limited confidence, that
the software generally "knows what it is doing". If it does not
know, there may be no chances for a recover.

Fortunately, the FreeMiNT implements the memory protection in a
way, that allows some user tuning. The way the program's
memory space can be protected is encoded in the program's
binary file header. There are four "levels", or modes, of
the protection implemented:

@{B}Private@{b}
In this mode the program's memory space is under a very restrictive
protection: noone can access the area taken by the program, except
the program itself and the operating system. Even interrupt
handlers, if any are installed by the program, cannot do that! This
is the default protection mode and most programs really work fairly
good under it.

@{B}Private/Readable@{b}
Here the protection is less restrictive: still, noone can write
to the program's area (except the program itself and the operating
system), but everybody can safely read data from it. You should set
this mode for GEM programs, those use the AV protocol, but are not
written with the memory protection in mind. ST Guide} is one of good
(bad) examples here.

@{B}Super@{b}
The full name is "Supervisor accessible": the program's area can be
accessed by noone (again, except the program itself and the
operating system) as long as the "intruder" runs in the CPU user
mode. However, any code running in the CPU supervisor mode (as
an interrupt handler for example) can access the program's memory
space freely. You should set this mode for software, that installs
own interrupt handlers. The Dump!module player is a good example.

@{B}Global@{b}
This mode can be set, if a program does not run under any of the
aforementioned protection modes. The program's space is unprotected
and anyone can freely access it.

There are generally three usual ways a program violates the memory
protection:

1) it tries to access the memory, that belongs to another program.
   The system alert, that appears then, mentions a memory violation
   "type private". Paradoxally, the program, that has been shot
   down this way, may not be guilty. For example, if you notice,
   that your desktop gets killed due to memory violation "type
   private", while you were playing with *.hyp files, you should
   change the protection status not in the desktop executable, but,
   yes, you guessed it - in the st-guide.app.

2) it tries to access memory, that does not belong to anyone. It is
   called "memory violation type free". This is what GFA BASIC
   programs usually do, but also the aforementioned st-guide.app
   may be an example, when it comes to display a colour image
   embedded in a *.hyp document. This means a bug in the program,
   and we cannot do much in this point (except dodging the author
   to fix the bug).

3) it causes a complete system crash. Examples are: Pure Debugger,
   X-Boot III or Dump! module player. Paradoxally, as it is with
   the mentioned programs, it may be the most easy thing to fix -
   it is just enough to change the protection status to
   "Supervisor".
   Newest FreeMiNT versions are a bit more picky, try to keep an
   eye on such programs and warn the user (you), when it is likely
   that the further program execution will bring the system down.
   Unfortunately, it is not always possible to detect, that the
   program is going to do an ugly thing.

Using the Thing desktop you can try changing the protection status
of a program and test the behaviour. As a rule, if a program runs
fine with the "Private" status, you should leave the things as they
are. If it does not, the next tested status should be "Readable",
then "Super", and finally "Global".

If the program still does not work, it may be worth to give it a
try without the memory protection. However, you're encouraged to
run the system in the memory protected mode (unless it is
completely unacceptable for you).

@{B}NOTICE:
@{B}The memory protection mechanism works only on machines equipped
@{B}with processor 68030 or newer.
@{b}

@line 1 70 0

@endnode


@node "Prioritization"

@line 1 70 0

The commonly known truth is that a CPU can run only one instruction
at once. Hence, even in a multitasking system, programs don't
really run in parallel - they're granted the CPU time in turns,
each one for a short period of time. This period is called a
'timeslice'. Each time the time slice 'expires', the operating
system executes some special code (called 'the scheduler') and this
decides, which process is about to be granted the CPU time for the
next slice.

All this allows to make two observations:

1) the shorter is the timeslice, the more processes are granted CPU
   time per second, so the time to wait for a program's reaction on
   an event is shorter. We say that 'the process response time is
   better'.

2) however, the shorter is the timeslice, the more often the
   scheduler is executed. Since the scheduler also takes the CPU
   time to run, making the tasks more responsive also arranges more
   of the general CPU power for the actual task switching. In other
   words, the shorter is the timeslice, the general system's
   performance is worse.

Changing the timeslice period is global and affects all the system
processes. Apart from that, the FreeMiNT offers a way to
individually control the amount of time granted processes by the
scheduler. Each process is assigned a special attribute called
'priority'. The higher the priority value, the more CPU time the
process is granted - hence it 'runs faster'.

Of course, the CPU time is a definite quantity, so if one process
gets higher priority, the rest of processes will be automatically
granted less time. And this is the reason, why the exact effect of
a priority change cannot be foreseen accurately. Namely, the actual
amount of time to be granted depends not only on the priority
value, but also, of course, on the actual number, state and
priority of all processes present in the system at the moment.
Generally, if you set maximum priority for a process, you can
expect it will get more timeslices, but if you set maximum priority
for all processes, there will be no visible effect.

To make things more complex, the operating system may automatically
tune priorities making them bigger or lower when necessary. Of
course, the preset priority value is considered default all the
time and it is used for the process most of the time. However, if
the OS decides, that a process may need more CPU time at the
moment, it can momentarily raise the priority level for the
process - and vice versa, when it turns over, that a process does
not need so much CPU power, its priority level can be lowered.
After all the priority level, obviously, sooner or later returns to
the default preset value. In other words, the priority you set is
considered a basic level, but the real ('current') priorities
change automatically around that level all the time depending on
the current requirements. This behaviour is called 'adaptive
prioritization'.

Notice there are no 'top priority' or 'background priority' presets
in FreeMiNT. The adaptive prioritization method used is considered
more flexible, than the way of using two fixed priorities, as it
can be observed on some systems.

@line 1 70 0

@endnode


@node "The problem of the memory fragmentation"

@line 1 70 0

When using the command 'free' from a text sheel, you can see text
similar to the following:

6365184 bytes (6216K) in 11 blocks free, largest free block 4227072 (4128K)

The fragmentation is a phenomenon generally known to occur on data
storage. Basically, if we have 1 MB of free disk space on a disk,
then we save there a file, that is 256k long, the amount of free
space is lowered by this 256k. Then we save another file, that is
100k long, and the free space shrinks by further 100k. When we
delete the first 256k file, the total amount of the free space on
the disks grows back by 256k, however, in fact, the other 100k
splits the whole media to two free blocks ('fragments') of 256k and
668k in size. The disk is 'fragmented'.

There's a very similar problem with the RAM space, that is likely
to occur on every multitasking system. Similarly to the situation
described above, when we have a 1 MB of free memory, then we load a
program that is 256k long, and subsequently another one which is
100k long, then we finally terminate that first one leaving the
other one running, the terminated program leaves a free 'hole' in
the memory so that the previously solid 1 MB block of free memory
gets splitted into two blocks by 256 and 668k each. The memory has
got fragmented.

And it is much worse, than with the disk space, because while
writing data to a disk, the file can be efficiently distributed
among free clusters even if they don't create a larger continuous
area big enough for the file to fit. It is actually satisfying, if
the total amount of free clusters is big enough, regardless of
their position. Contrary to that, when considering memory space,
programs must unconditionally be loaded into a continuous block of
free bytes of requested size, and if they additionally ask the
system to allocate some more memory resources, it is also expected,
that these blocks will be solid and continuous as well.

Thus, contrary to the storage media, where the total amount of free
clusters must be considered while saving data, the most important
memory parameter while requesting memory resources (e.g. to load
a program) is not the total amount of free RAM, but the actual size
of the largest free block, that is possible to allocate as a
continuous area. Basically, we won't be able to load a 256k program
to 1 MB of free memory, if the largest free block of this 1 MB area
is smaller, than 256k. And of course, unlike disks, the memory
cannot be defragmented on demand.

The solution for that may be memory virtualization, the FreeMiNT
however, being developed to run on machines equipped with an
ordinary 68000 processor, works in physical memory space, not
virtualized at all. Thus, eventhough this problem will most likely
be solved in some (near) future, the system can be at the moment
severly affected by memory fragmentation, similarly to other
OSes, which use memory space the same way as the FreeMiNT does.
Basically, since the memory is dynamically used all the time, the
longer the system is up, the memory fragmentation gets bigger and
bigger, up to the (sad) moment, when it is necessary to reboot
(because the largest free block is not large enough to fit
anything anymore).

Fortunately, the amount of time necessary for the memory to get
totally fragmented, is quite long - it is averagely several days or
a week being continuously up, without a reboot. The dynamical
memory management, which can momentarily raise the fragmentation
level, also serves for decreasing it, so that in longer time
periods of lower system's activity a number of small blocks of
memory may 'automagically' concatenate into a larger continuous
area, what may obviously prolongate the effective lifetime of the
system.

And even without that it is not so that the user (you) couldn't do
anything to decrease the memory fragmentation level allowing the
system to run successfully for bigger periods of time. There are
several rules worth to obey:

1) Don't use binaries packed with programs like ICE!, Sentry
   Packer etc. which are automatically depacking after the file
   has been loaded. The depacking routine embedded in such a packed
   binary unpacks the file into a different memory location, than
   the place it all has been loaded. Shortly, this increases memory
   fragmentation. If you have such packed programs, unpack it using
   dedicated depackers or use NewDepack from Sinister Developments.

2) Try to terminate programs in the reverse order than they have
   been loaded.

3) Try to never terminate daemon processes or applications, those
   are practically resident, like the Desktop, the Control Panel, a
   Taskbar (if you're using one). Let them run until the system
   shutdown time.

4) Remember, that the system component that greatly increases the
   fragmentation, is GEM, which needs to dynamically manage a
   larger amount of relatively small memory blocks to hold screen
   objects (like, for instance, windows).

@line 1 70 0

@endnode


@node "Supplying time zone information"
@next "Tuning TOS programs for FreeMiNT"

@line 1 70 0

Beginning with kernel version 1.14.8 the time related functions of
FreeMiNT have changed drastically. Don't worry if you have missed
to read this documentation until now; if you don't use the new
facilities you can't mess up anything. The new stuff is 100 %
compatible with the old time interface to the kernel.

@{B}1. Standard TOS time@{b}

Earlier versions of FreeMiNT have inherited the standard TOS time
setting (and retrieval) functions. The only difference was that
changing the system time required superuser privileges.

The TOS time functions had one major short-coming. The internal
representation of a calendar time caused a maximum resolution of
two seconds for the system time. Furthermore, timezones were
completely ignored; evaluating user-supplied timezone information
was left to software.

@{B}2. New MiNT features@{b}

As a default the MiNT kernel clock now ticks in UTC (Universal Time
Coordinated, GMT or Greenwich Mean Time is more or less a synonyme
for that). You can also tell the kernel about the timezone that
you're living in. Those programs that request local times from the
kernel will get values corrected according to the timezone settings
you have supplied.

No, again, don't worry. As long as you haven't set the timezone
explicitely, no correction will take place, no mess, the kernel
will believe that you live in London/UK and that there is no such
thing as daylight savings time.

@{B}3. How to use them?@{b}

The user-level (resp. system-administrator-level) interface to the
new time facilities is the tzinit program. You should add the
following lines to you MiNT configuration file mint.cnf:

# Set the system-wide time zone information
setenv TZ 'Europe/Warsaw'

# Uncomment the following line if you want to make
# the kernel clock tick in local time.
# setenv MINT_CLOCKMODE "local"

# Make the time zone known to the kernel.
exec u:/usr/sbin/tzinit

As you might have guessed, you should install the tzinit program as
/usr/sbin/tzinit but any other place will do.

The tzinit program will do two things. First it evaluates the
current setting of the TZ envariable and set the kernel timezone
accordingly.

Because the tzinit program changes kernel time information it needs
super-user privileges to run (don't worry about that if you run it
from mint.cnf or from one of the /etc/rc files). Insufficient
privileges are actually the only possible reasons for tzinit to
fail.

The tzinit program has one major bug. It should actually be a
daemon that waits and changes the kernel time information if
daylight savings time (DST) for your timezone starts or end while
your machine is running. Thus, when your local time changes from
DST to standard time or standard time to DST during your machine is
running you should reboot. In case your kernel clock ticks in local
time you also have to change the hardware clock by hand.

@{B}4. UTC vs. Local Time@{b}

You have the choice if you want the kernel clock to tick in UTC
or in local time. Both alternatives have pros and cons:

@{B}UTC@{b}
This is the standard for 'real' Eunuchs machines. A major advantage
is that you never have to change the hardware clock whether or not
DST applies or not. If you sometimes run Linux or NetBSD on your
machine you will also welcome this possibility because these
operating systems feel much more comfortable with a hardware clock
ticking in UTC.

@{B}Local time@{b}
Deprecated, but probably better if you run other non-Eunuchs-like
operatings systems, too. If your hardware clock is actually fed by
some radio time signal or other source that provides the time in
local representation you also may need this setting. The major
disadvantage. You have to ensure that you change the hardware clock
whenever DST starts or ends (when running UTC it is sufficient to
reboot).

@{B}5. The TZ Environment Variable@{b}

The TZ environment variable is the standard for setting timezone
information. Not only the kernel (via tzinit) but all software
on your system that processes calendar times evaluate it.

@{B}6. Other user-visible changes@{b}

The kernel time now has an accuracy of approximately 26 microseconds
and a resolution of 1 microsecond (the old interface provided a maximum
accuracy of 2 seconds). Provided that your software gets adapted to
the new MiNT features you will see that the accuracy increases.

@{B}7. Bugs@{b}

Many, many time-keeping variables inside the kernel use the old TOS
format (which is more or less derived from MS-DOS). This was
probably short-sighted and it causes difficulties now. You can
really confuse the system if you keep on changing the system
timezone or the kernel clock mode too often. Timestamps can get
corrupted and it processes that rely on precise timing can get
confused. Thus, you are strongly discouraged to change the system
timezone or the kernel clock mode from somewhere else than
mint.cnf. In mint.cnf you should call the tzinit program as soon as
possible.

@line 1 70 0

@endnode


@node "The TZ environment variable"
@toc "Supplying time zone information"

@line 1 70 0

This is now superseded by the MiNTLib's timezone database. It's
strictly recommended to remove any TZ environment variable and to
install the timezone database.

@line 1 70 0

@endnode


@node "Tuning TOS programs for FreeMiNT"
@next "Appendices"
@prev "Supplying time zone information"

@line 1 70 0

This list is incomplete, please send suggestions and updates.

A list of programs, those can be tuned to run under FreeMiNT:

        1st Guide
        Amail 1.05
        CAB 2.7
        Calamus 1.09N and SL 96
        clock.acc
        Connect
        Data Manager ST 1.0
        Devpac 3.10
        Diamond Edge 2.04
        Dump! 1.x by DHS (Falcon030 only)
        FastCopy Pro 1.2
        Finder 1.10
        FlaySID 3.01 (Falcon030 only)
        Magic Shadow Archiver (MSA) v.1.0ž by Marwijn Hessel
        MPEG Audio layer 2 decoder by BitMaster (Falcon030 only)
        Papyrus 7.0x
        Premium Mah Jongg (the game)
        RSC View 1.00
        Slay 0.1
        SND Play 1.0 by AssemSoft & DHS
        ST Guide
        The 1st Word Plus 3.20TT
        XBoot! III

A list of programs those are replaced by the FreeMiNT kernel, or
dedicated software, thus there's no need to use them anymore:

        Accessory v.1.31 by Murray Levine
        BigDOS by Rainer Seitel
        FPATCH2 by Atari Corp.

A list of badly programmed software discouraged to use under
FreeMiNT:

        BubbleGEM by Thomas Much (any version)
        CKBD (the keyboard driver TSR, any version)
        DATAlight by LOGILEX (the disk compressor, any version)
        TOS debuggers
        Freedom 2.x by Kolja Koischwitz
        STiK, the ST Internet Kit
        Sting by Peter Rottengatter (any version)
        Wdialog by Behne&Behne (any version)

'Discouraged' means, that you can even (with less or more
effort) get these programs to work properly, but they may still
have a bad influence on the stability of the system.

@line 1 70 0

@endnode


@node "1st Guide"
@alias "clock.acc"
@alias "Dump!"
@alias "Finder"
@alias "FlaySID"
@alias "MPEG Audio"
@alias "MSA"
@alias "RSC View"
@alias "SND Play"
@alias "Slay"
@alias "St Guide"
@alias "XBoot!"
@toc "Tuning TOS programs for FreeMiNT"

@line 1 70 0

To get these programs to work, you must reset the default
protection mode as shown below:

Program         Mode
-------         ----
clock.acc       Readable
Dump!           Supervisor
Finder          Readable
FlaySID         Supervisor
MPEG Audio      Supervisor
MSA             Supervisor
RSC View        Readable
SND Play        Global
Slay            Readable
ST Guide        Readable
XBoot!          Supervisor

Notice the above note refers to the Bitmaster's MPEG Audio layer 2
decoder, not to the NoCrew MPEG Audio player, which runs fine with
'Private' flag set.

Amail 1.05, CAB 2.7 and Papyrus 7.0x should have 'global'
protection status set, if the OLGA protocol extension 'Inplace
Drawing' is used (otherwise they run fine with 'Private' status).
Read the chapter Understanding the memory protection mechanism for
more details.

@{B}WARNING@{b}
Programs which require the 'Supervisor' flag usually grab interrupt
vectors. When such a program suddenly dies due to some failure
(e.g. bus error), these vectors may be left pointing to invalid
memory. Any next occurrance of the interrupt will crash the system
then.

@line 1 70 0

@endnode


@node "Calamus"
@toc "Tuning TOS programs for FreeMiNT"

@line 1 70 0

@{B}Calamus 1.09N@{0}
Calamus 1.09N is basically unable to find its RSC file. To get this
version to work you must copy the calamus.rsc file to the same
directory, where the main binary file calamus.prg is.

@{B}Calamus SL 96@{0}
This version tries to use the FreeMiNT extended filesystem
functions. However, due to a bug in the linked library, this is
done incorrectly, so that after the correct system response to the
Calamus request, the program gets horribly confused. Fortunately,
this error only affects the Calamus' internal fileselector. The
solution is to disable the built-in fileselector using the
system.cxm module (or upgrade to SL 98).

@line 1 70 0

@endnode


@node "Connect"
@toc "Tuning TOS programs for FreeMiNT"

@line 1 70 0

The modem terminal program Connect may want to know which system
device has a modem attached to it. For example, if the modem is
attached to the port MODEM2, to make the Connect know it, you
define the environment variable MODEMDEV, by putting the following
line to your mint.cnf file:

setenv MODEMDEV u:/dev/modem2

or alternatively, when you installed the proper serial driver,
you supply:

setenv MODEMDEV u:/dev/ttyS1

@line 1 70 0

@endnode


@node "Data Manager ST"
@alias "The 1st Word Plus 3.20TT"
@toc "Tuning TOS programs for FreeMiNT"

@line 1 70 0

@{B}Data Manager ST@{0}
This is a very old database program, ported in 1986 from PC GEM. To
get it to work correctly you must limit the amount of memory
available for this program to some size, for example 512k.
Otherwise it will hog all the memory, so that there's not enough
free RAM to actually display a fileselector.

@{B}The 1st Word Plus 3.20TT@{0}
This one is a (quite popular some years ago) wordprocessor
developed in early 1990s. The solution is the same as above.

@line 1 70 0

@endnode


@node "Devpac"
@toc "Tuning TOS programs for FreeMiNT"

@line 1 70 0

The Devpac 3.10 debugger (MonST) does not work at all. Since it
can be automatically loaded from within the editor, it is advisable
to change its filename or even completely delete monst.prg from the
Devpac's bin folder, so that the editor couldn't find it.

The Devpac 3.10 editor @{B}may@{0} work, but running it is
endangered by system crash (it may fool the AES to use its special
privileges to destroy the system). Hence it is advisable to use
another editor instead, for example QED 4.52, provided you enable
editing with CR/LF line endings ('Atari' mode). If you insist on
using the Devpac native editor, you must make sure the folder
containing the gen.ttp compiler is indicated by the PATH=
environment variable.

The Devpac 3.10 compiler (GenST) works fine under FreeMiNT and it
is still a great piece of software (because the other option, the
gas GNU Assembler is rather not for human use). Hence it is
advisable to use the GenST as a command line program from a text
shell. The gen compiler can be easily controlled using make scripts
(makefiles), as in the following example:

#
# 15/10/1999 Draco (draco@@atari.org)
#

AS= gen
AFLAGS=-I/d/asm/devpac3/incdir -I/d/asm/devpac3/lib
NAME= myprog
TARGET= $(NAME).prg

all: clean $(TARGET)

$(TARGET): $(NAME).s
        $(AS) $(AFLAGS) $(NAME).s -O$(TARGET)

clean:
        rm -f $(TARGET)

# end of file

To get this to work you have to copy or link the gen.ttp to your
main bin folder (and obviously you must have the make program
properly installed :-)). Refer to the Devpac documentation on how
to set assembly options directly in the source file.

@line 1 70 0

@endnode


@node "Diamond Edge"
@toc "Tuning TOS programs for FreeMiNT"

@line 1 70 0

The Diamond Edge generally works fine, except that it tends to
report errors when used on a VFAT disk (it does not recognize VFAT
entries, symbolic links etc). For this reason, the Diamond Edge
should @{B}not@{0} be used for checking, defragmentation or fixing
enhanced FAT filesystems.

The DADE program (Diamond Advanced Disk Editor) will also run when
its protection mode is set to 'Super'.

@line 1 70 0

@endnode


@node "FastCopy Pro"
@toc "Tuning TOS programs for FreeMiNT"

@line 1 70 0

This program works fine provided you don't invoke a nonmodal
fileselector from within it (e.g. N.Fileselector, if installed),
because such an action confuses it horribly.

@line 1 70 0

@endnode


@node "Premium Mah Jongg"
@toc "Tuning TOS programs for FreeMiNT"

@line 1 70 0

Similarly to the problem occurring with the Calamus 1.09N, the game
is unable to find the RSC file. Also, similarly, you must copy the
proper RSC file to the same folder, where the main executable is
located (either mahjongg.prg or mhj_eng.prg). It is also advisable
to unpack the binary - as it has been packed with PFX (save a copy
of the original before doing that!).

@line 1 70 0

@endnode


@node "TOS debuggers"
@toc "Tuning TOS programs for FreeMiNT"

@line 1 70 0

Debuggers are perhaps the only class of TOS application software,
that do not work in gremio. Because of the memory protection and
concept of running programs in separate address spaces, no debugger
developed for TOS (including Atari Debugger) is likely to work
correctly. No patches usually help - there are more efforts, than
effects - because the way TOS debuggers work violates some FreeMiNT
principals, and violates them completely.

There are at the moment two replacement debuggers developed
especially for FreeMiNT. The one is called DuDebug written by Craig
Graham of Data Uncertain Software. Use it, if you have no option,
because it is rather limited and rather far from being finished.
Fortunately it is available in Lattice C and assembler sources, so
perhaps some day someone will make it work better.

The other option is called Paral. It is a Pure Debugger lookalike
one with fully graphical GEM interface. However, unlike the Pure
Debugger, the Paral has *real* GEM interface and is also compatible
with 68040 and 68060 processors. It is currently (10.XII.1999) the
absolutely best debugger available for all Atari systems (and it
runs only under MiNT).

@line 1 70 0

@endnode


@node "Appendices"
@next "Gratias"
@prev "Tuning TOS programs for FreeMiNT"

@line 1 70 0

   1. Unix user's manual
   2. Graphic shell
   3. Text shell
   4. Using tar & gzip
   5. Symbolic links
   6. Special keys
   7. Glossary

@line 1 70 0

@endnode


@node "Unix user's manual"
@toc "Appendices"

@line 1 70 0

1) Unix is an operating system

2) The manual for each command is displayed after you type
   @{B}man command@{0}

3) The manual for the command man is displayed after you type
   @{B}man man@{0}

@line 1 70 0

@endnode


@node "Graphic shell"
@toc "Appendices"

@line 1 70 0

@{B}Graphic shell@{0}
The graphic shell on Atari machines is called 'the Desktop'. And
this is basically everything we can tell you about this kind of a
shell, because you (being an Atarian) are either experienced in
using the Desktop, or you have appropriate documentation for the
one you're using. There is a number of GEM shells, i.e. desktops,
available, but the absolutely best one for FreeMiNT is Thing
Desktop v.1.27 or newer. You can also try out Gemini and (as a last
resort) the Atari Desktop that comes with the last version (1.08)
of the Atari MultiTOS.

Unlike under TOS (and derivatives), usage of a GEM shell in
FreeMiNT is @{B}optional@{0} - the system is fully useable even
without it. See chapter Text shell for details.

@line 1 70 0

@endnode


@node "Text shell"
@toc "Appendices"

@line 1 70 0

The text shell in Un*x provides a CLI functionality to the system
and simultaneously serves as a script interpreter - this does not
however mean that one shell must deal with both tasks.

Shell script files in Unices are much more powerful than e.g batch
files in other systems. As a result, they are more universal and
are often used in a case, where you'd need a binary program under
another operating system. Of course, since scripts are interpreted,
the execution is slower than of a binary, but at the other hand
scripts are easier to write and really much easier to modify and
customization. Last but not least, shell scripts are cross
platform, i.e. the same script will work and do equivalent things
on either Sun, i386, RS6000 or Atari machine.

The file /etc/shells provide information on what shells are
installed. One of them - usually /bin/sh - is the default script
interpreter. Since different shells provide different script
syntax, the /bin/sh has an ability to automatically invoke another
shell and hand off the task to it. Hence it is advisable to keep
all shells installed, even if you think you use one.

The most commonly used shells are derived from either Bourne Shell
(bsh) or C Shell (csh), which are known as bash (Bourne Again
Shell) and tcsh (TEDEX C Shell) in the most commonly known
instances. The bash is great as the default script interpreter (you
can create a link /bin/sh pointing to /bin/bash), many people use
it as a CLI as well, while others prefer tcsh for that last. You
try out either one, then decide, what is better for you. You can
use multiple CLIs at a time with a windowed terminal (TosWin for
example) or virtual text consoles.

For details on shell usage refer to the system manpages. If it
isn't sufficient, you can search dedicated WWW and FTP sites for
the needed documentation, or ask people sitting on other Unices
to supply information and/or hints. For example, the tcsh has an
excellent manual called "The tcsh book", which is available on FTP
sites in HTML and manpage form, it is advisable to take a look at
it before you actually try to use the shell. Hint here: the HTML
and manpage for tcsh are the same, just the former is more 'user
friendly' (when you use a graphic HTML browser).

@line 1 70 0

@endnode


@node "Using tar & gzip"
@toc "Appendices"

@line 1 70 0

The GNU Zip (aka gzip) is commonly used under Unices. Also, as you
can probably easily notice while using FTP sites, many FreeMiNT
files have been packed with gzip too (these files usually have .gz
extension). Actually, the gzip is often preferred over ST Zip
and LHarc for the following reasons:

a) long filenames, casing, file attributes (along with permission
   and ownership codes) are accurately stored to the archive. LHarc
   archives do not retain extended attributes, ST Zip does not even
   preserve casing, and all this is often substantial, especially
   while compressing Un*x software.
b) GNU Zip compresses better retaining decent speed. LHarc is
   about 10% faster, but produces longer archives. ST Zip features
   the same average compression ratio as LHarc, but is slower.
c) GNU Zip is problemless. LHarc has few annoying bugs, ST Zip has
   a bunch of these.
d) GNU Zip archives can be transferred over networks without
   problems, ST Zip files also. LHarc archives are often recognized
   by webservers as textfiles, thus cannot be properly downloaded.
e) gz file can be unpacked on every Unix machine, because there is
   no Unix installation without gzip.
f) GNU Zip is (surprise, surprise) convenient.

People who are new to Unix world tend to complain tar.gz archives,
because they, not being used to the tar/gzip tandem, have problems
with unpacking. However, since this packing method is used on some
purpose (mainly as shown in the above point a), an assumption is
made, that anyone, who is able to use the stuff inside the archive,
also is able to unpack it without problems. In other words, if you
cannot unpack something, it is probably not for you.

The gzip is most commonly used in conjunction with GNU Tar to
create tar.gz archives (also sometimes marked as .tgz or .taz). It
is so, because neither one of the mentioned programs is actually
able to create a compressed archive. Out of these two, the GNU Tar
creates archives, which are compressed by GNU Zip. Since both
programs are very often used together, there is a facility
implemented to invoke gzip from within tar, so that the archive is
both created and compressed (resp. uncompressed) in one shot.

@{B} Since the Tar archiver and GZip packer are separate programs, you
@{B} can sometimes find archives marked tar.Z, tar.zip, tar.bz2, which
@{B} have been created with GNU Tar, but compressed using Compress,
@{B} Zip or bzip2, instead of GNU Zip. Out of these, tar.Z and tar.zip
@{B} are likely to unpack the same way as tar.gz files (i.e. gzip
@{B} should be able to decompress it). For the rest you must first make
@{B} decompression using bzip2, and then unpack the actual archive with
@{B} tar.@{b}

To quickly unpack an archive named stuff.tar.gz you use the
following command from your shell (assuming you have Un*x
distribution installed):

        tar zxf stuff.tar.gz

or alternatively, when you want to see where the files are being
unpacked:

        tar zxvf stuff.tar.gz

Reversely, to pack a folder named 'stuff' into archive
stuff.tar.gz, use this:

        tar zcvf stuff.tar.gz stuff

Instead of a single folder name you can supply a list of file and
folder names to be packed. While packing, the GNU Tar automatically
digs into subdirectories.

Sometimes it may happen that while trying to unpack something named
*.tar.gz, you only see a message saying:

@{B}gzip: stdin: not in gzip format
@{b}
This may not necessarily mean the archive is broken. Some brain
damaged network clients (notably: MSIE) can silently decompress the
tar.gz file, while it is being downloaded, still keeping the
original file name. So, as a result, we have a .tar archive (which
is true) claiming to be gzipped (which is not true). In such a
situation you can give the file one more shot omitting the 'z'
option for GNU Tar:

        tar xvf stuff.tar.gz

Invoking tar or gzip with parameter @{B}--help@{0} lists available
options. You can also try out the system manuals disposing commands
@{B}man tar@{0} and @{B}man gzip@{0} while being at shell prompt.

@line 1 70 0

@endnode


@node "Symbolic links"
@alias "symlinks"
@alias "hard links"
@toc "Appendices"

@line 1 70 0

Apart from regular files and directories (folders) you certainly
know from TOS and other operating systems, the FreeMiNT supports so
called links. A link is basically another name for a file (or a
folder), a pure reference, that is treated by the system equally as
the file (or the folder) the link "points" to.

For example, you have on your disk a file named n_aes030.sys. For a
certain reason, you need it to be referenced as gem.sys. You could
of course just rename the file, but say you want it another time to
be referenced with its original name (n_aes030.sys) too. On TOS, in
such a situation you had to make a copy of the file under a
different name, so that you had two physical instances of the same
data. Under FreeMiNT you do not make copies, but a link instead, so
that the file has two names, but its physical instance is one.

There are in fact two different types of links:

@{B}Hard link@{0}
This is litterally just another name for a file. Making a hard
link, the GEMDOS creates a regular directory entry just like for a
newly created file, but such an entry references data, that belong
to an already existing file instead.
Hard links have one big advantage, namely a reference done using a
hard link is equally fast as a reference done using the original
file name. They also do not take more place, than a normal
directory entry. But hard links have disadvantages too: first, you
can hardly :-) know, whether a directory entry is a "real" file
name, or a hard link, because they look identical (upto smallest
details) and are treated equally. Second, a hard link
@{B}cannot@{0} be created across different filesystems
(partitions). Third, hard links are supported only by few
filesystems, like Minix FS and Ext2 FS.

@{B}Symbolic links@{0}
Unlike a hard link, a symbolic link is more like a pseudo-file,
which holds an exact pathname (instead of holding data like
regular files do) for the file the link references. Symlinks take
data blocks - usually one block, to be strict - on a disk, and
additionally are much slower than hard links. However, their
biggest goal is, that they can reference files across different
filesystems, even across a network.

Unlike hardlink, a symlink is easily distinguishable from a regular
file. Symlinks are directory entries with permission encoding
'lrwxrwxrwx'. Read the File ownership and access permissions
chapter for more details.

There is also an important difference in how the system does treat
a hard link and a symlink, when the user disposes a file to be
deleted. If the file name of a symlink is given, only the symlink
will be removed and the original file remains intact. However, if
the file name of a @{B}hard link@{0} is given, the original file
remains intact @{B}provided there's at least yet one hard link@{0},
which references the data. In other words, deleting a last hard
link is equal to a physical deletion of the file referenced by that
one.

@{B}This may be important to know, because on Un*x filesystems there's
@{B}usually NO WAY to recover a deleted file.
@{b}
In other cases links reference data blocks of the file they point
to - we say that they 'are dereferenced'. While copying, if you
give a link as the source file, this by default @{B}becomes a
@{B}regular file on the destination@{0}. This is always the case for
hard links. A symlink can be copied without dereferencing, see the
documentation of your desktop and to the system manual and help
option of the command cp (@{B}man cp@{0} and @{B}cp --help@{0}
respectively).

@line 1 70 0

@endnode


@node "Special keys"
@toc "Appendices"

@line 1 70 0

When the virtual console daemon is installed, function keys F1-F9
in conjunction with the Alt key, activate virtual text consoles,
which are marked enbled by the /etc/ttytab file. Alt/F10 returns to
the 'real', graphic console.

Despite that, all versions of FreeMiNT handle the following
keyboard shortcuts:

@{B}Ctrl/Alt/Del@{0}
Warm start, as in all TOS versions.

@{B}Ctrl/Alt/RShift/Del@{0}
Cold start, as in TOS version >= 1.04.

@{B}Ctrl/Alt/Undo@{0}
Sends SIGQUIT to the whole group of processes running on the
console, including the shell. This is equal to a "logout", but
don't use it while using the GEM Desktop! :-)

@{B}Left Shift@{0}
When you hold down the left Shift key while booting FreeMiNT, it
will either ask you whether it should load itself or not (kernels
before 1.15.10) or whether it should display the boot menu or not
(kernels 1.15.10 and later).

@line 1 70 0

@endnode


@node "Glossary"
@toc "Appendices"

@line 1 70 0

@{B}FIFO@{0} aka @{B}pipe@{0}
'First In, First Out', a structure (a virtual file actually) used
for interprocess communication. Basically, if two programs open the
same FIFO, they can exchange data with read/write calls via the
FIFO without arranging disk space. Physically a FIFO is just a
memory buffer.

@{B}GEM@{0}
Graphic Environment Manager. On Atari computers the part of the
operating system, that creates and manages the graphic front end of
the OS, i.e. windows, dialog boxes, menus, mouse.

@{B}GEMDOS@{0}
On Atari computers, the part of the operating system that actually
manages data storage. The FreeMiNT kernel's core is a completely
new, multitasking GEMDOS, which replaces the old TOS' one, which is
located in ROM.

@{B}home@{0} aka @{B}home directory@{0}
In multiuser systems, a directory that contains files and
subdirectories private to the user, who 'owns' this directory.
The home directory usually has the same name as the corresponding
username. While the user is logged on, there is a variable called
$HOME in his environment, which points to the directory. All
programs started by the user inherit the $HOME as the default path
for dealing with user files. Obviously, to make it work painlessly,
there must be as many home directories in the system, as many users
are there.

@{B}manpage@{0}
System manual file accessible with the command man. When you need
to view the manpage of a program called 'gcc', you type
@{B}man gcc@{0}. These online manuals provide condensed and
specific information on the given topic, though the language
they've been written is not always fully understandable for people
not used to. Also, the first reference to the manpage can be slow,
because it (the page) need to be formatted for the current display
size. The formatted result is cached on the disk, so that all later
references to the same page are much faster.

@{B}MiNT@{0}
The multitasking kernel for Atari ST computers and compatibles. The
first version was released 18 May 1990. The abbreviation 'MiNT'
originally stands for 'MiNT is Not TOS', but later, after the
kernel was licensed to Atari Corp. and became MultiTOS, this was
changed to 'MiNT is Now TOS'. FreeMiNT is a MiNT derivative
copyrighted by Atari Corporation, and licensed under terms
described in the file COPYING included in the system distribution.

@{B}MultiTOS-like configuration@{0}
This is a term, which, as opposed to an Un*x like configuration,
describes a single user, multitasking setup, without the Un*x
filesystem structures built up on the disk and without Un*x
software. In other words, it is a multitasking TOS.

@{B}NFS@{0}
Network File System. A type of an XFS, which allows a networked
machine to access a storage media that physically exists on another
machine provided it has been connected to the same network and
allows its disks to be accessed this way (we say 'it exports own
filesystems over the network'). Disks mounted via the NFS appear on
the root filesystem (u:/) as folders and behave like local data
storage except they're usually much slower. Despite that, you can
mount and use this way any filesystem exported, even if the machine
it belongs to is located on another continent (provided both
machines are connected to the worldwide network).

@{B}root@{0}
Also known as @{B}Superuser@{0} (q.v.), the system administrator.
The name is 'root' because in earlier Unix systems the superuser's
home directory was the root directory of the entire filesystem,
i.e. the '/'.

@{B}scheduler@{0}
A piece of code inside the operating system kernel, that actually
deals with granting processes the CPU time for execution.

@{B}server@{0}
Surprisingly, a *program*, that manages some resources (especially
in networks) and allows clients to access them in standardized way.
Also common name for a computer running one or more server programs.

@{B}Superuser@{0} aka @{B}root@{0} aka @{B}System administrator@{0}
In a multiuser system an user, who is privileged enough to actually
control the operating system.

@{B}Supervisor@{0}
One of two (the higher one) privilege levels supported by the
Motorola 68k series of processors. The OS code usually runs the
supervisor mode since it grants the fullest possible control on the
hardware resources of the machine. Unfortunately, while the CPU is
switched to the supervisor mode, no multitasking is possible.

@{B}XDD@{0}
Stands for 'eXtended Device Driver', a softloaded FreeMiNT module
that installs a device on the BIOS FS (u:/dev/).

@{B}XFS@{0}
Stands for 'eXtended File System driver', a softloaded FreeMiNT
module that installs a filesystem driver, what allows to mount a
filesystem (disk) on the drive u:

@{B}TSR@{0}
Terminate-and-Stay-Resident. A class of TOS extensions loaded from
the auto folder, which become resident system extensions after they
have been loaded.

@line 1 70 0

@endnode


@node "Gratias"
@prev "Appendices"

@line 1 70 0

Thanks going to:

@{B}Tom Quellenberg@{0} and @{B}Christian Felsch@{0}
because I've done most of this document in QED 4.52.

@{B}Christian Peppermueller@{0}
because his little editor ED saved me a suicide when I started to
be beaten by formatting bugs in QED.

@{B}University of Washington@{0}
because I finally ended up with Pico.

@{B}Guido Flohr@{0}
for his work on the time zone stuff and all the supplied
information.

@{B}Frank Naumann@{0}
for his work on the FreeMiNT kernel and all the supplied
information.

@{B}Edgar Aichinger@{0}
for his final adjustments of the hypertext structure and all the
work done on the German translation.

@{B}The MiNT mailing list members@{0}
who, willing or not, gave me many hints included in this document.

@line 1 70 0

@endnode
