GNO/ME Version 2.0
By Jawaid Bazyar and Tim Meekins
The GNO Multitasking Environment is Copyright 1991-1996 by Procyon Enterprises Incorporated
Documentation, second edition, August 1996.
The ORCA/C run-time libraries are Copyright 1987-1993 Byte Works, Inc. and distributed with permission.
This product includes software developed by the University of California, Berkeley and its contributors.
GNO/ME 2.0 also includes several utilities and libraries produced by outside authors and in the public domain. This software is included solely as a convenience to users of GNO/ME, and is not considered part of GNO/ME for copyright purposes.
GNO and GNO/ME are trademarks of Procyon Enterprises Incorporated.
Apple IIGS, APW, Finder, GS/OS, ProDOS, Macintosh, and HFS are registered trademarks of Apple Computer, Inc.
AppleWorks GS is a trademark of Claris Corp.
UNIX is a registered trademark of AT&T Bell Laboratories.
Important Notice: This is a fully copyrighted work and as such is protected under the copyright laws of the United States of America. According to these laws, consumers of copywritten material may make copies for their personal use only. Duplication for any other purpose whatsoever would constitute infringement of copyright laws and the offender would be liable to civil damages of up to $50,000 in addition to actual damages, plus criminal penalties of up to one year imprisonment and/or a $10,000 fine.
Procyon Enterprises Inc. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED IN SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE.
This product is sold for use on a single computer at a single location. For information on obtaining a site license for using multiple copies, contact the publisher.
Procyon Enterprises, Inc.
P.O. Box 641
Englewood, CO 80151-0641 USA
(303) 781-3273
Credits
"Always listen to experts. They'll
tell you what can't be done, and why. Then do it."
Lazarus Long
The GNO Multitasking Environment for the Apple IIgs
Copyright 1991-1993, Procyon Enterprises Inc. and Tim Meekins
Please direct all inquiries to:
For on-line technical assistance, contact:
Written by:
Jawaid Bazyar Kernel &
Documentation
Tim Meekins Shell & Documentation
Albert Chin Documentation
Andrew Roughan Documentation
Derek Taubert Kernel support and utilities
Greg Thompson, Philip Vandry, James Brookes, Ian
Schmidt Utilities
With many thanks to:
Dave Lyons, for tolerating my endless questions since the beginning of time, for getting me started in IIgs programming, and for calling GNO 'cool'.
Mike Westerfield, for your technical assistance and all your work in making great development tools for the IIgs.
Special thanks to:
Randy Hyde, for telling me it couldn't be done.
Miscellaneous
Reporting Bugs
In any large piece of computer software such as the GNO/ME system, bugs are sure to turn up, no matter how much testing is performed on the software before it goes out the door. If you discover a bug in GNO/ME, we'd like to hear about it. There are several things we require, however, to make bug reports useful to us.
First of all, we need a complete description of your computer system; how much RAM, what cards, in what slots, what type of disk storage, etc. This information is very important in tracking down hardware-dependent bugs. Also, we need to know the version numbers of the software involved; the GNO Kernel, the GNO Shell, and any utilities.
Second, we need a step-by-step description of how to duplicate the bug. If this requires writing down individual keystrokes, then we need it. Only in this way can we decide whether the bug is hardware dependent or global.
You can send bug reports to any of the electronic mail addresses listed on the 'Credits' page, or by mailing a disk containing a description of the problem and the necessary software and files to the Procyon address.
User Projects
If you're working on a project which utilizes GNO/ME in some way, we'd like to know about it. Just contact us by mail, phone, or whatever is most convenient for you, and tell us about your project. If possible, we'll coordinate your efforts with those of other programmers. If we really like your project and think it may be useful to others, we may include it on the next GNO/ME distribution!
Software Piracy
If you copied GNO/ME from someone and are now reading this, take a moment to reflect on what you've done. GNO/ME is a project that has consumed around three man-years of effort, huge amounts of money, and a lot of grief on our part. The kernel alone consists of over 18,000 lines of source code; the shell and utilities make up another twenty to thirty thousand lines.
Is it right that you're now benefiting from our effort without any just compensation to the authors and Procyon, Inc.? We are Apple II programmers born, bred and raised in the spirit of the machine; we love to program it, and probably always will. But if we cannot make enough money to make it worthwhile to continue work on GNO/ME, then we won't; because by worthwhile, we mean not only food on the table, but resources for expansion; expansion of our IIgs product line and support to IIgs owners being abandoned by the rest of the industry. In short, support us and we'll support you.
GNO/ME is very inexpensive when you consider what it allows you to do, and what it will allow you to do when software development for GNO/ME starts full-swing. And it's a small price to pay indeed for our loyalty to you, the IIgs owner.
To all you GNO/ME purchasers out there: thank you very much. We will continue to provide you with new IIgs products until our hair and teeth fall out, and our fingers are too frail to type the keys (and even then, with Easy Access, we might crank out a program or two). We hope you will be sufficiently impressed with the system to recommend it to others.
p.s. Remember - if someone comes up to you on the street and offers you some IBM, Just Say GNO!
Preface
Computers are tools. The flexibility of a tool determines how useful it is. Early computers were much like the one this software was written for: the Apple IIgs. They could only run one program at a time, and their usefulness was limited to what the particular program the user was executing offered. In the late 1960's, a team of researchers at AT&T began developing the UNIX operating system. The UNIX design was partially based on the premise that most programs are I/O bound, that is, most of the time the program executes is spent waiting for user input or other I/O operations. While one program is waiting for I/O, why not allow another program to execute? This is what they did, and the result was one of the most successful computer operating systems ever created.
The Apple IIgs, like the Macintosh it is modelled after, provides very limited multitasking abilities in the form of desk accessories (NDAs). The programs in the NDA menu are available in whatever application you use as long as it follows Apple's guidelines. However, there are many graphics based programs that don't support NDAs, and in addition there is a wealth of software that has been developed for the Byte Works' ORCA environment. This environment is mainly text-based, and thus makes access to NDAs impossible. As if that wasn't enough, it's very difficult to write an NDA to allow the application to keep running concurrently. So the benefits are lost, and we're back at ground zero.
Enter the GNO Multitasking Environment. What was once just dreamed about is now a reality. GNO/ME provides an environment that is almost entirely compatible with software developed for the ORCA environment. But GNO/ME also provides a wealth of new abilities, lots of new ground for developers and users alike.
Before we begin describing, we'd like to respond to those who say such a multitasking system isn't possible on the Apple IIgs. Obviously it is: you hold it in your hands. Some say the Apple IIgs isn't powerful enough to make multitasking useful. We point out that the Apple IIgs is much more powerful than the first computers UNIX was designed to run on; they only had 64K of real memory, and were 16 bit machines. Some ask why you'd ever need to run more than one program at once. These are the same people who asked why we'd ever need more than 64K of memory, or more than 140K of storage on disks (end soapbox).
Introduction
The GNO Multitasking Environment provides pre-emptive multitasking. Many programs can be executing at the same time; each is called a 'process'. Each process is allowed to run for a short period of time (1/20th of a second on average). When its time runs out, the current process is set aside and another one chosen to run next. This cycle continues until there are no more processes left (i.e. when you exit GNO/ME). Starting up processes to run 'in the background' is a simple matter of adding a few characters to the shell commands.
GNO/ME provides a shell that takes full advantage of the multitasking ability provided. The most important feature of the shell is job control (starting, terminating, and suspending processes). But the shell also provides power never before seen on the Apple IIgs. The ability to choose files by 'wildcard' has been around for a while, but the GNO Shell takes this to a new level with 'regular expressions', a very powerful yet simple programming language. Other benefits of the GNO shell are too numerous to mention. (see the GNO Shell User's Manual for details).
In addition to being compatible with the ORCA system, GNO/ME is a very powerful programming environment. Available to the programmer are all the calls needed to control processes, support Inter-Process Communication, and other tools needed in a multitasking environment.
GNO/ME also boasts the first completely consistent method for accessing serial and console I/O. The IIgs TextTools have been incredibly enhanced to provide a truly all-encompassing interface for serial, console, and IPC applications. Imagine being able to attach terminals to your GS, and have a useful shell in each one. Multiuser BBSs, remote dial-ups, UUCP or SLIP that doesn't take over your computer- the applications are endless!
With all this talk of shell utilities, have desktop users (users of programs like AppleWorks GS) been left behind? Absolutely not. GNO/ME doesn't allow more than one desktop program to run concurrently, but it DOES let you run a desktop program with as many text applications as you like. In other words, no functionality is lost from the IIgs by using GNO/ME.
Finally, the GNO Multitasking Environment comes with a large number of free utilities that bring some of the power of a UNIX system to the Apple IIgs. Also, a number of programming libraries are included that make it easy to port programs from UNIX or MS-DOS systems to the Apple IIgs.
The GNO/ME package
Included in your GNO/ME Version 2.0 package are:
Hardware Requirements
GNO/ME will work on any Apple IIgs with at least 2 MegaBytes of memory and a hard drive.
You should have at least 5 MegaBytes of hard disk space free.
We recommend 4 MegaBytes of Memory and an accellerator card, especially if you will be using GNO with many background processes. A modem and access to an on-line service will greatly speed access to technical assistance and new utilities as they are made available.
Installation
GNO/ME is a very large system. Most of the system is stored on the three disks in a compressed format. For this reason we recommend that you read this section carefully and use the included automated installation program to save yourself the major headache of arranging everything. You'll need a hard drive partition with at least 5 Megabytes free to install GNO/ME. The entire installation process should take no longer than 10 minutes.
If you are upgrading from GNO 1.0 to GNO 2.0, we recommend that you install GNO 2.0 on a new area of your hard drive. This is because GNO 2.0 provides new versions of almost all the utilities and other software provided with GNO 1.0. You can then move the parts of your old system that aren't a part of the standard GNO 2.0 distribution over to the new installation.
The installer program is able to the copy the GNO libraries for use with the ORCA languages and tools. If you want to use your ORCA languages and tools, you should answer the appropriate questions during the install process. ORCA installation is covered in more detail below.
Step 1:
Step 2:
Step 3:
Do you have existing Byteworks (ORCA) language products?
If you use Byteworks language products such as ORCA/C, ORCA/M, ORCA/Pascal, etc. and wish to use them from GNO/ME then answer 'Yes' to this question. Otherwise, answer 'No'.
Clicking on the 'Info' button will display the following text:
If you currently use products such as ORCA/C, ORCA/Pascal, ORCA/M, etc., and wish to use them from GNO/ME then you should answer 'Yes' to this dialog.
Install will then ask you to locate the file "ORCA.SYS16" (the ORCA Shell). Usually, it will be in a directory called "ORCA" on one of your hard drive partitions. On our system, it is :software:orca. The location of this file determines where Install puts the GNO-specific ORCA/C header files and libraries (in the ORCA LIBRARIES directory). If you have renamed ORCA.SYS16 to something else, select that instead.
Install uses this information to correctly set the ORCA prefixes and add the EXECUTABLES directory to the $PATH variable in your gshrc file. See the GNO Shell User's Manual, Appendix B, for more information on the ORCA prefixes.
Do you want to install the modified ORCA/C 2.0 ORCALIB library?
If you have ORCA/C 2.0 installed and you answered 'Yes' to the previous question, then you should answer 'Yes' now. If you have ORCA/C 1.3 installed, or you do not have any ORCA languages or tools, then you should answer 'No'.
Clicking 'Info' will display the following text:
GNO/ME 2.0 comes with a modified version of the ORCA/C ORCALIB standard library. This library adds specific support for some of GNO's special files (pipes, terminals, etc) transparently and corrects other problems the standard ORCALIB has with GNO.
This special ORCALIB is only for use with ORCA/C 2.0. It will NOT work with previous versions of ORCA/C.
Note that all of GNO's other libraries (libgno, libbsd, libc) work fine with ORCA/C 1.3.
Do you want to install the Multi-User package?
If you wish to have the Multi User package installed, answer 'Yes'. It is recommended that new users do not install this package until they are familiar with the system. This package is not fully discussed in the GNO/ME manuals and may introduce many unfamiliar concepts.
Clicking 'Info' will display the following text:
The 'Multi-User' package consists of a number of cooperating programs, including init(8) and login(8). MU provides for password-protected access to the GNO Shell via the console or serial ports (modems and dedicated terminals). It also handles multiple user accounts, and a certain level of protection between users.
If you will be using a terminal with GNO, or want to be able to dial into GNO with a modem, you should install MU.
You may wish to hold off setting up the Multi-User package until you learn your way around GNO a little better, as it's simple to set up MU later.
Step 4:
If the installer cannot finish it's tasks for some reason, it will abort to the shell. At this point you should study the error messages to determine the cause of the failure,
Step 5:
That's all!
What has been installed?
If you examine the directory that you chose for GNO/ME, you will find that the Installer has created several directories. Here is a brief rundown of thier contents:
Desk Accessories
The following is a description of the desk accessories that are shipped with GNO/ME.
GSI NDA
The Graphical Shell Interface New Desk Accessory allows you to access the shell from a window inside a desktop application. Selecting 'GSI' from the Apple menu opens a window and brings up a shell in it. You can use the shell in this window just as you would in text mode.
At this time, GSI doesn't support any terminal emulations; i.e., it's a 'dumb' interface. As a result, full screen programs like 'less' and 'vi' will not work properly in GSI.
Suspend NDA
The Suspend New Desk Accessory allows you to temporarily stop a desktop program and return to the text shell. To return to the desktop program, simply type 'fg'.
You may put desktop programs in the background ('bg') at your own risk. This is not guaranteed to work for all programs, and putting a desktop program in the background will not put the Apple IIgs in text mode.
Also, do not run another desktop program when one is currently suspended. The GNO kernel tries to cleanly terminate the second program, but may not always be able to accomplish this.
GNO Snooper CDA
The GNO Snooper CDA is a utility that is very helpful in debugging software, and reporting system crashes. Snooper has access to information inside the kernel that is not generally available to processes.
When you enter the control panel and choose "GNO Snooper" a process list is displayed, which is very similar to the 'ps' shell command, and a menu is presented with the following options:
D)etails
Get detailed information on a process. Snooper asks you for the process ID number of the process you want to investigate. Snooper then dumps the state of the 65816 registers and shows various other information about the process.
K)ill
This option sends a SIGKILL (signal number 9) to a process. Just type in the process ID of the process you want to kill.
P)rocess Group Dump
Dumps the system process group tables, which is very useful for debugging code which manipulates process groups. The first table, 'pgrp', is the process group reference count table. This table lists how many processes (and TTYs) belong to that process group. pgrp ID's start at 2, so the first pgrp listed is 2.
The second listing is the ttyStruct table. This table shows which pgrp each TTY belongs to. The TTYs start with .null (0), then move on to .ttyb, .ttya, .ttyco, etc.
F)ile Table Dump
Lists all open files that GNO knows about. The information is presented in tuples. The first element is the real GS/OS refNum or device driver ID. The second is the type of file (GSOS, ttyXX, or PIPE). The third is how many references to that file are open. This information is global, so if two processes have .NULL opened, the refcount for .tty00 will be 2.
Reading List
Recommended Reading for Users
Title: Learning Unix
Author: James Gardner
Publisher: Sams
Edition: 1991
ISBN: 0-672-30001-X
Comment: With disks containing MSDOS simulation of Unix (MKS Tools). A good tutorial / reference book for those without constant access to Unix.
Title: The Unix Operating System
Author: Kaare Christian
Publisher: Wiley
Edition: 2nd ed. 1988
ISBN: 0-471-84781-X
Comment: A classic overview of Unix commands. Good in coverage.
Title: Peter Norton's Guide to Unix
Authors: Peter Norton and Harley Hahn
Publisher: Bantam Computer
Edition: 1991
ISBN: 0-553-35260-1
Comment: Good coverage. A good introduction for beginners (especially those accustomed to DOS).
Title: Unix in a Nutshell
Authors: Daniel Gilly and O'Reilly staff
Publisher: O'Reilly
Edition: 2nd ed. 1992 (System V and Solaris 2)
ISBN: 1-56592-001-5
Comment: **** Highly Recommended **** An excellent desktop reference to almost all Unix commands "a complete reference containing all commands and options, plus generous descriptions and examples that put the commands in context." Also, an edition for 4.3. BSD.
Title: Life with Unix - A Guide for
Everyone
Authors: Don Libes and Sandy Ressler
Publisher: Prentice Hall
Edition: 1990
ISBN: 0-13-536657-7
Comment: **** Highly Recommended **** An everything-you-want-to-know-about-Unix book. It includes info you might not find elsewhere. "This book is the "other" book about Unix, a study in reading between the lines - which is very much what learning UNIX is like."
Title: Unix for the Impatient
Authors: Paul Abrahams and Bruce Larson
Publisher: Addison Wesley
Edition: 1992
ISBN: 0-201-55703-7
Comment: **** Highly Recommended **** A new, comprehensive, in-depth reference to Unix. "a handbook you can use both as a manual to learn UNIX and as a ready reference for fast answers to specific UNIX questions."
Title: Learning the vi Editor
Author: Linda Lamb
Publisher: O'Reilly
Edition: 1990
ISBN: 0-937175-67-6
Comment: A very good guide to vi and ex commands. With a quick reference card.
Titles: vi Tutor and vi Reference
Authors: Michael Pierce and Robert Ware (Tut), Maarten Litmaati
(Ref)
Edition: 1.3 (Tut), 8 (Ref)
Comment: These and other good vi stuff are obtainable by anonymous ftp from cs.uwp.edu (in pub/vi) ...
Recommended Reading for Programmers
Title: The Design and Implementation of the
4.3 BSD Unix Operating System
Authors: Samuel Leffler et al
Publisher: Addison-Wesley
Edition: 1990
ISBN: 0-201-06196-1
Comment: An authoritative description of the design of BSD Unix. "It covers the internal structure of the 4.3BSD system and the concepts, data structures, and algorithms used in implementing the system facilities."
Title: The Unix Programming Environment
Authors: Brian Kernighan and Rob Pike
Publisher: Prentice-Hall
Edition: 1984
ISBN: 0-13-937681-X
Comment: A true classic on Unix programming.
Title: Advanced Programming in The Unix
Environment
Author: Richard Stevens
Publisher: Addison-Wesley
Edition: 1992
ISBN: 0-201-56317-7
Comment: **** Highly Recommended **** A going-to-be classic on how programs work under Unix. The source codes and errata list are obtainable by anonymous ftp from ftp.uu.net (in /published/books).
Title: Advanced Unix Programming
Author: Marc Rochkind
Publisher: Prentice Hall
Edition: 1985
ISBN: 0-13-011818-4
Comment: A superb book covering all system calls in detail.
Title: Using C on the Unix System
Author: David Curry
Publisher: O'Reilly
Edition: 1990
ISBN: 0-937175-23-4
Comment: This book is directed to (would-be) system programmers.
Required Reading for Programmers
Title: The C Programming Language
Authors: Brian Kernighan and Dennis Ritchie
Publisher: Prentice Hall
Edition: 2nd ed. 1988
ISBN: 0-13-110362-8
Comment: The answers to the exercises can be found in C Answer Book written by Tondo and Gimpel and published by Prentice Hall (ISBN: 0-13-109653-2).
All the books listed below are available from:
Resource Central
PO Box 11250
Overland Park Kansas 66207
(913) 469 6502
Title: Apple IIgs ToolBox Reference.
Volumes 1, 2 & 3
Author: Apple Computer
Publisher: Addison-Wesley
Title: Programmers Reference for System 6.0
Author: Mike Westerfield
Publisher: Byteworks, Inc
Title: Apple IIgs Firmware Reference
Author: Apple Computer
Publisher: Addison-Wesley
Title: GS/OS Reference
Author: Apple Computer
Publisher: Addison-Wesley