2696 lines
95 KiB
TeX
2696 lines
95 KiB
TeX
%
|
|
% GNO Kernel Reference Manual
|
|
%
|
|
% $Id: kern.tex,v 1.6 1999/02/21 23:37:12 gdr-ftp Exp $
|
|
%
|
|
|
|
\documentclass{report}
|
|
\usepackage{html}
|
|
\usepackage{makeidx}
|
|
\makeindex
|
|
\bodytext{
|
|
bgcolor=#ffffff
|
|
textcolor=#000000
|
|
linkcolor=#0000FF
|
|
vlinkcolor=#001177
|
|
alinkcolor=#001177
|
|
}
|
|
\begin{document}
|
|
|
|
\title{GNO Kernel Reference Manual}
|
|
\author{By Jawaid Bazyar \\ Edited by Andrew Roughan and Devin Reade}
|
|
\date{19 November 1997}
|
|
\maketitle
|
|
|
|
\begin{latexonly}
|
|
\tableofcontents
|
|
\end{latexonly}
|
|
|
|
\parindent=0pt
|
|
\parskip=1pc
|
|
|
|
%
|
|
% CHAPTER: Introduction
|
|
%
|
|
|
|
\begin{latexonly}
|
|
\chapter{Introduction}
|
|
\end{latexonly}
|
|
\begin{htmlonly}
|
|
\chapter{Chapter 1: Introduction}
|
|
\end{htmlonly}
|
|
|
|
The GNO kernel is the heart of the GNO Multitasking Environment
|
|
(GNO/ME). The GNO kernel provides a
|
|
layer of communication between the shell (and shell-based
|
|
programs) and the operating system, GS/OS. The kernel handles
|
|
such things as multitasking,
|
|
\index{background}
|
|
background processes, foreground
|
|
processes and many other features that were not previously
|
|
available on the Apple IIGS. It is these features which make
|
|
GNO/ME very powerful.
|
|
|
|
This reference manual is highly technical
|
|
in nature and is provided to help programmers develop utilities
|
|
for the GNO Multitasking Environment. The beginner has no need to
|
|
read this manual and is certainly not expected to understand its
|
|
contents. However, Chapter 5 \bf Process Management \rm and
|
|
Chapter 6 \bf Interprocess Communication \rm provide a good
|
|
background discussion for anyone who is interested in the
|
|
internal workings of the kernel.
|
|
|
|
%
|
|
% CHAPTER: GNO Compliance
|
|
%
|
|
|
|
\begin{latexonly}
|
|
\chapter{GNO Compliance}
|
|
\end{latexonly}
|
|
\begin{htmlonly}
|
|
\chapter{Chapter 2: GNO Compliance}
|
|
\end{htmlonly}
|
|
|
|
For a program to work effectively under
|
|
GNO/ME, certain rules must be followed. Most of these rules boil
|
|
down to one underlying concept ---
|
|
\bf never directly access features of the machine\rm .
|
|
Always use GS/OS, the ToolBox, or
|
|
GNO/ME to accomplish what you need. We have taken great care to
|
|
provide the sorts of services you might need, such as checking
|
|
for input without having to wait for it. GNO/ME compliance isn't
|
|
just a matter of trying to make applications work well under the
|
|
environment; it ensures that those applications stay compatible,
|
|
no matter what changes the system goes through. Below are
|
|
summarized the points you must consider when you're writing a
|
|
GNO/ME compliant application.
|
|
|
|
\section{Detecting the GNO Environment}
|
|
|
|
If your application requires the GNO Kernel
|
|
to be active (if it makes any kernel calls), you can make sure of
|
|
this by making a \bf kernStatus \rm call at the beginning of your
|
|
program. The call will return no error if the kernel is active,
|
|
or it will return an error code of \$0001 (Tool locator --- tool not
|
|
found), in which case the value returned will be invalid. The
|
|
call actually returns a 1 if no error occurs, but the value
|
|
returned will be indeterminate if the kernel is not active, so
|
|
you should only check for an error (the function
|
|
\index{toolerror} \bf toolerror\rm (3) or the variable
|
|
\index{\_{}toolErr} \bf \_{}toolErr \rm in C,
|
|
\index{assembly language programs}
|
|
the value in the A register in assembly).
|
|
|
|
You can also determine the current version
|
|
of the GNO Kernel by making the \bf kernVersion \rm call. The
|
|
format of the version number returned is the same as the standard
|
|
ToolBox calls. For example a return value of \$0201 indicates a
|
|
version of 2.1.
|
|
|
|
\bf kernStatus \rm and \bf kernVersion \rm
|
|
are defined in the \tt <gno/gno.h> \rm
|
|
header file.
|
|
|
|
\section{Terminal I/O}
|
|
|
|
The Apple II has always been lacking in
|
|
standardized methods for reading keyboard input and controlling
|
|
the text screen. This problem was compounded when Apple stopped
|
|
supporting the TextTools in favor of the GS/OS
|
|
\index{driver!console} console driver.
|
|
The console driver has a number of problems that prevent it from
|
|
being a good solution under GNO/ME. There is high overhead
|
|
involved in using it. It is generally accessed like a regular
|
|
file, which means any I/O on it must filter through several
|
|
layers before being handled. Even though in System 6.0.1 there is
|
|
a provision for patching the low-level routines the special
|
|
high-level user input features of the driver cannot be used over
|
|
a modem or in a desktop program. And GS/OS must be called to
|
|
access it, which means that while a console driver access is
|
|
occurring, no other processes can execute. See Chapter 3 \bf Mutual
|
|
Exclusion in GS/OS and ToolBox calls\rm .
|
|
|
|
GNO/ME ignores the GS/OS
|
|
\index{.CONSOLE}
|
|
\tt .CONSOLE \rm driver and replaces
|
|
the TextTools with a high performance, very flexible
|
|
generic terminal control system. GNO/ME directly supports the
|
|
console (keyboard and screen), as well as the serial ports, as
|
|
terminals. In order for a user program to take advantage of these
|
|
features and to be GNO/ME compliant, you must do terminal I/O
|
|
only through the TextTools, or through stdin, stdout, and stderr
|
|
(refNums 1,2, and 3 initially) via GS/OS. By its very nature
|
|
TextTools is slow, so we recommend using them only for small and
|
|
simple tasks. Calls to the GS/OS console driver will not crash
|
|
the system, but they will make other processes stop until the
|
|
call is completed.
|
|
|
|
You must not get input directly from the
|
|
keyboard latch (memory location \$E0/C000,
|
|
nor may you write directly to the screen memory.
|
|
GNO/ME's terminal I/O system has been designed so you don't have
|
|
to do either of these things. If you need to check for keyboard
|
|
input without stopping your application, you can make the
|
|
appropriate \bf ioctl\rm(2) call to do what you need.
|
|
|
|
In the future, GNO/ME may provide a
|
|
GNO/ME-friendly version of the GS/OS
|
|
\index{.CONSOLE}
|
|
\tt .CONSOLE \rm driver.
|
|
|
|
\section{Stack Usage}
|
|
|
|
Stack space is at a premium on the Apple IIgs. Process
|
|
stacks can only be located in \index{bank zero}
|
|
Bank 0 --- a total of 64k. This
|
|
theoretical limit doesn't apply, however, as GS/OS and other bits
|
|
of system software reserve a large chunk of this without any way
|
|
to reclaim it. There is approximately 48K of usable stack space.
|
|
This space also has to be shared with direct page space for Tools
|
|
and certain types of device drivers, however. For a program to be
|
|
GNO compliant, stack usage analysis must be done and acted upon.
|
|
Use of the stack should be minimized so that many processes can
|
|
coexist peacefully. From experience we've found that 1K usually
|
|
suffices for well-written C applications, and at a maximum 4K can
|
|
be allocated.
|
|
|
|
\index{assembly language programs}
|
|
Assembly language programs tend to be very
|
|
efficient when it comes to use of the stack. The 4K provided by
|
|
default to applications is usually more than enough for assembly
|
|
language programs. C programs can use up tremendous amounts of
|
|
stack space, especially if recursion is employed or string
|
|
manipulation is done without concern for stack usage; however,
|
|
even assembly programs can be written poorly and use a lot of
|
|
stack space. Below are some hints to keep stack usage at a
|
|
minimum.
|
|
|
|
\begin{enumerate}
|
|
\item
|
|
Avoid use of large local arrays and character strings.
|
|
Instead, dynamically allocate large structures such as
|
|
GS/OS strings with \bf malloc\rm (3) or
|
|
the Memory Manager. Alternatively, you can designate such
|
|
items as \tt ''static''\rm , which causes the C compiler to
|
|
allocate the space for the variable from main memory.
|
|
|
|
|
|
\item
|
|
Try not to use recursion unless absolutely necessary. All recursive
|
|
functions can be rewritten using standard loops and creative programming.
|
|
This is a good general programming rule because your program will run
|
|
faster because setting up stack frames is expensive in terms of
|
|
time and memory.
|
|
|
|
\item
|
|
ORCA/C 1.3 (and older) generates 8K of
|
|
stack by default, in case the desktop is started up.
|
|
Since GNO/ME compliant programs generally will not be
|
|
desktop-based, make sure you judge how much stack your
|
|
program will require and use the \tt \#pragma stacksize \rm directive
|
|
(or the \bf occ\rm (1) \bf -S \rm flag)
|
|
to limit how much stack space ORCA/C tries to
|
|
allocate for your program. Also, since ORCA/C 1.3 programs
|
|
don't use the stack given them by GNO/ME and GS/OS, when
|
|
you link your program include a small (256 bytes) stack
|
|
segment. See the utilities sources for examples of this.
|
|
ORCA/C 2.0.x (and later) allocates stack via the GS/OS supported
|
|
method, so ORCA/C 2.0 programs use exactly the amount of
|
|
stack specified by \tt \#pragma stacksize\rm .
|
|
|
|
\end{enumerate}
|
|
|
|
\section{Disk I/O}
|
|
|
|
Since the Apple IIgs doesn't have
|
|
coprocessors to manage disk access and the serial ports, either
|
|
of these requires the complete attention of the main
|
|
\index{65816 processor}
|
|
65816 processor.
|
|
This can wreak havoc in an environment with slow disks
|
|
or high-speed serial links, as accessing disks usually results in
|
|
turning off interrupts for the duration of the access. This
|
|
situation is lessened considerably with a DMA disk controller,
|
|
such as the Apple High Speed SCSI or CV Technologies RamFAST. But
|
|
this isn't as bad as it sounds; the IBM PC and Apple Macintosh
|
|
also suffer from this problem, and the solution is robust
|
|
programming. Make sure your communications protocol can handle
|
|
errors where expected data doesn't arrive quite on time, or in
|
|
full. The best solution would be an add-on card with serial ports
|
|
and an on-board processor to make sure all serial data was
|
|
received whether or not the main processor was busy (this is a
|
|
hint to some enterprising hardware hacker, by the way).
|
|
|
|
Yet another concern for GNO/ME applications
|
|
is file sharing. GS/OS provides support for file sharing, but it
|
|
is up to the application author to use it via the requestAccess
|
|
field in the \tt OpenGS \rm call.
|
|
GS/OS only allows file sharing if all current
|
|
references to a file (other instances of the file being opened)
|
|
are read-only. GNO/ME authors should use read-only access as much
|
|
as possible. For example, an editor doesn't need write permission
|
|
when it's initially reading in a file. Note that the \bf fopen\rm (3)
|
|
library routine in ORCA/C 1.2 does NOT support read-only mode
|
|
(even if you open the file with a 'r' specificier), but it does
|
|
in ORCA/C 1.3 and later.
|
|
|
|
\section{Non-Compliant Applications}
|
|
|
|
GNO/ME wasn't really designed with the
|
|
intention of making EVERY program you currently run work under
|
|
GNO/ME; that task would have been impossible. Our main goal was
|
|
to provide a UNIX-based multitasking environment; that we have
|
|
done. We made sure as many existing applications as we had time
|
|
to track and debug worked with GNO/ME. The current list of
|
|
compatible and non-compatible applications can be found in the
|
|
file ''RELEASE.NOTES'' on the GNO/ME disk.
|
|
|
|
However, due to the sheer number of
|
|
applications and authors, there are some programs that just plain
|
|
don't work; and some that mostly work, except for annoyances such
|
|
as two cursors appearing, or keyboard characters getting 'lost'.
|
|
The problem here is that some programs use their own text drivers
|
|
(since TextTools output was very slow at one time); since GNO/ME
|
|
doesn't know about these custom drivers, it goes on buffering
|
|
keyboard characters and displaying the cursor. There is a way,
|
|
however, to tell GNO/ME about these programs that break GNO/ME's
|
|
rules.
|
|
|
|
\index{auxType}
|
|
We've defined an auxType for S16 and EXE
|
|
files, to allow distinction between programs that are GNO/ME
|
|
compliant and those that are not. Setting the auxType of an
|
|
application to \$DC00 disables the interrupt driven keyboard
|
|
buffering and turns off the GNO/ME cursor. Desktop programs use
|
|
the GNO/ME keyboard I/O via the Event Manager, and thus should \em not \rm
|
|
have their auxType changed.
|
|
|
|
You can change a program's auxType with the
|
|
following shell command:
|
|
|
|
\index{chtyp}
|
|
\begin{verbatim}
|
|
chtyp -a \$DC00 filename
|
|
\end{verbatim}
|
|
|
|
where filename is the name of the
|
|
application. As more programmers become aware of GNO/ME and work
|
|
to make their software compatible with it, this will become less
|
|
of a problem, but for older applications that are unlikely to
|
|
ever change (like the America OnLine software), \$DC00 is a
|
|
reasonable approach.
|
|
|
|
%
|
|
% CHAPTER: Modifications to GS/OS
|
|
%
|
|
|
|
\begin{latexonly}
|
|
\chapter{Modifications to GS/OS}
|
|
\end{latexonly}
|
|
\begin{htmlonly}
|
|
\chapter{Chapter 3: Modifications to GS/OS}
|
|
\end{htmlonly}
|
|
|
|
The GNO system modifies the behavior of a
|
|
number of GS/OS calls in order to allow many programs to execute
|
|
concurrently, and to effect new features. The changes are done in
|
|
such a way that old software can take advantage of these new
|
|
features without modification. Following is a complete
|
|
description of all the changes made. Each section has details in
|
|
text, followed by a list of the specific GS/OS or ToolBox calls
|
|
affected.
|
|
|
|
\section{Mutual Exclusion in GS/OS and ToolBox Calls}
|
|
|
|
The Apple IIGS was not designed as a
|
|
multitasking machine, and GS/OS and the Toolbox reflect this in
|
|
their design. The most notable problem with making multitasking
|
|
work on the Apple IIgs is the use of global (common to all
|
|
processes) information, such as prefixes and direct page space
|
|
for tool sets which includes information like SANE results,
|
|
QuickDraw drawing information, etc. In most cases we've corrected
|
|
these deficiencies by keeping track of such information on a
|
|
per-process basis, that is, each process has its own copy of the
|
|
information and changes to it do not affect any other process'
|
|
information.
|
|
|
|
However, there were many other situations
|
|
where this could not be done. Therefore, there is a limit of one
|
|
process at a time inside either GS/OS or the ToolBox. GNO/ME
|
|
automatically enforces this restriction whenever a tool or GS/OS
|
|
call is made.
|
|
|
|
The method and details of making GS/OS
|
|
calls does not change! The calls listed below have been expanded
|
|
transparently. There are no new parameters and no new parameter
|
|
values. In all cases, the corresponding ProDOS-16 interface calls
|
|
are also supported, except ExpandPath and other calls which do
|
|
not exist in ProDOS-16.
|
|
|
|
\section{Pathnames and Prefixes}
|
|
|
|
Normally under GS/OS there are 32 prefixes,
|
|
and these are all under control of the current application.
|
|
GNO/ME extends this concept to provide each process with it's own
|
|
copies of all prefixes. When a process modifies one of these
|
|
prefixes via the GS/OS SetPrefix call, it modifies only it's own
|
|
copy of that prefix --- the same numbered prefixes of any other
|
|
processes are not modified.
|
|
|
|
Pathname processing has been expanded in
|
|
GNO/ME. There are now two new special pathname operators that are
|
|
accepted by any GS/OS call that takes a pathname parameter:
|
|
|
|
\begin{verbatim}
|
|
. current working directory
|
|
.. parent directory
|
|
\end{verbatim}
|
|
|
|
For example, presume that the current
|
|
working directory (prefix 0) is \tt /foo/bar/moe\rm.
|
|
``\tt./ls\rm'' refers to the file ``\tt/foo/bar/moe/ls\rm'',
|
|
and since a pathname was specified, this overrides the shell's hash table.
|
|
``\tt../ls\rm`` refers to ``\tt/foo/bar/ls\rm''.
|
|
The operators can be combined, also, as in
|
|
``\tt../../ls\rm'' (``\tt/foo/ls\rm''), and
|
|
``\tt./.././ls\rm'' (``\tt/foo/bar/ls\rm'').
|
|
As you can see, the '.' operator is simply
|
|
removed and has no effect other than to force a full expansion of
|
|
the pathname.
|
|
|
|
Shorthand
|
|
\index{device!names}
|
|
device names (.d2, .d5, etc) as are used in the ORCA/Shell
|
|
are available only under System Software 6.0 and later.
|
|
The common pathname operator '\~' (meaning the home
|
|
directory) is handled by the shell; if the character appears in a
|
|
GS/OS call it is not treated specially.
|
|
|
|
\index{ChangePath}
|
|
\index{ClearBackupBit}
|
|
\index{Create}
|
|
\index{Destroy}
|
|
\index{ExpandPath}
|
|
\index{GetFileInfo}
|
|
\index{GetPrefix}
|
|
\index{Open}
|
|
\index{SetFileInfo}
|
|
\index{SetPrefix}
|
|
|
|
\begin{tabular}{ll}
|
|
\$2004 & ChangePath \\
|
|
\$200B & ClearBackupBit \\
|
|
\$2001 & Create \\
|
|
\$2002 & Destroy \\
|
|
\$200E & ExpandPath \\
|
|
\$2006 & GetFileInfo \\
|
|
\$200A & GetPrefix \\
|
|
\$2010 & Open \\
|
|
\$2005 & SetFileInfo \\
|
|
\$2009 & SetPrefix \\
|
|
\end{tabular}
|
|
|
|
|
|
\section{Named Prefixes}
|
|
|
|
In order to allow easy installation and
|
|
configuration of third-party software into all systems, GNO/ME
|
|
provides a feature called named prefixes. These prefixes are
|
|
defined in the
|
|
\index{/etc/namespace}
|
|
/etc/namespace file. Basically, since all UNIX
|
|
systems have /bin, /usr, /etc, and other similar standard
|
|
partitions, but Apple IIgs systems generally do not have these
|
|
partitions, named prefixes provide a way to simulate the UNIX
|
|
directories without forcing GNO/ME users to rename their
|
|
partitions (an arduous and problem-filled task).
|
|
|
|
Named prefixes are handled by the GNO
|
|
kernel in the same GS/OS calls described in Chapter 3 \bf Pathnames
|
|
and Prefixes\rm.
|
|
The format of the /etc/namespace file can be found in the
|
|
\bf namespace\rm(5) manual page.
|
|
|
|
Note that if you have a physical partition that matches the name of a
|
|
logical partition defined in the /etc/namespace file, then the physical
|
|
parition will not be visible while running GNO.
|
|
|
|
\section{Open File Tracking}
|
|
|
|
Previously, a major problem with the way
|
|
GS/OS handled open files was that unrelated programs could affect
|
|
each other's open files. For example, a Desk Accessory (or a
|
|
background program of any sort) could open a file and have it
|
|
closed without it's knowledge by the main application program.
|
|
This presented all kinds of problems for desk accessory authors.
|
|
Apple presented a partial solution with System Software 5.0.4,
|
|
but it wasn't enough for a true multitasking environment. GNO/ME
|
|
keeps track of exactly which process opened which file. It also
|
|
discontinues the concept of a global File Level, opting instead
|
|
for a per-process File Level. Any operations a process performs
|
|
on a file (opening, closing, etc.) do not affect any other
|
|
process' files.
|
|
|
|
In addition to this behavior, when a
|
|
process terminates in any manner all files that it currently has
|
|
opened will be closed automatically. This prevents problems of
|
|
the sort where a program under development terminates abnormally,
|
|
often leaving files open and formerly necessitating a reboot.
|
|
|
|
The Flush GS/OS call is not modified in
|
|
this manner as its effects are basically harmless.
|
|
|
|
\index{Close}
|
|
The Close call accepts a refNum parameter
|
|
of 0 (zero), to close all open files. This works the same way
|
|
under GNO/ME, except of course that only the files of the process
|
|
calling Close are in fact closed.
|
|
|
|
\begin{tabular}{ll}
|
|
\$2010 & Open \\
|
|
\$2014 & Close \\
|
|
\$201B & GetLevel \\
|
|
\$201A & SetLevel \\
|
|
\end{tabular}
|
|
|
|
\section{Quitting Applications}
|
|
|
|
The QUIT and QuitGS calls have been
|
|
modified to support the GNO/ME process scheme. Quitting to
|
|
another application, whether by specifying a pathname or by
|
|
popping the return stack, is accomplished with \bf execve\rm(2).
|
|
When there are no entries on the return stack, the process is
|
|
simply killed. See the \it GS/OS Reference Manual \rm for more
|
|
details on how the Quit stack works.
|
|
|
|
\section{Refnums and File Descriptors}
|
|
|
|
GS/OS tells you about open files in the
|
|
form of refNums (reference numbers). UNIX's term for the same
|
|
concept is ``file descriptor''. From a user's or programmer's view
|
|
of GNO/ME, these terms are identical and will be used as such;
|
|
which one depends on what seems most appropriate in context.
|
|
|
|
For each process, GNO/ME keeps track of
|
|
which files that particular process has opened. No other process
|
|
can directly access a file that another process opened (unless
|
|
programmed explicitly), because it doesn't have access to any
|
|
file descriptors other than its own. This is different from GS/OS
|
|
in that GS/OS allows access to a file even if a program guessed
|
|
the refNum, either deliberately or accidentally. This is one of
|
|
the aspects of process protection in GNO/ME.
|
|
|
|
All of the various I/O mechanisms that
|
|
GNO/ME supports (files, pipes, and TTYs) are handled with the
|
|
same GS/OS calls you are familiar with. When you create a pipe,
|
|
for example, you are returned file descriptors which, because of
|
|
synonymity with refNums, you can use in GS/OS calls. Not all
|
|
GS/OS calls that deal with files are applicable to a particular
|
|
file descriptor; these are detailed in the sections on pipes and
|
|
TTYs.
|
|
|
|
GNO/ME sets no limit on the number of files
|
|
a process may have open at one time. (Most UNIX's have a set
|
|
limit at 32).
|
|
|
|
\section{GNO/ME Character Devices}
|
|
|
|
\index{device!character|(}
|
|
GNO/ME supports a new range of character
|
|
device drivers. These drivers are not installed like normal GS/OS
|
|
drivers, but they are accessed the same way. There are the
|
|
following built-in drivers:
|
|
|
|
\begin{rawhtml}
|
|
<!-- cleantable-start -->
|
|
\end{rawhtml}
|
|
\begin{tabular}{ll}
|
|
\bf .TTYCO \rm &
|
|
\begin{minipage}[t]{8cm}
|
|
% latex2html gets confused here
|
|
\begin{rawhtml}
|
|
</b>
|
|
\end{rawhtml}
|
|
This is the GNO/ME console driver. The driver supports
|
|
the TextTools Pascal control codes, plus a few GNO/ME
|
|
specific ones. These are documented in Chapter 4
|
|
\bf TextTools Replacement\rm. This driver is highly
|
|
optimized both through the GS/OS and TextTools interfaces.
|
|
\end{minipage} \hfill \\
|
|
|
|
\index{.pty}
|
|
\index{.tty}
|
|
\bf .TTYA[0-9,A-F] \rm \\
|
|
\bf .PTYQ[0-9,A-F] \rm &
|
|
\begin{minipage}[t]{8cm}
|
|
Pseudo-terminal devices; PTYs are used for interprocess
|
|
communication and in network activities.
|
|
\end{minipage} \hfill \\
|
|
|
|
\index{.NULL}
|
|
\bf .NULL \rm &
|
|
\begin{minipage}[t]{8cm}
|
|
This driver is a bit bucket. Any data written to it is
|
|
ignored, and any attempt to read from it results in an
|
|
end-of-file error (\$4C).
|
|
\end{minipage} \hfill \\
|
|
\end{tabular}
|
|
\begin{rawhtml}
|
|
<!-- cleantable-end -->
|
|
\end{rawhtml}
|
|
|
|
Just as with GS/OS devices, these GNO/ME
|
|
drivers are accessed with the same
|
|
\index{Open}
|
|
\index{Read}
|
|
\index{Write}
|
|
\index{Close}
|
|
Open, Read, Write, and Close
|
|
calls that are used on files. Unlike GS/OS character devices, the
|
|
characteristics of GNO/ME drivers are controlled through the
|
|
\bf ioctl\rm(2) system call. The GS/OS Device calls (like DInfo, DStatus)
|
|
are not applicable to GNO/ME drivers. See the \bf ioctl\rm(2) and
|
|
\bf tty\rm(4) man pages for details.
|
|
|
|
Some GS/OS calls will return an error when
|
|
given a refNum referring to a GNO/ME character driver or pipe
|
|
because the concepts simply do not apply. The error returned will
|
|
be \$58 (Not a Block Device), and the calls are as follows:
|
|
|
|
\begin{tabular}{ll}
|
|
\$2016 & SetMark \\
|
|
\$2017 & GetMark \\
|
|
\$2018 & SetEOF \\
|
|
\$2019 & GetEOF \\
|
|
\$2015 & Flush \\
|
|
\$201C & GetDirEntry \\
|
|
\end{tabular}
|
|
|
|
GNO/ME loaded drivers (generally for serial
|
|
communications, but other uses are possible) are configured in the
|
|
\index{/etc/tty.config} \bf /etc/tty.config \rm file.
|
|
Each line in \index{/etc/tty.config}
|
|
\bf /etc/tty.config \rm describes one driver. The format of each line is:
|
|
|
|
\begin{verbatim}
|
|
filename slot devname
|
|
\end{verbatim}
|
|
|
|
\bf devname \rm is the name of the device as
|
|
it will be accessed (for example,
|
|
\index{.ttya}
|
|
\bf.ttya\rm). \bf slot \rm is the slot in the
|
|
device table from where the device will be accessed; it may refer
|
|
to one of the physical expansion slots, as TextTools will use the
|
|
specified driver when redirecting output to a slot. The \bf modem \rm
|
|
and \bf printer \rm port drivers are configured for slots 2 and 1,
|
|
respectively.
|
|
|
|
Pseudo-terminals are pre-configured into
|
|
the kernel. PTYs are discussed further in Chapter 6 \it Psuedo-Terminals
|
|
PTYs\rm.
|
|
|
|
Since .ttyco and the pseudo-terminals are
|
|
preconfigured in the GNO kernel, entries for these devices do
|
|
not appear in \index{/etc/tty.config} \bf /etc/tty.config\rm.
|
|
\index{device!character|)}
|
|
|
|
\section{Restartability}
|
|
|
|
GS/OS supports the concept of program
|
|
``restartability''. This allows programs which are written in a
|
|
certain way to remain in memory in a purgeable state so that if
|
|
they are invoked again, and their memory has not been purged,
|
|
they can be restarted without any disk access. This greatly
|
|
increases the speed with which restartable programs can be
|
|
executed.
|
|
|
|
The ORCA environment specifies whether or
|
|
not a program is restartable via a flag character in the SYSCMND
|
|
file. The GS/OS standard method, however, is to set the
|
|
appropriate flags bit in the GS/OS Quit call. This is the method
|
|
that GNO/ME supports. Provided with the GNO/ME standard library
|
|
is a routine \bf rexit\rm(3). \bf rexit\rm (3) only works with
|
|
ORCA/C 2.0. \bf rexit\rm(3) works just like the normal C \bf exit\rm(3)
|
|
call but it sets the restart flag when calling QuitGS.
|
|
|
|
The standard ORCA/C 1.3 libraries are not
|
|
restartable, but the ORCA/C 2.0 libraries are.
|
|
|
|
\section{Miscellaneous}
|
|
|
|
The following miscellaneous GS/OS calls have also been modified for GNO/ME:
|
|
|
|
\begin{rawhtml}
|
|
<!-- cleantable-start -->
|
|
\end{rawhtml}
|
|
\begin{tabular}{ll}
|
|
\$2027 GetName &
|
|
\begin{minipage}[t]{8cm}
|
|
\begin{rawhtml}
|
|
</b>
|
|
\end{rawhtml}
|
|
Returns the name on disk of the process. This only
|
|
returns valid information after an \bf execve\rm(2).
|
|
\end{minipage} \hfill \\
|
|
|
|
\$2003 OSShutdown &
|
|
\begin{minipage}[t]{8cm}
|
|
This call has been modified to kill all processes before
|
|
performing the actual shutdown operation.
|
|
\end{minipage} \hfill \\
|
|
\end{tabular}
|
|
\begin{rawhtml}
|
|
<!-- cleantable-end -->
|
|
\end{rawhtml}
|
|
|
|
|
|
%
|
|
% CHAPTER: Modifications to the Toolbox
|
|
%
|
|
|
|
\begin{latexonly}
|
|
\chapter{Modifications to the ToolBox}
|
|
\end{latexonly}
|
|
\begin{htmlonly}
|
|
\chapter{Chapter 4: Modifications to the ToolBox}
|
|
\end{htmlonly}
|
|
|
|
Several changes have been made to the
|
|
ToolBox, the most major of which is the replacement of the entire
|
|
TextTools tool set. The TextTools were replaced for a number of
|
|
reasons --- better control over text I/O, increased speed, and
|
|
emulation of ORCA's redirection system with as little overhead as
|
|
possible. Other changes were made to modify the behavior of some
|
|
tool calls to be more consistent with the idea of a multitasking
|
|
environment.
|
|
|
|
\section{TextTools Replacement}
|
|
|
|
The changes to the TextTools have turned it
|
|
into a much more powerful general I/O manager. The TextTools now
|
|
intrinsically handle pipes and redirection, and you can install
|
|
custom drivers for TextTools to use. Also, the TextTools have had
|
|
their old slot-dependence removed; the parameter that used to
|
|
refer to 'slot' in the original texttools calls now refers to a
|
|
driver number. A summary of driver numbers (including those that
|
|
come pre-installed into GNO) are as follows:
|
|
|
|
\index{device!driver}
|
|
\begin{tabular}{ll}
|
|
\bf{0} & null device driver \\
|
|
\bf{1} & serial driver (for printer port compatibility) \\
|
|
\bf{2} & serial driver (for modem port compatibility) \\
|
|
\bf{3} & console driver (Pascal-compatible 80-column text screen) \\
|
|
\bf{4--5} & user installed \\
|
|
\end{tabular}
|
|
|
|
See Chapter 3 \bf GNO/ME Character Devices\rm,
|
|
for information on configuring these drivers.
|
|
|
|
There are also new device types in the
|
|
TextTools; the complete list of supported device types and what
|
|
their slotNum's (from SetInputDevice, SetOutputDevice, etc) mean
|
|
is as follows:
|
|
|
|
\index{device!types|(}
|
|
|
|
\begin{rawhtml}
|
|
<!-- cleantable-start -->
|
|
\end{rawhtml}
|
|
|
|
\begin{tabular}{rll}
|
|
\begin{minipage}[t]{1cm}
|
|
\sloppy
|
|
\bf Type \rm
|
|
\end{minipage} \hfill &
|
|
\begin{minipage}[t]{5cm}
|
|
\sloppy
|
|
\begin{center}
|
|
\bf Use \rm
|
|
\end{center}
|
|
\end{minipage} \hfill &
|
|
\begin{minipage}[t]{5cm}
|
|
\sloppy
|
|
\bf slotNum \rm
|
|
\end{minipage} \hfill \\ \cline{1-3}
|
|
|
|
|
|
\begin{minipage}[b]{1cm}
|
|
\sloppy
|
|
\bf 0 \rm
|
|
\end{minipage} \hfill &
|
|
\begin{minipage}[t]{5cm}
|
|
\sloppy
|
|
Used to be \index{BASIC} BASIC text drivers. These
|
|
are no longer supported under GNO/ME, and setting I/O to
|
|
a BASIC driver actually selects a Pascal driver.
|
|
\end{minipage} \hfill &
|
|
\begin{minipage}[t]{5cm}
|
|
\sloppy
|
|
Not applicable.
|
|
\end{minipage} \hfill \\
|
|
|
|
|
|
\begin{minipage}[b]{1cm}
|
|
\sloppy
|
|
\bf 1 \rm
|
|
\end{minipage} \hfill &
|
|
\begin{minipage}[t]{5cm}
|
|
\sloppy
|
|
Pascal text driver. This is one of the drivers specified in
|
|
\index{/etc/ttys} /etc/ttys or built-in to GNO/ME.
|
|
\end{minipage} \hfill &
|
|
\begin{minipage}[t]{5cm}
|
|
\sloppy
|
|
Driver number as listed above.
|
|
\end{minipage} \hfill \\
|
|
|
|
|
|
\begin{minipage}[b]{1cm}
|
|
\sloppy
|
|
\bf 2 \rm
|
|
\end{minipage} \hfill &
|
|
\begin{minipage}[t]{5cm}
|
|
\sloppy
|
|
RAM-based Driver (documented in \it ToolBox Reference Volume 2\rm)
|
|
\end{minipage} \hfill &
|
|
\begin{minipage}[t]{5cm}
|
|
\sloppy
|
|
Pointer to the RAM-based driver's jump table.
|
|
\end{minipage} \hfill \\
|
|
|
|
|
|
\begin{minipage}[b]{1cm}
|
|
\sloppy
|
|
\bf 3 \rm
|
|
\end{minipage} \hfill &
|
|
\begin{minipage}[t]{5cm}
|
|
File redirection
|
|
\end{minipage} \hfill &
|
|
\begin{minipage}[t]{5cm}
|
|
refNum (file descriptor) of the file to access through TextTools.
|
|
\end{minipage} \hfill \\
|
|
\end{tabular}
|
|
\begin{rawhtml}
|
|
<!-- cleantable-end -->
|
|
\end{rawhtml}
|
|
|
|
% This is an attempt to do without the kludge below. Just comment it
|
|
% out for now
|
|
\begin{comment}
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%
|
|
% This is a really annoying kludge-fuck.
|
|
%
|
|
% latex2html doesn't currently seem to handle \parbox correctly.
|
|
% On the other hand, using \begin{verbatim} mode makes this table
|
|
% look ugly in postscript. Piece of crap.
|
|
%
|
|
% So instead we resort to duplicating this information. Be careful
|
|
% to update both versions, please.
|
|
%
|
|
|
|
\begin{latexonly}
|
|
\begin{tabular}{rll}
|
|
\parbox[b]{1cm}{
|
|
\sloppy
|
|
\bf Device Type \rm
|
|
} &
|
|
\parbox[t]{5cm}{
|
|
\sloppy
|
|
\bf Use \rm
|
|
} &
|
|
\parbox[t]{5cm}{
|
|
\sloppy
|
|
\bf slotNum \rm
|
|
} \\ \cline{1-3}
|
|
|
|
\parbox[t]{1cm}{
|
|
\sloppy
|
|
\bf 0 \rm
|
|
} &
|
|
\parbox[t]{5cm}{
|
|
\sloppy
|
|
Used to be BASIC text drivers. These
|
|
are no longer supported under GNO/ME, and set-\\ting I/O to
|
|
a BASIC driver actually selects a Pascal driver.
|
|
} &
|
|
\parbox[t]{5cm}{
|
|
\sloppy
|
|
Not applicable.
|
|
} \\
|
|
|
|
\parbox[t]{1cm}{
|
|
\sloppy
|
|
\bf 1 \rm
|
|
} &
|
|
\parbox[t]{5cm}{
|
|
\sloppy
|
|
Pascal text driver. This is one of
|
|
the drivers specified in /etc/ttys or built-in to GNO/ME.
|
|
} &
|
|
\parbox[t]{5cm}{
|
|
\sloppy
|
|
Driver number as listed above.
|
|
} \\
|
|
|
|
|
|
\parbox[t]{1cm}{
|
|
\sloppy
|
|
\bf 2 \rm
|
|
} &
|
|
\parbox[t]{5cm}{
|
|
\sloppy
|
|
RAM-based Driver (documented in \it ToolBox Reference Volume 2\rm)
|
|
} &
|
|
\parbox[t]{5cm}{
|
|
\sloppy
|
|
Pointer to the RAM-\\based driver's jump table.
|
|
} \\
|
|
|
|
|
|
\parbox[t]{1cm}{
|
|
\sloppy
|
|
\bf 3 \rm
|
|
} &
|
|
\parbox[t]{5cm}{
|
|
\sloppy
|
|
File redirection
|
|
} &
|
|
\parbox[t]{5cm}{
|
|
\sloppy
|
|
refNum (file descriptor) of the file to access through TextTools.
|
|
} \\
|
|
\end{tabular}
|
|
\end{latexonly}
|
|
|
|
%
|
|
% This is the html version. The tables look strange because of the
|
|
% formatting commands. They actually line up if those commands are
|
|
% removed.
|
|
%
|
|
|
|
\begin{htmlonly}
|
|
\begin{rawhtml}
|
|
<pre>
|
|
<b>Device
|
|
Type Use slotNum
|
|
-------------------------------------------------------------------</b>
|
|
<b>0</b> Used to be BASIC text drivers. These Not Applicable
|
|
are no longer supported under GNO/ME,
|
|
and setting I/O to a BASIC driver
|
|
actually selects a Pascal driver.
|
|
|
|
<b>1</b> Pascal text driver. This is one of Driver number as
|
|
the drivers specified in /etc/ttys listed above.
|
|
or built-in to GNO/ME.
|
|
|
|
<b>2</b> RAM-based Driver (documented in Pointer to the RAM-
|
|
<em>ToolBox Reference Volume 2</em>. based driver's jump
|
|
table.
|
|
|
|
<b>3</b> File redirection. refNum (file desc-
|
|
riptor) of the file
|
|
to access through
|
|
TextTools.
|
|
</pre>
|
|
\end{rawhtml}
|
|
\end{htmlonly}
|
|
%
|
|
% kludge-fuck ends
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\end{comment}
|
|
|
|
\index{device!types|)}
|
|
\index{driver!console}
|
|
|
|
The new console driver supports all the
|
|
features of the old 80-column Pascal firmware, and adds a few
|
|
extensions, with one exception --- the codes that switched between
|
|
40 and 80 columns modes are not supported. It is not compatible
|
|
with the GS/OS
|
|
\index{.CONSOLE}
|
|
``.console'' driver. The control codes supported are as follows:
|
|
|
|
\index{\^{}C}
|
|
\index{\^{}Z}
|
|
\begin{tabular}{lll}
|
|
Hex & ASCII & Action \\ \cline{1-3}
|
|
01 & CTRL-A & Set cursor to flashing block \\
|
|
02 & CTRL-B & Set cursor to flashing underscore \\
|
|
03 & CTRL-C & Begin ``Set Text Window'' sequence \\
|
|
05 & CTRL-E & Cursor on \\
|
|
06 & CTRL-F & Cursor off \\
|
|
07 & CTRL-G & Perform FlexBeep \\
|
|
08 & CTRL-H & Move left one character \\
|
|
09 & CTRL-I & Tab \\
|
|
0A & CTRL-J & Move down a line \\
|
|
0B & CTRL-K & Clear to EOP (end of screen) \\
|
|
0C & CTRL-L & Clear screen, home cursor \\
|
|
0D & CTRL-M & Move cursor to left edge of line \\
|
|
0E & CTRL-N & Normal text \\
|
|
0F & CTRL-O & Inverse text \\
|
|
11 & CTRL-Q & Insert a blank line at the current cursor position \\
|
|
12 & CTRL-R & Delete the line at the current cursor position. \\
|
|
15 & CTRL-U & Move cursor right one character \\
|
|
16 & CTRL-V & Scroll display down one line \\
|
|
17 & CTRL-W & Scroll display up one line \\
|
|
18 & CTRL-X & Normal text, mousetext off \\
|
|
19 & CTRL-Y & Home cursor \\
|
|
1A & CTRL-Z & Clear entire line \\
|
|
1B & CTRL-[ & MouseText on \\
|
|
% This is a CTRL-\
|
|
1C & CTRL-\symbol{92} & Move cursor one character to the right \\
|
|
1D & CTRL-] & Clear to end of line \\
|
|
1E & CTRL-\^{} & Goto XY \\
|
|
1F & CTRL-\_{} & Move up one line \\
|
|
\end{tabular}
|
|
|
|
|
|
(\bf Note\rm: the \it Apple IIgs Firmware Reference \rm
|
|
incorrectly has codes 05 and 06 reversed. The codes listed here
|
|
are correct for both GNO/ME and the Apple IIgs 80-column
|
|
firmware.)
|
|
|
|
FlexBeep is a custom beep routine that
|
|
doesn't turn off interrupts for the duration of the noise as does
|
|
the default Apple IIgs beep. This means that the beep could sound
|
|
funny from time to time, but it allows other processes to keep
|
|
running. We also added two control codes to control what kind of
|
|
cursor is used. There are two types available as in most
|
|
text-based software; they are underscore for 'insert' mode, and
|
|
block for 'overstrike'. You may, of course, use whichever cursor
|
|
you like. For example, a communications program won't have need
|
|
of insert mode, so it can leave the choice up to the user.
|
|
|
|
|
|
|
|
The Set Text Window sequence (begun by a \$03 code) works as follows:
|
|
|
|
\begin{verbatim}
|
|
CTRL-C '[' LEFT RIGHT TOP BOTTOM
|
|
\end{verbatim}
|
|
|
|
CTRL-C is of course hex \$03, and '[' is the
|
|
open bracket character (\$5B). TOP, BOTTOM, LEFT, and RIGHT are
|
|
single-byte ASCII values that represent the margin settings.
|
|
Values for TOP and BOTTOM range from 0 to 23; LEFT and RIGHT
|
|
range from 0 to 79. TOP must be numerically less than BOTTOM;
|
|
LEFT must be less than RIGHT. Any impossible settings are
|
|
ignored, and defaults are used instead. The extra '[' in the
|
|
sequence helps prevent the screen from becoming confused in the
|
|
event that random data is printed to the screen.
|
|
|
|
After a successful Set Text Window
|
|
sequence, only the portion of the screen inside the 'window' will
|
|
be accessible, and only the window will scroll; any text outside
|
|
the window is not affected.
|
|
|
|
The cursor blinks at a rate defined by the
|
|
\index{control panel}
|
|
\bf Control Panel/Options/Cursor Flash \rm setting. Far left is no blinking
|
|
(solid), and far right is extremely fast blinking.
|
|
|
|
\tt ReadLine \rm (\$240C) now sports a complete line editor unlike the old
|
|
TextTools version. Following is a list of the editor commands.
|
|
|
|
\begin{tabular}{ll}
|
|
\index{\^{}D}
|
|
EOL & Terminates input (EOL is a parameter to the \_{}ReadLine call). \\
|
|
LEFT-ARROW & Move cursor to the left. \\
|
|
RIGHT-ARROW & Move cursor to right. It won't go past rightmost character. \\
|
|
DELETE & Delete the character to the left of the cursor. \\
|
|
CTRL-D & Delete character under the cursor. \\
|
|
OA-D & Delete character under the cursor. \\
|
|
OA-E & Toggles between overwrite and insert mode. \\
|
|
\end{tabular}
|
|
|
|
|
|
\tt ReadChar \rm (\$220C) has also been changed. The character returned may now
|
|
contain the key modification flags (\$C025) in the upper byte and
|
|
the character typed in the lower byte. This is still compatible
|
|
with the old TextTools ReadChar. To get the keyMod flags, call
|
|
\tt SetInGlobals \rm (\$090C) and
|
|
set the upper byte of the AND mask to \$FF. Typical parameters for
|
|
\tt SetInGlobals \rm to get this information are:
|
|
\index{ANDmask}
|
|
ANDmask\ =\ \$FF7F, ORmask\ =\ \$0000.
|
|
|
|
|
|
The default I/O masks have also been
|
|
changed. They are now
|
|
\index{ANDmask}
|
|
ANDmask\ =\ \$00FF, ORmask\ =\ \$0000. They are
|
|
set this way to extend the range of data that can be sent through
|
|
TextTools. GNO/ME Character drivers do not, like the previous
|
|
TextTools driver, require the hi-bit to be set.
|
|
|
|
The new TextTools are completely reentrant.
|
|
This means that any number of processes may be executing
|
|
TextTools calls at the same time, increasing system performance
|
|
somewhat. The TextTools are also the only toolset which is not
|
|
mutexed.
|
|
|
|
\index{driver!console}
|
|
The GNO/ME console driver also supports
|
|
flow-control in the form of Control-S and Control-Q. Control-S is
|
|
used to stop screen output, and Control-Q is used to resume
|
|
screen output.
|
|
|
|
\section{SysFailMgr}
|
|
|
|
|
|
The MiscTool call SysFailMgr (\$1503) has been
|
|
modified so that a process calling it is simply killed, instead
|
|
of causing system operation to stop. This was done because many
|
|
programs use SysFailMgr when a simple error message would have
|
|
sufficed. There are, however, some tool and GS/OS errors which
|
|
are truly system failure messages, and these do cause system
|
|
operation to stop. These errors are as follows:
|
|
|
|
\begin{tabular}{ll}
|
|
\$0305 & Damaged heartbeat queue detected. \\
|
|
\$0308 & Damaged heartbeat queue detected. \\
|
|
\$0681 & Event queue damaged. \\
|
|
\$0682 & Queue handle damaged. \\
|
|
\$08FF & Unclaimed sound interrupt. \\
|
|
\end{tabular}
|
|
|
|
What the system does after displaying the
|
|
message is the same as for a system panic.
|
|
|
|
|
|
\section{The Resource Manager}
|
|
|
|
The Resource Manager has been modified in
|
|
some subtle ways. First, GNO/ME makes sure that the
|
|
CurResourceApp value is always correct before a process makes a
|
|
Resource Manager call. Second, all open resource files are the
|
|
property of the Kernel. When a GetOpenFileRefnum call is made, a
|
|
new refnum is \bf dup\rm(2)'d to allow the process to access the
|
|
file. Having the Kernel control resource files also allows all
|
|
processes to share SYS.RESOURCES without requiring each process
|
|
to explicitly open it.
|
|
|
|
\section{The Event Manager}
|
|
|
|
|
|
GNO/ME starts up the Event Manager so it is
|
|
always available to the kernel and shell utilities. Changes were
|
|
made so that the Event Manager obtains keystrokes from the GNO/ME
|
|
\index{driver!console}
|
|
console driver (.ttyco). This allows UNIX-style utilities and
|
|
desktop applications to share the keyboard in a cooperative
|
|
manner. This also makes it possible to suspend desktop
|
|
applications; see Chapter 7, \bf Suspend NDA\rm.
|
|
|
|
EMStartUp sets the GNO console driver to
|
|
RAW mode via an \bf ioctl\rm(2) call, to allow the Event Manager
|
|
to get single keystrokes at a time, and to prevent users from
|
|
being able to kill the desktop application with \^C or other
|
|
interrupt characters. The four ``GetEvent'' routines,
|
|
GetNextEvent, GetOSEvent, EventAvail, and OSEventAvail now poll
|
|
the console for input characters instead of using an interrupt
|
|
handler.
|
|
|
|
\section{The Control Panel}
|
|
|
|
\index{CDA}
|
|
\index{control panel}
|
|
In most cases, the CDA menu is executed as
|
|
an interrupt handler. Since the Apple IIgs interrupt handler
|
|
firmware isn't reentrant, task switching is not allowed to occur
|
|
while the control panel is active. This basically means that all
|
|
processes grind to a halt. In many ways, however, this is not
|
|
undesirable. It definitely eases debugging, since a static system
|
|
is much easier to deal with than a dynamic system. Also, CDAs
|
|
assume they have full control of the text screen; multitasking
|
|
CDAs would confuse and be confused in terms of output.
|
|
|
|
During the execution of the Control Panel,
|
|
the original non-GNO/ME TextTools tool is reinstalled to prevent
|
|
compatibility problems. Another step, taken to maintain user
|
|
sanity, makes CDAs run under the kernel's process ID.
|
|
|
|
All the changes were made to two tool
|
|
calls: \tt SaveAll \rm (\$0B05) and \tt RestAll \rm (\$0C05).
|
|
|
|
\section{QDStartup}
|
|
|
|
The \tt QDStartup \rm (\$0204)
|
|
call has been modified to signal an error and
|
|
terminate any process that tries to make the call when it's
|
|
\index{controlling terminal}
|
|
controlling terminal is not the Apple IIgs console. This prevents
|
|
a user on a remote terminal from bringing up a desktop
|
|
application on the console, an operation he could not escape from
|
|
and one that would greatly annoy the user at the console.
|
|
|
|
Another change ensures that an attempt to
|
|
execute two graphics-based applications concurrently will fail;
|
|
the second process that tries to call
|
|
\tt QDStartUp \rm is killed and a diagnostic message is displayed
|
|
on the screen.
|
|
|
|
%
|
|
% CHAPTER: Process Management
|
|
%
|
|
|
|
\begin{latexonly}
|
|
\chapter{Process Management}
|
|
\end{latexonly}
|
|
\begin{htmlonly}
|
|
\chapter{Chapter 5: Process Management}
|
|
\end{htmlonly}
|
|
|
|
Before discussing process management using
|
|
Kernel calls, it would be wise to define just exactly what we
|
|
refer to when we say \it process\rm. A process is generally
|
|
considered to be a program in execution. ``A program is a
|
|
passive entity, while a process is an active entity.''
|
|
(Operating Systems Concepts p.73, Silberschatz and Peterson,
|
|
Addison-Wesley, 1989). The concept of process includes the
|
|
information a computer needs to execute a program (such as the
|
|
program counter, register values, etc).
|
|
|
|
In order to execute multiple processes, the
|
|
operating system (GNO/ME and GS/OS in this case) has to make
|
|
decisions about which process to run and when. GNO/ME supports
|
|
what is termed \it preemptive multitasking\rm, which means that
|
|
processes are interrupted after a certain amount of time (their
|
|
time slice), at which point another process is allowed to run.
|
|
The changing of machine registers to make the processor execute a
|
|
different process is called a \index{context switch}
|
|
\it context switch\rm, and the
|
|
information the operating system needs to do this is called its
|
|
\it context\rm.
|
|
The GNO kernel maintains a list of all active processes, and
|
|
assigns time slices to each process according to their order in
|
|
the list. When the kernel has run through all the processes, it
|
|
starts again at the beginning of the list. This is called \it round-robin
|
|
scheduling\rm. Under certain circumstances, a process can
|
|
actually execute longer than its allotted time slice because task
|
|
switches are not allowed during a GS/OS or ToolBox call. In these
|
|
cases, as soon as the system call is finished the process is
|
|
interrupted.
|
|
|
|
Processes can give up the rest of their
|
|
time slice voluntarily (but not necessarily explicitly) in a
|
|
number of ways, terminal input being the most common. In this
|
|
case, the rest of the time slice is allocated to the next process
|
|
in line (to help smooth out scheduling). A process waiting on
|
|
some event to happen is termed \index{blocked processes} \it blocked\rm.
|
|
There are many ways this can happen, and each will be mentioned in its place.
|
|
|
|
An important item to remember is the \it process
|
|
ID\rm. This is a number which uniquely identifies a process. The
|
|
ID is assigned when the process is created, and is made available
|
|
for reassignment when the process terminates. A great many system
|
|
calls require process IDs as input. Do not confuse this with a
|
|
userID, which is a system for keeping track of memory allocation
|
|
by various parts of the system, and is handled (pardon the pun)
|
|
by the Memory Manager tool set. Also, do not confuse Memory
|
|
Manager userID's with Unix user ID's --- numbers which are assigned
|
|
to the various human users of a multiuser machine.
|
|
|
|
There are two methods for creating new
|
|
processes: the system call \bf fork\rm(2)
|
|
(or \bf fork2\rm(2))
|
|
and the library routine \bf exec\rm(3)
|
|
(specifics for calling these functions and others is in Appendix
|
|
A \it Making System Calls\rm). \bf fork \rm starts up a process
|
|
which begins execution at an address you specify. \bf exec \rm
|
|
starts up a process by loading an executable file (S16 or EXE). \bf fork \rm
|
|
is used mainly for use inside a specific application, such as
|
|
running shell built-ins in the \index{background} background, or setting up
|
|
independent entities inside a program. Forked processes have some
|
|
limitations, due to the hardware design of the Apple IIgs. The
|
|
parent process (the process which called fork) must still exist
|
|
when the
|
|
\index{process!child|(}
|
|
children die, either via \bf kill \rm or by simply
|
|
exiting. This is because the forked children share the same
|
|
memory space as the parent; the memory the children execute from
|
|
is tagged with the parent's userID. If the parent terminated
|
|
before the children, the children's code would be deallocated and
|
|
likely overwritten. A second caveat with \bf fork \rm is the
|
|
difference between it's UNIX counterpart. UNIX \bf fork \rm
|
|
begins executing the child at a point directly after the call to \bf fork\rm.
|
|
This cannot be accomplished on the Apple IIgs because virtual
|
|
memory is required for such an operation; thus the need to
|
|
specify a \bf fork \rm child as a C function. Note that an
|
|
appropriately written
|
|
\index{assembly language programs}
|
|
assembly language program need not
|
|
necessarily have these restrictions. When a process is forked,
|
|
the child process is given it's own direct page and stack space
|
|
under a newly allocated userID, so that when the child terminates
|
|
this memory is automatically freed.
|
|
|
|
\bf exec\rm(3) is used when the process you
|
|
wish to start is a GS/OS load file (file type S16 and EXE). \bf exec \rm
|
|
follows the procedure outlined in the \it GS/OS Reference Manual \rm
|
|
for executing a program, and sets up the new program's
|
|
environment as it expects. After \bf exec \rm has loaded the
|
|
program and set up it's environment, the new process is started
|
|
and \bf exec \rm returns immediately.
|
|
|
|
Both \bf fork\rm(2) and \bf exec\rm(3) return
|
|
the process ID of the child. The parent may use this process ID
|
|
to send \it signals \rm to the child, or simply wait for the child
|
|
to exit with the \bf wait\rm(2) system call; indeed, this is the
|
|
most common use. Whenever a child process terminates or is
|
|
stopped (See Chapter 6 \it Interprocess Communication\rm),
|
|
the kernel creates a
|
|
packet of information which is then made available to the
|
|
process' parent. If the parent is currently inside a wait call,
|
|
the call returns with the information. If the parent is off doing
|
|
something else, the kernel sends the parent process a
|
|
\tt SIGCHLD \rm signal. The default is to ignore \tt SIGCHLD\rm,
|
|
but a common technique is to install a handler for \tt SIGCHLD\rm,
|
|
and to make a \bf wait \rm call inside the handler to retrieve
|
|
the relevant information.
|
|
|
|
\bf exec\rm(3) is actually implemented as
|
|
two other system calls: \bf fork\rm(2), and one called \bf execve\rm(2).
|
|
\bf execve \rm loads a program from an executable file, and
|
|
begins executing it. The current process' memory is deallocated.
|
|
The shell uses a \bf fork\rm/\bf execve \rm pair explicitly,
|
|
so it can set up redirection and handle job control.
|
|
|
|
\index{process!child|)}
|
|
|
|
\section{Process Table}
|
|
|
|
Information about processes is maintained
|
|
in the process table, which contains one entry for each possible
|
|
process (\bf NPROC\rm, defined in the C header file \tt <gno/conf.h>\rm.
|
|
There is other per-process information spread about the kernel, but
|
|
those are usually used for maintaining compatibility with older
|
|
software, and thus are not described here. Please note that the
|
|
data in this section is informational only (e.g. for programs
|
|
like \bf ps\rm(1)). Do not attempt to modify kernel data
|
|
structures or the GNO Kernel will likely respond with a
|
|
resounding crash. Only 'interesting' fields are documented.
|
|
|
|
Copies of process entries should be
|
|
obtained by using the Kernel Virtual Memory (KVM) routines
|
|
(\bf kvm\_{}open\rm(2), and so forth).
|
|
These are documented in the electronic manual pages.
|
|
|
|
\begin{description}
|
|
|
|
\item[processState]
|
|
Processes have a
|
|
state associate with them. The state of the process is a
|
|
description of what the process is doing. The possible process
|
|
states (as listed in
|
|
\tt <gno/proc.h> \rm
|
|
and described here) are:
|
|
|
|
\begin{rawhtml}
|
|
<!-- cleantable-start -->
|
|
\end{rawhtml}
|
|
|
|
\begin{tabular}{ll}
|
|
|
|
RUNNING &
|
|
\begin{minipage}[t]{8cm}
|
|
The process is currently in execution.
|
|
\end{minipage} \hfill \\
|
|
|
|
READY &
|
|
\begin{minipage}[t]{8cm}
|
|
The process is not currently executing, but is ready to be
|
|
executed as soon as it is assigned a time slice.
|
|
\end{minipage} \hfill \\
|
|
|
|
BLOCKED &
|
|
\begin{minipage}[t]{8cm}
|
|
\index{blocked processes}
|
|
The process is waiting for a slow I/O operation to
|
|
complete (for instance, a read from a TTY).
|
|
\end{minipage} \hfill \\
|
|
|
|
NEW &
|
|
\begin{minipage}[t]{8cm}
|
|
The process has been created, but has not executed yet.
|
|
\end{minipage} \hfill \\
|
|
|
|
SUSPENDED &
|
|
\begin{minipage}[t]{8cm}
|
|
The process was stopped with SIGSTOP, SIGTSTP,
|
|
SIGTTIN, or SIGTTOU.
|
|
\end{minipage} \hfill \\
|
|
|
|
WAITING &
|
|
\begin{minipage}[t]{8cm}
|
|
The process is waiting on a semaphore ``signal'' operation.
|
|
Programs waiting for data from a pipe have this state.
|
|
\end{minipage} \hfill \\
|
|
|
|
WAITSIGCH &
|
|
\begin{minipage}[t]{8cm}
|
|
The process is waiting to receive a SIGCHLD signal.
|
|
\end{minipage} \hfill \\
|
|
|
|
PAUSED &
|
|
\begin{minipage}[t]{8cm}
|
|
The process is waiting for any signal.
|
|
\end{minipage} \hfill \\
|
|
|
|
\end{tabular}
|
|
|
|
\begin{rawhtml}
|
|
<!-- cleantable-end -->
|
|
\end{rawhtml}
|
|
|
|
|
|
\item[ttyID]
|
|
\index{device!number}
|
|
\index{device!names}
|
|
The device number of the
|
|
\index{controlling terminal}
|
|
controlling TTY for this process.
|
|
This is not a GS/OS refnum; rather, it is an index into the kernel's internal
|
|
character device table.
|
|
The value of this field can be interpreted as follows:
|
|
|
|
\index{.pty}
|
|
\index{.tty}
|
|
\index{.ttya}
|
|
\index{.ttyb}
|
|
\begin{tabular}{rl}
|
|
\bf{0} & .null \\
|
|
\bf{1} & .ttya \\
|
|
\bf{2} & .ttyb \\
|
|
\bf{3} & .ttyco \\
|
|
\bf{6} & .ptyq0 pty0 master side \\
|
|
\bf{7} & .ttyq0 pty0 slave side \\
|
|
\end{tabular}
|
|
|
|
Other values may be appropriate depending
|
|
on the
|
|
\index{/etc/tty.config}
|
|
\tt /etc/tty.config \rm file. Namely, \bf 1 \rm and \bf 2 \rm
|
|
(by default the modem and printer port drivers), and \bf 4 \rm and
|
|
\bf 5 \rm (unassigned by default) may be assigned to different devices.
|
|
|
|
|
|
\item[ticks]
|
|
The number of full ticks this process has executed. If a process gives up
|
|
it's time slice due to an I/O operation, this value is not incremented.
|
|
A tick is 1/60 second.
|
|
|
|
\item[alarmCount]
|
|
\index{alarmCount}
|
|
If an
|
|
\index{alarm}
|
|
\bf alarm\rm(2) request was made, this is the number of seconds
|
|
remaining until the process is sent SIGALRM.
|
|
|
|
\item[openFiles]
|
|
This is a structure which stores information about the files a
|
|
process has open. See \tt struct ftable \rm and \tt struct fdentry \rm
|
|
in \tt <gno/proc.h> \rm.
|
|
|
|
\item[irq\_{}A, irq\_{}X, irq\_{}Y, irq\_{}S, irq\_{}D, irq\_{}B,
|
|
irq\_{}P, irq\_{}state, irq\_{}PC, irq\_{}K]
|
|
\index{context switch}
|
|
Context information for the process. These fields are the values of the
|
|
\index{65816 registers}
|
|
65816 registers
|
|
at the last context switch. They only truly represent the
|
|
machine state of the process if the process is not RUNNING.
|
|
|
|
\item[args]
|
|
\index{args}
|
|
This is a NULL-terminated (C-style) string that contains the command line
|
|
with which the process was invoked. This string begins with
|
|
\index{BYTEWRKS}
|
|
``BYTEWRKS'', the shell identifier.
|
|
|
|
\end{description}
|
|
|
|
For more details and an example of how to
|
|
investigate process information, look at the source code for the
|
|
\index{CDA}
|
|
``GNO Snooper CDA''.
|
|
|
|
\section{Task Switching}
|
|
|
|
\index{context switch|(}
|
|
|
|
As mentioned earlier, user code can often
|
|
unwittingly initiate a context switch by reading from the console
|
|
(and other miscellaneous things). There are a few situations
|
|
where this can cause a problem, namely inside interrupt handlers.
|
|
While the kernel makes an attempt to prevent this, it cannot
|
|
predict every conceivable problem. The kernel attempts to detect
|
|
and prevent context switches inside interrupt handlers by
|
|
checking for the following situations.
|
|
|
|
\begin{itemize}
|
|
\item Is the system busy flag non-zero? (The busy flag is located at
|
|
address \tt \$E100FF\rm.)
|
|
|
|
\item Is the ``No-Compact'' flag set? (Located at \tt\$E100CB\rm.)
|
|
|
|
\item Does the stack pointer point to anything in thr range
|
|
\tt \$0100-\$01FF\rm?
|
|
|
|
\item Is the interrupt bit in the processor status register set?
|
|
\end{itemize}
|
|
|
|
If any of these conditions are met, a
|
|
context switch will not take place. This can cause problems in
|
|
certain circumstances. The basic rule is to avoid making Kernel
|
|
calls that might cause a context switch or change in process
|
|
state from inside an interrupt handler. This includes the
|
|
following:
|
|
|
|
\begin{itemize}
|
|
\item reading from the console
|
|
\item accessing a pipe
|
|
\item any of the following kernel traps:
|
|
\bf \_{}execve\rm(2) (or other calls in the \bf exec \rm family),
|
|
\bf fork\rm(2),
|
|
\bf fork2\rm(2),
|
|
\bf kill\rm(2),
|
|
\bf pause\rm(2),
|
|
\bf procreceive\rm(2),
|
|
\bf sigpause\rm(2),
|
|
or
|
|
\bf wait\rm(2).
|
|
\end{itemize}
|
|
|
|
Calls such as \bf procsend\rm(2), however, may be used from inside
|
|
an interrupt handler, and in fact are very useful in such situations.
|
|
|
|
\index{context switch|)}
|
|
|
|
\section{Job Control}
|
|
|
|
Job control is a feature of the kernel that
|
|
helps processes orderly share a terminal. It prevents such
|
|
quandaries as ``What happens when two processes try to read
|
|
from the terminal at the same time?''.
|
|
|
|
Job control works by assigning related
|
|
processes to a \it process group\rm. For example, all of the
|
|
processes in a pipeline belong to one process group. Terminal
|
|
\index{device!driver}
|
|
device drivers also belong to process groups, and when the
|
|
process group of a job does not match that of its
|
|
\index{controlling terminal}
|
|
\it controlling terminal \rm
|
|
the job is said to be in the \index{background} background.
|
|
Background jobs have access to their controlling terminal restricted in
|
|
certain ways.
|
|
|
|
\begin{itemize}
|
|
\item If a background job attempts to read from the terminal, the
|
|
kernel suspends the process by sending the \tt SIGTTIN \rm signal.
|
|
|
|
\item The interrupt signals \tt SIGTSTP \rm and \tt SIGINT\rm,
|
|
generated by \^Z and \^C respectively, are sent only to the
|
|
foregound job. This allows backgrounded jobs to proceed without
|
|
interruption.
|
|
|
|
\item Certain \bf ioctl\rm(2) calls cannot be made by a background job;
|
|
the result is a \tt SIGTTIN \rm signal.
|
|
\end{itemize}
|
|
|
|
Job control is accessed by software through the \bf tcnewpgrp\rm,
|
|
\bf tctpgrp, and \bf settpgrp\rm(2) system calls.
|
|
See the \bf jobcontrol\rm(2) and \bf ioctl\rm(2) man pages.
|
|
|
|
%
|
|
% CHAPTER: Interprocess Communication
|
|
%
|
|
|
|
\begin{latexonly}
|
|
\chapter{Interprocess Communication}
|
|
\end{latexonly}
|
|
\begin{htmlonly}
|
|
\chapter{Chapter 6: Interprocess Communication}
|
|
\end{htmlonly}
|
|
|
|
\tiny
|
|
|
|
\begin{verse}
|
|
Oh, give me a home \\
|
|
Where the semaphores roam, \\
|
|
and the pipes are not deadlocked all day ... \\
|
|
|
|
--- unknown western hero
|
|
\end{verse}
|
|
|
|
\normalsize
|
|
|
|
The term Interprocess Communication (\it IPC\rm)
|
|
covers a large range of operating system features. Any time a
|
|
process needs to send information to another process some form of
|
|
IPC is used. The GNO Kernel provides several basic types:
|
|
semaphores, signals, pipes, messages, ports, and
|
|
pseudo-terminals. These IPC mechanisms cover almost every
|
|
conceivable communication task a program could possibly need to
|
|
do.
|
|
|
|
\section{Semaphores}
|
|
|
|
In the days before radio, when two ships
|
|
wished to communicate with each other to decide who was going
|
|
first to traverse a channel wide enough only for one, they used
|
|
multicolored flags called semaphores. Computer scientists, being
|
|
great lovers of anachronistic terms, adopted the term and meaning
|
|
of the word semaphore to create a way for processes to
|
|
communicate when accessing shared information.
|
|
|
|
GNO/ME, like other multitasking systems,
|
|
provides applications with semaphore routines. Semaphores
|
|
sequentialize access to data by concurrently executing processes.
|
|
You should use semaphores whenever two or more processes want to
|
|
access shared information. For example, suppose there were three
|
|
processes, each of which accepted input from user terminals and
|
|
stored this input into a buffer in memory. Suppose also that
|
|
there is another process which reads the information out of the
|
|
buffer and stores it on disk. If one of the processes putting
|
|
information in the buffer (writer process) was in the middle of
|
|
storing information in the buffer when a
|
|
\index{context switch}
|
|
context switch occurred,
|
|
and one of the other processes then accessed the buffer, things
|
|
would get really confused. Code that accesses the buffer should
|
|
not be interrupted by another process that manipulates the
|
|
buffer; this code is called a
|
|
\index{critical section}
|
|
\it critical section\rm; in order to operate properly, this code
|
|
must not be interrupted by any other attempts to access the buffer.
|
|
|
|
To prevent the buffer from becoming
|
|
corrupted, a semaphore would be employed. As part of it's
|
|
startup, the application that started up the other processes
|
|
would also create a semaphore using the \bf screate\rm(2) system
|
|
call with a parameter of 1. This number means (among other
|
|
things) that only one process at a time can enter the critical
|
|
section, and is called the \it count\rm.
|
|
|
|
When a process wishes to access the buffer,
|
|
it makes a \bf swait\rm(2), giving as argument the semaphore
|
|
number returned by \bf screate\rm(2). When it's done with the
|
|
buffer, it makes an \bf ssignal\rm(2) call to indicate this fact.
|
|
|
|
This is what happens when \bf swait \rm is
|
|
called: the kernel first decrements the count. If the count is
|
|
then less than zero, the kernel suspends the process, because a
|
|
count of less than zero indicates that another process is already
|
|
inside a critical section. This suspended state is called
|
|
'waiting' (hence the name of \bf swait\rm). Every process that
|
|
tries to call \bf swait \rm with count < 0 will be suspended;
|
|
a queue of all the processes currently waiting on the semaphore
|
|
is associated with the semaphore.
|
|
|
|
Now, when the process inside the critical
|
|
section leaves and executes \bf ssignal\rm, the kernel
|
|
increments the count. If there are processes waiting for the
|
|
semaphore, the kernel chooses one arbitrarily and restarts it.
|
|
When the process resumes execution at its next time slice, its
|
|
\bf swait \rm
|
|
call will finish executing and it will have exclusive control of
|
|
the critical section. This cycle continues until there are no
|
|
processes waiting on the semaphore, at which point its count will
|
|
have returned to 1.
|
|
|
|
When the semaphore is no longer needed, you
|
|
should dispose of it with the \bf sdelete\rm(2) call. This call
|
|
frees any processes that might be waiting on the semaphore and
|
|
returns the semaphore to the semaphore pool.
|
|
|
|
One must be careful in use of semaphores or
|
|
\index{deadlock}
|
|
\it deadlock \rm can occur.
|
|
|
|
There are (believe it or not) many
|
|
situations in everyday programming when you may need semaphores,
|
|
moreso than real UNIX systems due to the Apple IIgs's lack of
|
|
virtual memory. The most common of these is your C or Pascal
|
|
compiler's stdio library; these are routines like \bf printf\rm(3)
|
|
and \bf writeln\rm(3). In many cases, these libraries use global
|
|
variables and buffers. If you write a program which forks a
|
|
\index{process!child}
|
|
child process that shares program code with the parent process (i.e.
|
|
doesn't \bf execve\rm(2) to another executable), and that child
|
|
and the parent both use \it non-reentrant \rm library calls, the
|
|
library will become confused. In the case of text output
|
|
routines, this usually results in garbaged output.
|
|
|
|
Other library routines can have more
|
|
disastrous results. For example, if a parent's
|
|
\bf free\rm(3) or \bf dispose\rm(3)
|
|
memory management call is interrupted, and the child makes a
|
|
similar call during this time, the linked lists that the library
|
|
maintains to keep track of allocated memory could become
|
|
corrupted, resulting most likely in a program crash.
|
|
|
|
GNO/ME provides \it mutual exclusion \rm
|
|
(i.e., lets a maximum of one process at a time execute the code)
|
|
automatically around all Toolbox and GS/OS calls as described in
|
|
Chapter 3, and also uses semaphores internally in many other
|
|
places. Any budding GNO/ME programmer is well advised to
|
|
experiment with semaphores to get a feel for when and where they
|
|
should be used. Examples of semaphore use can be found in the
|
|
sample source code, notably \tt dp.c \rm
|
|
(Dining Philosophers demo) and \tt pipe*.c \rm
|
|
(a sample implementation of pipes written entirely in C).
|
|
|
|
\section{Signals}
|
|
|
|
|
|
Another method of IPC is software signals.
|
|
Signals are similar to hardware interrupts in that they are
|
|
asynchronous; that is, a process receiving a signal does not have
|
|
to be in a special mode, does not have to wait for it. Also like
|
|
hardware interrupts, a process can install signal handlers to
|
|
take special action when a signal arrives. Unlike hardware
|
|
interrupts, signals are defined and handled entirely through
|
|
software.
|
|
|
|
Signals are generally used to tell a
|
|
process of some event that has occurred. Between the
|
|
system-defined and user-defined signals, there is a lot of things
|
|
you can do. GNO/ME currently defines 32 different signals. A list
|
|
of signals and their codes can be found in \bf signal\rm(2) and
|
|
the header file \tt <gno/signal.h>\rm.
|
|
|
|
There are three types of default actions
|
|
that occur upon receipt of a signal. The process receiving the
|
|
signal might be terminated, or stopped; or, the signal might be
|
|
ignored. The default action of any signal can be changed by a
|
|
process, with some exceptions. Not all of the defined signals are
|
|
currently used by GNO/ME, as some are not applicable to the Apple
|
|
IIgs, or represent UNIX features not yet implemented in GNO/ME .
|
|
Here is a list of the signals that are used by GNO/ME.
|
|
|
|
\begin{description}
|
|
\item[SIGINT]
|
|
This signal is sent to the
|
|
foreground job when a user types \^C at the terminal
|
|
keyboard.
|
|
\item[SIGKILL]
|
|
The default
|
|
action of this signal (termination) cannot be changed.
|
|
This provides a sure-fire means of stopping an otherwise
|
|
unstoppable process.
|
|
\item[SIGPIPE]
|
|
Whenever a process tries to
|
|
write on a pipe with no readers, it is sent this signal.
|
|
SIGALRM SIGALRM is sent when an
|
|
alarm timer expires (counts down to zero). An application
|
|
can start an alarm timer with the
|
|
\index{alarm}
|
|
\bf alarm\rm(2)
|
|
\begin{rawhtml}
|
|
</b>
|
|
\end{rawhtml}
|
|
\rm system call.
|
|
\item[SIGTERM]
|
|
This is the default signal
|
|
sent by \bf kill\rm(1). Use of this signal allows
|
|
applications to clean up (delete temporary files, free
|
|
system resources like semaphores, etc) before terminating
|
|
at the user's bequest.
|
|
\item[SIGSTOP]
|
|
This signal is used to stop
|
|
a process' execution temporarily. Like SIGKILL, processes
|
|
are not allowed to install a handler for this signal.
|
|
\item[SIGCONT]
|
|
To restart a stopped process, send this signal.
|
|
\item[SIGTSTP]
|
|
This is similar to SIGSTOP,
|
|
but is sent when the user types \^Z at the keyboard.
|
|
Unlike SIGSTOP, this signal can be ignored, caught, or
|
|
blocked.
|
|
\item[SIGCHLD]
|
|
\index{process!child}
|
|
A process receives this
|
|
signal whenever a child process is stopped or terminates.
|
|
\bf gsh \rm uses this to keep track of jobs, and the wait
|
|
system call waits for this signal to arrive before
|
|
exiting.
|
|
\item[SIGTTIN]
|
|
This signal also stops a process. It is sent to \index{background}
|
|
background jobs that try to get input from the terminal.
|
|
\item[SIGTTOU]
|
|
Similar to SIGTTIN, but is
|
|
sent when a background process tries to write to the
|
|
terminal. This behavior is optional and is by default
|
|
turned off.
|
|
\item[SIGUSR1, SIGUSR2]
|
|
These two signals are
|
|
reserved for application authors. Their meaning will
|
|
change from application to application.
|
|
\end{description}
|
|
|
|
As you can see, signals are used by many
|
|
aspects of the system. For detailed information on what various
|
|
signals mean, consult the appropriate electronic manual page ---
|
|
see \bf tty\rm(4), \bf wait\rm(2), and \bf signal\rm(2).
|
|
|
|
For an example of signal usage, consider a
|
|
print spooler. A print spooler takes files that are put in the
|
|
spool directory on a disk and sends the data in the files to a
|
|
printer. There are generally two parts to a print spooler: The
|
|
\index{daemon}
|
|
\it daemon\rm,
|
|
a process that resides in memory and performs the transfer of
|
|
data to the printer in the background; and the spooler. There can
|
|
be many different types of spoolers, say one for desktop
|
|
printing, one for printing source code, etc. To communicate to
|
|
the daemon that they have just placed a new file in the spool
|
|
directory, the spoolers could send the daemon SIGUSR. The daemon
|
|
will have a handler for SIGUSR, and that handler will locate the
|
|
file and set things up so the print will begin. Note that the
|
|
actual implementation of the print spooling system in GNO/ME,
|
|
\bf lpr\rm(1) and \bf lpd\rm(8),
|
|
is somewhat more complex and uses messages and
|
|
ports instead of signals. However, an earlier version of the
|
|
spooler software \it did \rm use signals for communication.
|
|
|
|
Signals should not be sent from inside an
|
|
interrupt handler, nor from inside a GS/OS or Toolbox call.
|
|
Window Manager update routines are a prime example of code that
|
|
should not send signals; they are executed as part of a tool
|
|
call. The GS/OS aspect of this limitation is a little harder to
|
|
come up against. GS/OS does maintain a software signal facility
|
|
of it's own, used to notify programs when certain low-level
|
|
events have occurred. Do not confuse these GS/OS signals with
|
|
GNO/ME signals, and above all, don't send a GNO/ME signal from a
|
|
GS/OS signal handler.
|
|
|
|
When a process receives a signal for which
|
|
it has installed a handler, what occurs is similar to a
|
|
\index{context switch}
|
|
context switch. The process' context is saved on the stack, and the
|
|
context is set so that the signal handler routine will be
|
|
executed. Since the old context is stored on the stack, the
|
|
signal handler may if it wishes return to some other part of the
|
|
program. It accomplishes this by setting the stack pointer to a
|
|
value saved earlier in the program and jumping to the appropriate
|
|
place. Jumps like this can be made with C's
|
|
\bf setjmp\rm(3) and \bf longjmp \rm(3)
|
|
functions. The following bit of code demonstrates this ability.
|
|
|
|
\begin{verbatim}
|
|
void sighandler (int sig, int code)
|
|
{
|
|
printf("Got a signal!");
|
|
longjmp(jmp_buf);
|
|
}
|
|
|
|
void routine(void)
|
|
{
|
|
signal(SIGUSR, sighandler);
|
|
if (setjmp(jmp_buf)) {
|
|
printf("Finally done! Sorry for all that...\n");
|
|
} else {
|
|
while(1) {
|
|
printf("While I wait I will annoy you!\n");
|
|
}
|
|
}
|
|
}
|
|
\end{verbatim}
|
|
|
|
% gdr: this is the spot where I left off reviewing the postscript output
|
|
|
|
This program basically prints an annoying
|
|
message over and over until SIGUSR is received. At that point,
|
|
the handler prints ``Got a Signal!'' and jumps back to
|
|
the part of the if statement that prints an apology. If the
|
|
signal handler hadn't made the \bf longjmp\rm, when the handler
|
|
exited control would have returned to the exact place in the \bf while \rm
|
|
loop that was interrupted.
|
|
|
|
\index{assembly language programs}
|
|
Similar techniques can be applied in assembly language.
|
|
|
|
\section{Pipes}
|
|
|
|
This third form of IPC implemented in
|
|
GNO/ME is one of the most powerful features ever put into an
|
|
operating system. A pipe is a conduit for information from one
|
|
process to another. Pipes are accessed just like regular files;
|
|
the same GS/OS and ToolBox calls currently used to manipulate
|
|
files are also used to manipulate pipes. When combined with
|
|
GNO/ME standard I/O features, pipes become very powerful indeed.
|
|
For examples on how to use \bf gsh \rm to connect applications
|
|
with pipes, see the \it GNO Shell Reference Manual\rm.
|
|
|
|
Pipes are unidirectional channels between
|
|
processes. Pipes are created with the \bf pipe\rm(2) system call,
|
|
which returns two GS/OS refNums; one for the write end, and one
|
|
for the read end. An attempt to read from the write end or
|
|
vice-versa results in an error.
|
|
|
|
Pipes under GNO/ME are implemented as a
|
|
circular buffer of 4096 bytes. Semaphores are employed to prevent
|
|
the buffer from overflowing, and to maintain synchronization
|
|
between the processes accessing the pipe. This is done by
|
|
creating two semaphores; their counts indicate how many bytes are
|
|
available to be read and how many bytes may be written to the
|
|
buffer (0 and 4096 initially). If an I/O operation on the pipe
|
|
would result in the buffer being emptied or filled, the calling
|
|
process is \index{blocked processes} blocked until the data (or space)
|
|
becomes available.
|
|
|
|
The usual method of setting up a pipeline
|
|
between processes, used by \bf gsh \rm and utilities such as
|
|
script, is to make the \bf pipe \rm call and then \bf fork\rm(2)
|
|
off the processes to be connected by the pipe.
|
|
|
|
\begin{verbatim}
|
|
|
|
/* No error checking is done in this fragment. This is
|
|
* left as an exercise for the reader.
|
|
*/
|
|
|
|
int fd[2];
|
|
int
|
|
testPipe(void)
|
|
{
|
|
pipe(fd); /* create the pipe */
|
|
fork(writer); /* create the writer process */
|
|
fork(reader); /* create the reader process */
|
|
close(fd[0]); /* we don't need the pipe anymore, because */
|
|
close(fd[1]); /* the children inherited them */
|
|
|
|
{ wait for children to terminate ... }
|
|
}
|
|
|
|
void
|
|
writer(void) {
|
|
/* reset the standard output to the write pipe */
|
|
dup2(STDOUT_FILENO, fd[1]);
|
|
|
|
/* we don't need the read end */
|
|
close(fd[0]);
|
|
{ exec writer process ...}
|
|
}
|
|
|
|
void
|
|
reader(void) {
|
|
/* reset the standard input to the write pipe */
|
|
dup2(STDIN_FILENO, fd[0]);
|
|
|
|
/* we don't need the write end */
|
|
close(fd[1]);
|
|
{ exec reader process ...}
|
|
}
|
|
|
|
\end{verbatim}
|
|
|
|
Recall that when a new process is forked,
|
|
it inherits all of the open files of it's parent; thus, the two
|
|
children here inherit not only standard I/O but also the pipe.
|
|
After the forks, the parent process closes the pipe and each of
|
|
the child processes closes the end of the pipe it doesn't use.
|
|
This is actually a necessary step because the kernel must know
|
|
when the reader has terminated in order to also stop the writer
|
|
(by sending \tt SIGPIPE\rm.
|
|
Since each open refNum to the read end of the
|
|
pipe is counted as a reader, any unnecessary copies must be
|
|
closed.
|
|
|
|
For further examples of implementing and
|
|
programming pipes, see the sample source code for \tt pipe.c\rm.
|
|
|
|
\section{Messages}
|
|
|
|
GNO's Message IPC is borrowed from the XINU
|
|
Operating System, designed by Douglas Comer. It is a simple way
|
|
to send a datum (a message) to another process. Messages are
|
|
32-bit (4-byte) longwords.
|
|
|
|
The Message IPC is centered around two
|
|
calls, \bf procsend\rm(2) and \bf procreceive\rm(2).
|
|
The \bf procsend \rm call sends a
|
|
message to a specified process ID. To access that message, a
|
|
process must use \bf procreceive\rm. If no message is waiting for a
|
|
process when it calls \bf procreceive\rm, the process will
|
|
\index{blocked processes} block until a message becomes available.
|
|
|
|
Since a process can only have one pending
|
|
message, the Message IPC is useful mostly in applications where
|
|
two or more cooperating processes only occasionally need to
|
|
signal each other; for example, the \bf init\rm(8) program
|
|
communicates with the \bf initd \rm
|
|
\index{daemon}
|
|
daemon by sending messages. Various
|
|
attributes are encoded in the 32-bit value sent to \bf initd\rm(8)
|
|
to instruct it on how to change its state.
|
|
|
|
If a process doesn't want to indefinitely block waiting for a message,
|
|
it can call \bf procrecvtim\rm(2). The \bf procrecvtim \rm call
|
|
accepts a timeout parameter which indicates the maximum amount of
|
|
time to wait for a message.
|
|
|
|
\section{Ports}
|
|
|
|
GNO/ME Ports IPC can be thought of as an
|
|
extended version of Messages. Whereas only one message can be
|
|
pending at once, a port can contain any number of pending
|
|
messages (up to a limit defined when an application creates a
|
|
port).
|
|
|
|
Like Messages, Ports transmit 32-bit values
|
|
between processes. The calls \bf psend\rm(2) and \bf preceive\rm(2)
|
|
work similarly to their Message counterparts.
|
|
|
|
A Port is created with the \bf pcreate\rm(2)
|
|
call. The application specifies the size of the port in this
|
|
call. When the application is done with the port, it should call
|
|
\bf pdelete\rm(2) to free up the resources used by the port.
|
|
|
|
One of the most important aspects of ports
|
|
is the ability to bind a \it name \rm to a port. Whereas many of
|
|
GNO/ME IPC mechanisms require the communicating processes to be
|
|
related in some way (common children of the same parent, for
|
|
instance) being able to give a port a name means that totally
|
|
unrelated processes can communicate. For example, the GNO/ME
|
|
print spooling system uses a named port for communicating
|
|
information about the addition of new jobs to the print queue.
|
|
The printer
|
|
\index{daemon}
|
|
daemon, \bf lpd\rm(8), creates a port with a specific
|
|
name; the name is defined by the author of the print daemon; any
|
|
application that wishes to have the daemon print a spool file
|
|
also knows this name. (The standard print daemon uses the name
|
|
``LPDPrinter''). The name allows an application to find
|
|
lpd's port regardless of the actual numeric port ID (which might
|
|
be different from system to system, or even from session to
|
|
session on the same machine).
|
|
|
|
Names are bound to ports with the \bf pbind\rm(2) call.
|
|
The numeric port ID can be obtained by passing a name to
|
|
\bf pgetport\rm(2).
|
|
|
|
\section{Pseudo-Terminals (PTYs)}
|
|
|
|
Pseudo-terminals are a bi-directional
|
|
communication channel that can be used to connect two processes
|
|
(or more correctly, a process group to another process). You may
|
|
(correctly) ask why two pipes would not do the same thing; the
|
|
answer is that a lot of modern UNIX software relies on the way
|
|
the terminal interface works, and thus would malfunction when
|
|
presented with a pipe as standard input. What PTYs provide is a
|
|
lot like two pipes, but with a TTY interface.
|
|
|
|
PTYs can be used in a number of important
|
|
and exciting applications, such as windowing systems and
|
|
'script-driven' interfaces.
|
|
|
|
Windowing systems like the UNIX X windowing system (known as just
|
|
``\bf X\rm'')
|
|
use PTYs to give a process group an interface that looks exactly
|
|
like a real terminal; however, the 'terminal' in this case is
|
|
actually a window in a graphics-based system. The program that
|
|
manages the window ('xterm' in \bf X\rm) is called the \it master\rm.
|
|
It is responsible for setting up the PTY, and starting up the
|
|
process with redirection (usually a shell) that is to run in the
|
|
window. The process running in the window is called the \it slave\rm.
|
|
|
|
\index{device!character}
|
|
To allocate a PTY, the master opens in turn
|
|
each PTY device starting with
|
|
\index{.pty}
|
|
.ptyq0. If a PTY is already in use,
|
|
the open call will return an error (the kernel uses the EXCL flag
|
|
internally). When an open succeeds, the master then has exclusive
|
|
access to that PTY. At this point, the master opens the
|
|
corresponding TTY file
|
|
\index{.tty}
|
|
(.ttyq0 --- .ttyqf), or the slave device. It
|
|
then forks off a process, which sets redirection up in the normal
|
|
fashion and then exec's the program to run on the PTY.
|
|
|
|
The following code fragment is taken from the source code for the
|
|
Graphical Shell Interface (GSI) NDA.
|
|
\tt initPipe \rm
|
|
scans the PTY devices, looking for a free one as
|
|
discussed above. Note that the master side of a PTY does \em not \rm
|
|
have (by default) a terminal interface; it is a very raw device,
|
|
with only a few \bf ioctl\rm's to be able to send signals and handle
|
|
other such low-level tasks.
|
|
|
|
\index{.pty}
|
|
\begin{verbatim}
|
|
|
|
char buffer[1024];
|
|
int ptyno, master;
|
|
|
|
int
|
|
initPipe(void)
|
|
{
|
|
int cl[2];
|
|
struct sgttyb sb;
|
|
char *ptyname = ".ptyq0";
|
|
|
|
unsigned i;
|
|
|
|
/* We have to open the master first */
|
|
for (i = 0; i<2; i++) {
|
|
/* generate a PTY name from the index */
|
|
ptyname[5] = intToHex(i);
|
|
master = open(ptyname,O_RDWR);
|
|
if (master > 0) {
|
|
break; /* successful open */
|
|
}
|
|
}
|
|
|
|
if (master < 1) {
|
|
return -1;
|
|
}
|
|
|
|
ptyno = i;
|
|
pid1 = fork(producer);
|
|
return 0;
|
|
}
|
|
\end{verbatim}
|
|
|
|
\tt producer() \rm
|
|
sets up redirection for the shell, and also opens
|
|
the slave side of the PTY. The slave processes must not have any
|
|
access whatsoever to the master side of the PTY, so \bf close(0) \rm
|
|
is used to close all open files (which includes, at this point,
|
|
the master PTY file descriptor from initPipe). Note that as in
|
|
many pipe applications, the file descriptor that will be assigned
|
|
to a newly opened file is assumed, and that can be safely done in
|
|
this case because it is clear that with no files open the next
|
|
file descriptor will be 1.
|
|
|
|
\index{.tty}
|
|
\begin{verbatim}
|
|
/* the shell is executed here */
|
|
|
|
#pragma databank 1
|
|
void
|
|
producer(void)
|
|
{
|
|
char *ptyname = ".ttyq0";
|
|
|
|
/* we must not have access to ANY other ttys */
|
|
|
|
close(0); /* close ALL open files */
|
|
ptyname[5] = intToHex(ptyno);
|
|
|
|
/* modify the tty slave name to correspond
|
|
* to the master */
|
|
|
|
slave = open(ptyname,O_RDWR); /* file descriptor 1 */
|
|
dup(slave); /* fd 2 */
|
|
dup(slave); /* fd 3 */
|
|
|
|
/* Set up the TextTools redirection */
|
|
SetOutputDevice(3,2l);
|
|
SetErrorDevice(3,3l);
|
|
SetInputDevice(3,1l);
|
|
|
|
WriteCString("Welcome to GNO GSI\r\n");
|
|
_execve(":bin:gsh","gsh -f");
|
|
|
|
/* If we get here, we were unable to run
|
|
* the shell.
|
|
*
|
|
* GDR note: printf should not be used here,
|
|
* since we're in the child process */
|
|
printf("Could not locate :bin:gsh : %d", errno);
|
|
}
|
|
#pragma databank 0
|
|
\end{verbatim}
|
|
|
|
\tt consume() \rm
|
|
is called as part of GSI's event loop. It simply
|
|
checks to see if there is any data for the master by using the
|
|
FIONREAD ioctl, one of the few ioctl's supported by the master
|
|
side. See PTY(4) for details. Any data that is available is sent
|
|
to the window via a routine toOut, which inserts the new data
|
|
into a TextEdit record.
|
|
|
|
\begin{verbatim}
|
|
void
|
|
consume(CtlRecHndl teH)
|
|
{
|
|
char ch;
|
|
int fio, fio1, i;
|
|
|
|
ioctl(master,FIONREAD,&fio);
|
|
if (fio) {
|
|
if (fio > 256) {
|
|
fio = 256;
|
|
}
|
|
fio1 = read(master,buffer,fio);
|
|
buffer[fio] = 0;
|
|
toOut(buffer,fio,teH);
|
|
updateWind1(fio,fio1);
|
|
}
|
|
}
|
|
\end{verbatim}
|
|
|
|
When the user types a key, the keypress is
|
|
sent to the slave by simply writing the data with a write call.
|
|
|
|
\begin{verbatim}
|
|
void
|
|
writedata(char k)
|
|
{
|
|
write(master, &k, 1);
|
|
}
|
|
\end{verbatim}
|
|
|
|
When the user is done with the window and
|
|
closes it, GSI closes the master end of the PTY.
|
|
|
|
\begin{verbatim}
|
|
void
|
|
closePipe(void)
|
|
{
|
|
int cl[2];
|
|
close(master);
|
|
}
|
|
\end{verbatim}
|
|
|
|
When this is done, the slave process
|
|
receives a SIGHUP signal, to indicate that the connection was
|
|
lost. Since the standard behavior of SIGHUP is to terminate the
|
|
process, the slave dies and either the slave or the kernel closes
|
|
the slave end. At this point, the PTY is available for re-use by
|
|
another application.
|
|
|
|
As you can see, PTYs are very simple to
|
|
program and use. The simplicity can be misleading, for PTYs are a
|
|
very powerful method of IPC. As another example of the use of
|
|
PTYs, we point out that PTYs can be used to drive programs with
|
|
'scripts'. These scripts are a series of 'wait-for' and 'print'
|
|
operations, much like auto-logon macros in communications
|
|
programs such as ProTERM. Script-driving a program can be used to
|
|
automate testing or use of an application.
|
|
|
|
PTYs can be used to test software that
|
|
would normally work over a regular terminal (such as a modem).
|
|
Since PTYs are identical (to the slave) to terminals, the
|
|
application being tested doesn't know the difference. What this
|
|
means to the programmer is incredible power and flexibility in
|
|
testing the application. For example, a communications program
|
|
could be nearly completely tested without ever dialing to another
|
|
computer with a modem!
|
|
|
|
There are so many applications of PTYs that
|
|
to attempt to discuss them all here would be impossible; as PTYs
|
|
are discovered by more GNO/ME programmers we expect that more
|
|
useful PTY applications will become available.
|
|
|
|
\section{Deadlock}
|
|
|
|
\index{deadlock|(}
|
|
With interprocess communication comes the
|
|
problem of \em deadlock\rm. If a situation arises where two or
|
|
more processes are all waiting for an signal from one of the
|
|
other waiting processes, the processes are said to be deadlocked.
|
|
|
|
The best way to explain deadlock is to give
|
|
an example. Suppose that two processes are connected with two
|
|
pipes so that they can communicate bidirectionally. Also suppose
|
|
that each of the pipes are full, and that when each process
|
|
writes into one of the pipes they are blocked.
|
|
\index{blocked processes}
|
|
Both processes are blocked waiting for the other to unblock them.
|
|
|
|
There is no way for the operating system to
|
|
detect every conceivable deadlock condition without expending
|
|
large amounts of CPU time. Thus, the only way to recover from a
|
|
deadlock is to kill the processes in question. Responsibility for
|
|
preventing deadlock situations is placed on the programmer.
|
|
Fortunately, situations where deadlock can occur are infrequent;
|
|
however, you should keep an eye out for them and try to work
|
|
around them when they do occur.
|
|
|
|
\index{deadlock|)}
|
|
|
|
\appendix
|
|
|
|
%
|
|
% Appendix: Making System Calls
|
|
%
|
|
|
|
\begin{latexonly}
|
|
\chapter{Making System Calls}
|
|
\end{latexonly}
|
|
\begin{htmlonly}
|
|
\chapter{Appendix A: Making System Calls}
|
|
\end{htmlonly}
|
|
|
|
\begin{latexonly}
|
|
\end{latexonly}
|
|
\begin{htmlonly}
|
|
\end{htmlonly}
|
|
|
|
The GNO Kernel is accessed through system
|
|
calls. The actual procedure is very simple from C: simply
|
|
\#include the appropriate header file as noted in the synopsis of
|
|
the call's manual page, and call it as you would any other C
|
|
function. From
|
|
\index{assembly language programs}
|
|
assembly language the procedure is no more
|
|
difficult, using the advanced macros provided for the \index{APW} APW and
|
|
ORCA assemblers. Make sure, however, that you have defined a word
|
|
variable \bf errno\rm. Lowercase is important, use the 'case on'
|
|
and 'case off' directives to ensure that the definition of \bf errno \rm
|
|
is case-sensitive. The system call interface libraries store any
|
|
error codes returned by the kernel in this variable.
|
|
|
|
If you are going to be accessing the kernel
|
|
from a language other than those for which interfaces are
|
|
provided, then the following information is for you.
|
|
|
|
\section{System Call Interface}
|
|
|
|
The system calls are implemented as a user toolset, tool number 3.
|
|
These tools are called the same way regular system tools (such as QuickDraw)
|
|
are called, except that you must \tt JSL \rm to \bf \$E10008 \rm
|
|
instead of to \bf \$E10000 \rm (or to \bf \$E1000C \rm instead of
|
|
to \bf \$E10004 \rm for the alternate entry point). The function
|
|
numbers for the currently defined tools are as follows:
|
|
|
|
\index{alarm}
|
|
\index{alarm10}
|
|
\begin{tabular}{llll}
|
|
getpid * & \$0903 &
|
|
kill & \$0A03 \\
|
|
fork & \$0B03 &
|
|
swait & \$0D03 \\
|
|
ssignal & \$0E03 &
|
|
screate & \$0F03 \\
|
|
sdelete & \$1003 &
|
|
kvm\_{}open & \$1103 \\
|
|
kvm\_{}close & \$1203 &
|
|
kvm\_{}getproc & \$1303 \\
|
|
kvm\_{}nextproc & \$1403 &
|
|
kvm\_{}setproc & \$1503 \\
|
|
signal & \$1603 &
|
|
wait & \$1703 \\
|
|
tcnewpgrp & \$1803 &
|
|
settpgrp & \$1903 \\
|
|
tctpgrp & \$1A03 &
|
|
sigsetmask & \$1B03 \\
|
|
sigblock & \$1C03 &
|
|
execve & \$1D03 \\
|
|
alarm & \$1E03 &
|
|
setdebug * & \$1F03 \\
|
|
setsystemvector * & \$2003 &
|
|
sigpause & \$2103 \\
|
|
dup & \$2203 &
|
|
dup2 & \$2303 \\
|
|
pipe & \$2403 &
|
|
getpgrp & \$2503 \\
|
|
ioctl & \$2603 &
|
|
stat & \$2703 \\
|
|
fstat & \$2803 &
|
|
lstat & \$2903 \\
|
|
getuid & \$2A03 &
|
|
getgid & \$2B03 \\
|
|
geteuid & \$2C03 &
|
|
getegid & \$2D03 \\
|
|
setuid & \$2E03 &
|
|
setgid & \$2F03 \\
|
|
procsend & \$3003 &
|
|
procreceive & \$3103 \\
|
|
procrecvclr & \$3203 &
|
|
procrecvtim & \$3303 \\
|
|
setpgrp & \$3403 &
|
|
times & \$3503 \\
|
|
pcreate & \$3603 &
|
|
psend & \$3703 \\
|
|
preceive & \$3803 &
|
|
pdelete & \$3903 \\
|
|
preset & \$3A03 &
|
|
pbind & \$3B03 \\
|
|
pgetport & \$3C03 &
|
|
pgetcount & \$3D03 \\
|
|
scount & \$3E03 &
|
|
fork2 & \$3F03 \\
|
|
getppid & \$4003 &
|
|
SetGNOQuitRec & \$4103 \\
|
|
alarm10 & \$4203 \\
|
|
\end{tabular}
|
|
|
|
The following system calls are new to GNO v2.0.6:
|
|
|
|
\begin{tabular}{llll}
|
|
select & \$4303 &
|
|
InstallNetDriver & \$4403 \\
|
|
socket & \$4503 &
|
|
bind & \$4603 \\
|
|
connect & \$4703 &
|
|
listen & \$4803 \\
|
|
accept & \$4903 &
|
|
recvfrom & \$4A03 \\
|
|
sendto & \$4B03 &
|
|
recv & \$4C03 \\
|
|
send & \$4D03 &
|
|
getpeername & \$4E03 \\
|
|
getsockname & \$4F03 &
|
|
getsockopt & \$5003 \\
|
|
setsockopt & \$5103 &
|
|
shutdown & \$5203 \\
|
|
setreuid & \$5303 &
|
|
setregid & \$5403 \\
|
|
\end{tabular}
|
|
|
|
Parameters should be pushed onto the stack
|
|
in the same order as defined by the C prototypes outlines in the
|
|
synopsis section of the manual pages; that is, left-to-right. In
|
|
addition to those parameters, all of the functions (except those
|
|
denoted by a \bf *\rm) take an integer pointer parameter \bf errno\rm.
|
|
This is a pointer to a word value which will contain the \bf errno \rm
|
|
code returned by the function if an error occurs, and should be
|
|
pushed onto the stack after all the other parameters. The calls
|
|
do not clear this code to 0 if no error occurs; thus, you must
|
|
check the return value of the function to see if an error
|
|
occurred, and then check errno to get the actual error code.
|
|
|
|
Do not forget to also push space on the
|
|
stack (before the parameters) for the call to store its return
|
|
value.
|
|
|
|
These low-level system call interfaces are
|
|
not to be used in general programming. It is assumed the
|
|
programmer will use the libraries provided, or use this
|
|
information to create a new library. The system call interface is
|
|
subject to change without notice; any changes will, of course, be
|
|
documented in future versions of GNO/ME.
|
|
|
|
\section{System Call Error Codes}
|
|
|
|
The following codes are taken from \tt <sys/errno.h>\rm. The
|
|
codes up to EPERM are the same values as those defined by ORCA/C
|
|
for compatibility reasons. Error conditions are usually reported
|
|
by system calls by returning a -1 (word) or NULL (long) value.
|
|
Which error codes can be expected from a particular call are
|
|
detailed in the errors section in the appropriate manual page.
|
|
|
|
\begin{description}
|
|
\item[EDOM]
|
|
Domain error. Basically an undefined error code.
|
|
\item[ERANGE]
|
|
Range error. A value passed to a system call was too large,
|
|
too small, or illegal.
|
|
\item[ENOMEM]
|
|
Not enough memory. The kernel could not allocate enough
|
|
memory to complete the requested operation.
|
|
\item[ENOENT]
|
|
No such file or directory. The file specified could not be found.
|
|
\item[EIO]
|
|
I/O error. An error occurred trying to perform an I/O operation,
|
|
such as that caused by bad media. It also refers to a disk
|
|
error not covered by the other errno codes.
|
|
\item[EINVAL]
|
|
Invalid argument. An argument to a system call was invalid in some way.
|
|
\item[EBADF]
|
|
Bad file descriptor. The file descriptor passed to the kernel does not
|
|
represent an open file.
|
|
\item[EMFILE]
|
|
Too many files are open. The kernel cannot open any more files
|
|
for this process; it's open file table is full. Close some other
|
|
open files and retry the operation.
|
|
\item[EACCESS]
|
|
Access bits prevent the operation. One of the access bit settings
|
|
(delete, rename, read, write) associated with the file does not allow
|
|
the requested operation.
|
|
\item[EEXIST]
|
|
The file exists. An attempt to create a new file with the same name
|
|
as an existing file results in this error.
|
|
\item[ENOSPC]
|
|
No space on device. There is not enough room on the requested
|
|
device to complete the operation. This is usually indicative
|
|
of a full disk.
|
|
\item[EPERM]
|
|
Not owner. Not yet used in GNO.
|
|
\item[ESRCH]
|
|
No such process. The process ID specified does not refer to an active
|
|
process. Possibly the process terminated earlier.
|
|
\item[EINTR]
|
|
Interrupted system call. Certain system calls can be interrupted by
|
|
signals. In cases where the user has specified that those calls not be
|
|
automatically restarted, the call will return this error.
|
|
\item[E2BIG]
|
|
Arg list too long. Too many arguments were specified in an
|
|
\bf \_{}execve\rm(2) call.
|
|
\item[ENOEXEC]
|
|
Exec format error. The file specified is not in an executable format
|
|
(OMF load file).
|
|
\item[ECHILD]
|
|
No children. This error is returned by \bf wait\rm(2) when there
|
|
are no child processes left running.
|
|
\item[EAGAIN]
|
|
No more processes. The process table is full, the \bf fork\rm(2)
|
|
cannot complete.
|
|
\item[ENOTDIR]
|
|
Not a directory. One of the elements in a pathname refers to a file
|
|
which is not a directory.
|
|
\item[ENOTTY]
|
|
Not a terminal. The file descriptor passed to an \bf ioctl\rm(2)
|
|
or job control call does not refer to a terminal file.
|
|
\item[EPIPE]
|
|
Broken pipe. If a process attempts to write on a pipe with no
|
|
readers, and has blocked or ignored SIGPIPE, this error is
|
|
returned by the write operation.
|
|
\item[ESPIPE]
|
|
Illegal seek. Similar to ENOTBLK, but specific for pipes.
|
|
\item[ENOTBLK]
|
|
Not a block device. An attempt to perform an operation on a character
|
|
device that only makes sense on a block device.
|
|
\end{description}
|
|
|
|
|
|
|
|
\section{System Panics}
|
|
|
|
In most cases, if the kernel detects an
|
|
error in operation an appropriate error code is returned by the
|
|
function in question (GS/OS calls, ToolBox calls, or system calls
|
|
as described above). However, there are rare circumstances where
|
|
the kernel detects what should be an impossible condition. This
|
|
can happen due to bugs in the kernel, because the kernel was
|
|
overwritten by a buggy program, or for any number of other
|
|
reasons.
|
|
|
|
When the kernel does come across such an
|
|
error, system operation cannot continue and what ensues is called
|
|
a \em system panic\rm. Panics are very easily noticed- the kernel
|
|
will print an error message on the screen and ensure that the
|
|
text screen is visible, turning off any graphics mode if
|
|
necessary. The kernel then sets the text and background colors to
|
|
red on white - a very noticeable condition. At that point, the
|
|
kernel turns off
|
|
\index{context switch}
|
|
context switching to prevent any background
|
|
process or other interrupt driven code from further confusing the
|
|
system. This is done mainly to prevent damage to disk directory
|
|
structures by a bad system.
|
|
|
|
When a system panic does occur, the only
|
|
thing you can do is reboot your system. If you can reliably
|
|
reproduce a system panic, please record the panic message and the
|
|
sequence of events necessary to evoke the panic and report the
|
|
information to Procyon, Inc.
|
|
|
|
%
|
|
% Appendix: Miscellaneous Programming Issues
|
|
%
|
|
|
|
\begin{latexonly}
|
|
\chapter{Miscellaneous Programming Issues}
|
|
\end{latexonly}
|
|
\begin{htmlonly}
|
|
\chapter{Appendix B: Miscellaneous Programming Issues}
|
|
\end{htmlonly}
|
|
|
|
\section{Option Arguments}
|
|
|
|
The Free Software Foundation (also known as the
|
|
FSF), invented user friendly long format option arguments, and
|
|
defined the ``\bf +\rm>'' character for interpretation
|
|
that a long format follows. This interpretation is generally
|
|
followed in the UNIX community. There are two files which will assist
|
|
you in programming GNO/ME utilities with both short and long
|
|
format options, \tt <getopt.h> \rm for short options, and
|
|
\tt <getopt1.h> \rm for long options.
|
|
|
|
\section{Pathname Expansion}
|
|
|
|
Those of you familiar with programming in
|
|
the ORCA environment should be familiar with the shell calls
|
|
\tt InitWildcard \rm and \tt NextWildcard\rm.
|
|
These shell calls, while supported by \bf gsh\rm,
|
|
are no longer necessary. All shell utilities that work with
|
|
multiple filenames do not need to provide support for file
|
|
globbing, as this is taken care of transparently to the command.
|
|
|
|
%
|
|
% Glossary
|
|
%
|
|
|
|
\chapter{Glossary}
|
|
|
|
\begin{description}
|
|
\item[Asynchronous]
|
|
An event that may take place at any time. See synchronous.
|
|
\item[BASIC]
|
|
\index{BASIC}
|
|
Beginners All-purpose Symbolic Instruction Code. A simple computer
|
|
language.
|
|
\item[Blocked]
|
|
\index{blocked processes}
|
|
Refers to a process waiting for some event to occur. Processes can
|
|
block on terminal I/O, signals, and other IPC and I/O functions.
|
|
\item[Console]
|
|
The terminal which represents the IIGS's keyboard and monitor.
|
|
\item[Context]
|
|
The attributes which define the state of a process. This includes
|
|
the program counter, stack pointer, and other machine registers (both
|
|
CPU and other computer hardware).
|
|
\item[Controlling terminal]
|
|
\index{controlling terminal}
|
|
The terminal which ``controls'' a process or process group;
|
|
processes can receive keyboard signals (such as SIGTSTP, or
|
|
\index{\^{}Z} \^{}Z)
|
|
only from their controlling terminal.
|
|
\item[Critical Section]
|
|
A piece of code inside which only one process at a time may
|
|
be allowed to execute. Critical sections are usually protected by
|
|
semaphores.
|
|
\item[Daemon]
|
|
\index{daemon}
|
|
A process that runs in the \index{background} background and
|
|
waits to act on an
|
|
asynchronous event. These can be anything: waiting for a caller
|
|
on a modem, waiting for spooled files to print, etc. Daemons
|
|
are usually started at boot time by the \bf initd\rm(8)
|
|
process.
|
|
\item[Deadlock]
|
|
\index{deadlock}
|
|
A situation where two or more communicating processes are blocked,
|
|
waiting on each other. See Chapter 5, ``Deadlock''.
|
|
\item[Errno]
|
|
A variable which holds a descriptive numeric error code,
|
|
returned from C libraries and system calls.
|
|
\item[Foobar, foo, bar]
|
|
Foobar derives from an old military acronym FUBAR. In it's politest
|
|
interpretation it stands for Fouled Up Beyond All Recognition.
|
|
Computer scientists borrowed the term and created foobar.
|
|
When a name for an object in a code fragment is needed but the
|
|
name itself is not important, foo and bar are first choice among
|
|
computing science types. They should not be used in production
|
|
code.
|
|
\item[Executable]
|
|
A program as it resides on disk. Executables can be compiled or
|
|
assembled programs, or shell scripts. Executables are run by
|
|
typing their name on the shell's command line and frequently take
|
|
paramters to determine what data they operate on and particulars
|
|
of how they do it.
|
|
\item[GNO/ME]
|
|
GNO Multitasking Environment. The complete package including the GNO
|
|
kernel and the GNO Shell.
|
|
\item[GNO Kernel]
|
|
Heart of GNO/ME. Executes processes when asked by the GNO Shell.
|
|
\item[GNO Shell]
|
|
Provides an interface between the user and the GNO kernel.
|
|
\item[gsh]
|
|
GNO Implementation of a UNIX-like shell.
|
|
\item[GS/OS]
|
|
A 16 bit Operating System for the Apple IIgs.
|
|
\item[IPC]
|
|
``Inter-Process Communication''. Any method by which processes
|
|
can pass information to other processes.
|
|
\item[Job]
|
|
\index{controlling terminal}
|
|
A set of related processes. Jobs are generally composed of
|
|
processes with a common parent and the same controlling terminal.
|
|
\item[Manpage]
|
|
Refers to the system call and utility documentation provided with GNO.
|
|
Manpages exist on disk as either \bf nroff\rm(1) or \bf aroff\rm(1)
|
|
source. They can also be preformatted by \bf catman\rm(1). They
|
|
can be viewed by various utilites on a variety of output devices.
|
|
\item[Master]
|
|
\index{.pty}
|
|
Refers to the .PTYxx side of a pseudo-terminal, and also
|
|
the process controlling that device. The master is usually responsible
|
|
for setting up the PTY and running a process on it.
|
|
\item[Message]
|
|
A 32-bit value that is passed via the Messages IPC mechanism to
|
|
another process.
|
|
\item[Mutex]
|
|
\index{critical section}
|
|
Short for mutual exclusion, a term that refers to protecting a
|
|
critical section.
|
|
\item[Panic]
|
|
An unrecoverable kernel error, usually indicating that an
|
|
internal data structure has become corrupted.
|
|
\item[Parent]
|
|
When talking about a process, the parent of a process is the one that
|
|
spawned it; i.e., made the \bf fork\rm(2) system call.
|
|
\item[Pipe]
|
|
A unidirectional IPC mechanism. Pipes transmit binary 8-bit data.
|
|
\item[Pipeline]
|
|
Two or more processes connected by pipes.
|
|
\item[Port]
|
|
A flow-controlled IPC mechanism that can pass longwords of data.
|
|
\item[Process]
|
|
A program in execution.
|
|
\item[Process Group]
|
|
An identifying code for a job. Process groups are also assigned
|
|
to TTYs, which allows the TTY to differentiate \index{background}
|
|
background jobs from foreground jobs when sending interrupt signals.
|
|
\item[Pseudo-terminal]
|
|
A bidirectional communications channel, normally used in windowing
|
|
systems or for advanced control and testing applications.
|
|
\item[PTY]
|
|
See 'pseudo-terminal'.
|
|
\item[Semaphore]
|
|
A data object used to synchronize concurrent processes.
|
|
\item[Sequentialization]
|
|
\index{critical section}
|
|
The task of ensuring that critical sections are only executed by one
|
|
concurrent process at a time.
|
|
\item[Signal]
|
|
A software interrupt and IPC mechanism.
|
|
\item[Slave]
|
|
1. A good term to describe the relationship of Joe Citizen to the IRS.
|
|
2. The \index{.tty} .TTYxx side of a pseudo-terminal; the slave
|
|
is usually an application program of some kind, like a shell.
|
|
\item[Suspended]
|
|
Refers to a process whose execution has been stopped.
|
|
\item[Synchronous]
|
|
An event that takes place at a predetermined time or sequence of times.
|
|
Also used to indicate the act of waiting for an event to happen. See
|
|
asynchronous.
|
|
\item[Terminal]
|
|
Any device that looks like a terminal; this includes pseudo-ttys. By
|
|
definition, a terminal supports all of the \bf tty\rm(4)
|
|
ioctl calls.
|
|
\item[Tty]
|
|
Short for Teletype. TTY is an anachronistic term; in modern usage
|
|
it is taken to mean ``terminal''.
|
|
\item[UNIX]
|
|
Popular operating system which has growing use in education and
|
|
business. One of the first operating systems to support multitasking.
|
|
\end{description}
|
|
|
|
\printindex
|
|
|
|
\end{document}
|
|
|