Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!news-out.cwix.com!newsfeed.cwix.com!newshub.northeast.verio.net!news.he.net!feeder.via.net!newshub1.home.com!news.home.com!news1.rdc1.ab.home.com.POSTED!not-for-mail
From:
[email protected] (Devin Reade)
Newsgroups: comp.sys.apple2.gno,comp.answers,news.answers
Subject: comp.sys.apple2.gno FAQ (v1.18)
Supersedes: <
[email protected]>
Followup-To: comp.sys.apple2.gno
Organization: Myrias Computer Technologies Corp
Lines: 2693
Sender:
[email protected]
Approved:
[email protected]
Distribution: world
Expires: 12/11/99 17:20:02
Message-ID: <
[email protected]>
Reply-To:
[email protected] (Devin Reade)
Summary: Contains information on the UNIX-like OS for the Apple IIgs.
Keywords: FAQ, GNO, Apple-II, UNIX, ORCA
X-Content-Currency: This FAQ changes regularly. When a saved or printed copy
is over 6 months old, please obtain a new one. Instructions in the
preamble indicate where to find them via NetNews, FTP, and the WWW.
Date: Sun, 07 Nov 1999 00:20:12 GMT
NNTP-Posting-Host: 24.64.124.43
X-Complaints-To:
[email protected]
X-Trace: news1.rdc1.ab.home.com 941934012 24.64.124.43 (Sat, 06 Nov 1999 16:20:12 PST)
NNTP-Posting-Date: Sat, 06 Nov 1999 16:20:12 PST
Xref: senator-bedfellow.mit.edu comp.sys.apple2.gno:7160 comp.answers:38387 news.answers:170492
Archive-name: apple2/GNO-faq
Last-modified: 06 May 1998 05:12:23
Version: 1.18
URL:
http://www.gno.org/~gno/FAQ.html
Posting-Frequency: monthly
This is the Frequently Asked Questions (FAQ) posting of the
comp.sys.apple2.gno newsgroup. This document can be freely copied so
long as
1. it is not sold (although it may be included in commercial
distributions of Apple II archives such as the Golden Orchard
CD series); and
2. any sections reposted elsewhere from it are credited back to
this FAQ with the FAQ's copyright info and official FTP and
WWW location left in place.
Explicit permission is granted to carry this FAQ on electronic forums
dealing with Apple II computers such as BBSs and service providers
such as Genie and Delphi.
This FAQ is available via ftp and on the WWW at
ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/faq/CURRENT
http://www.gno.org/~gno/FAQ.html
A summary of recent updates may be found at
ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/faq/LOG
http://www.gno.org/~gno/FAQ-log.html
This FAQ may also be found in archives of comp.answers and news.answers,
such as those at rtfm.mit.edu.
The question numbers in this FAQ are auto-generated. Therefore, when
referring to questions in this FAQ, please either give the version number
of the FAQ or (preferably) give some context that identifies to which
question you refer.
The FAQ was originally maintained by C. Matthew Curtin,
<
[email protected]>. It contains contributions (intentional
or otherwise) from many users of GNO.
The FAQ is currently maintained by Devin Reade, <
[email protected]>.
Questions, comments, suggestions, and submissions to this FAQ are welcome
and should be emailed to Devin Reade or posted to comp.sys.apple2.gno.
This FAQ is undergoing active development. Consequently, some questions
may have annotations starting with three asterisks ("***"). These are
questions that are in the process of having their answers written or
modified.
In the event that this FAQ appears to be abandoned, someone else is
welcome to take it over as the official maintainer or to use this FAQ
as the basis for a new one, provided that you credit the previous
maintainers. The criteria for abandonment are:
1. The FAQ has not been updated nor posted to comp.sys.apple2.gno
for a period of at least six months;
2. Attempts to contact the current maintainer (Devin Reade)
have failed. You must try for a period not less than 30
days, and you must try contacting the maintainer through
email, and postings to comp.sys.apple2.gno and the Delphi
(delphi.com) Apple II Programmers' Forum.
In addition, please ensure that there is a general consensus on
comp.sys.apple2.gno that the FAQ is indeed abandoned before you attempt
to take it over. I have not included this as a criterion since a
"general consensus" is difficult to quantify in any practical sense.
Table of Contents
=================
General
^^^^^^^
Q#1.1: What is GNO?
Q#1.2: What is the status of GNO?
Q#1.3: What is the current version of GNO?
Q#1.4: What are GNO's minimum system requirements?
Q#1.5: Where can I get GNO?
Q#1.6: What support is available for GNO?
Q#1.7: Where can I get the files/archives recommended in this FAQ?
Q#1.8: Why is this FAQ written in such a drab format?
Compatibility
^^^^^^^^^^^^^
Q#2.1: With what standard version of UNIX is GNO compatible?
Q#2.2: Can I run ORCA/Shell from GNO (or vice-versa)?
Q#2.3: Is GNO compatible with the SecondSight VGA card?
Q#2.4: Are desktop applications compatible with GNO?
Q#2.5: Can I use prizm (the ORCA desktop environment) with GNO?
Q#2.6: What new features are expected to be in the next version
(2.0.6)?
Documentation
^^^^^^^^^^^^^
Q#3.1: What documentation comes with GNO?
Q#3.2: What additional documentation is recommended for GNO?
Q#3.3: What are all the numbers in parenthesis following program
names?
Q#3.4: I've just finished writing a new program (or library or
whatever). What documentation should I include?
Q#3.5: I'm writing a manual page. What format should I use?
Q#3.6: What should be in a manual page?
Q#3.7: Man(3) is too slow when formatting pages. Can I speed it up?
Q#3.8: What are the standard manual page chapters?
Programs
^^^^^^^^
Q#4.1: What other programs come with GNO?
Q#4.2: Are there any ftp sites for GNO utilities?
Q#4.3: I cannot ftp to caltech or ground. How can I get the GNO
utilities?
Q#4.4: What is the most recent version of program XXXXXX?
Q#4.5: Which editor should I use?
Q#4.6: What command line flags does gsh(1) accept?
System Installation
^^^^^^^^^^^^^^^^^^^
Q#5.1: For what are the various directories used?
Q#5.2: What should be in my gshrc file?
Q#5.3: Where should I install custom additions to GNO?
Installing GNO with ORCA
^^^^^^^^^^^^^^^^^^^^^^^^
Q#6.1: Do I need separate installations of ORCA/C for use with GNO
and ORCA/Shell?
Q#6.2: How do I set up ORCA/C so that I can use it with GNO?
Q#6.3: GNO with ORCA: What should I use for compilation directories
and prefixes?
Q#6.4: GNO with ORCA: Where should my C header files go?
Q#6.5: GNO with ORCA: What goes in the 13/orcacdefs/defaults.h
file?
Q#6.6: GNO with ORCA: What header file modifications are necessary?
Q#6.7: GNO with ORCA: What libraries are used for the combination
of GNO v2.0.4 and ORCA/C v2.0.x?
Q#6.8: GNO with ORCA: What libraries are used for the combination
of GNO v2.0.4 and ORCA/C v2.1.x?
Q#6.9: GNO with ORCA: What libraries are used for the combination
of GNO v2.0.6 and ORCA/C v2.0.x?
Q#6.10: GNO with ORCA: What libraries are used for the combination
of GNO v2.0.6 and ORCA/C v2.1.x?
System Configuration
^^^^^^^^^^^^^^^^^^^^
Q#7.1: What patches should I have applied for GNO?
Q#7.2: How do I change the information that's printed before the
login prompt?
Q#7.3: How do I map /usr, /local, /var, and other partitions to
GS/OS volume or directory names?
Q#7.4: How do I set up cron?
Q#7.5: Why won't my entry in the inittab file work correctly?
Networking
^^^^^^^^^^
Q#8.1: Does GNO provide TCP/IP and/or SLIP support?
Q#8.2: Is GS/TCP available? Where can I get it?
Q#8.3: Does Marinetti work with GNO?
Q#8.4: What TCP/IP network utilities are available?
Q#8.5: Is there a WWW browser for GNO and GS/TCP?
Q#8.6: Can I use a serial card or internal modem with GNO?
Q#8.7: What should I use for my modem port control panel settings.
Q#8.8: How can I initialize my serial ports at GNO "boot" time?
Q#8.9: How do I hook up a terminal to the IIgs' printer/modem port?
Q#8.10: How do I enable GNO to activate dialup access.
Q#8.11: What do I use for a ProTERM termcap entry?
Q#8.12: Is there a mail/news package available for GNO?
Q#8.13: How do I use copycat?
Q#8.14: How do I use rz/sz?
Q#8.15: Why do I get errors when trying to access the (modem/serial)
port?
Porting UNIX Programs to the GNO Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Q#9.1: What programs/utilities should I have to port UNIX source
code to GNO?
Q#9.2: What are the common problems encountered when porting UNIX
source to GNO?
Q#9.3: Are there any other recommendations for porting programs?
Compiling
^^^^^^^^^
Q#10.1: Which language should I use?
Q#10.2: Should I purchase the ORCA Subroutine Library Source?
Q#10.3: What is occ?
Q#10.4: What is dmake?
Q#10.5: What macros should I be using for conditional compilation?
Q#10.6: When I'm using the new header files (post-v2.0.4), sometimes
ORCA/C can't find my header files. Why?
Libraries and Header Files
^^^^^^^^^^^^^^^^^^^^^^^^^^
Q#11.1: I keep getting "va_end" as an unresolved symbol when
linking. Why?
Q#11.2: Why do I keep getting "getc" and "putc" as unresolved
symbols when linking?
Q#11.3: How can I tell what order my libraries are in?
Q#11.4: How can I sort my libraries (or other files)?
Q#11.5: How can I tell what is in library XXXX?
Q#11.6: Why isn't the common function XXXX in the libraries?
Q#11.7: Function XXXX is declared in the GNO header files, but it's
not in the libraries. Why?
Q#11.8: I want to release my library to the GNO community. Is there
anything in particular that I should do?
Q#11.9: How do I get the file descriptor from a stdio FILE pointer?
Q#11.10: My (ported) source requires <sys/file.h>. Why isn't it
there?
Q#11.11: Why, when I '#include <types.h>' (or some other file), does
the compiler take it out of my current directory instead of
out of the system header directories?
Q#11.12: When using the December 1997 libraries (or later version),
why are my programs larger than they used to be?
Kernel Internals
^^^^^^^^^^^^^^^^
Q#12.1: Can task-switching occur during an interrupt?
Q#12.2: Can I tell GNO/ME to not task switch during a short (like a
couple of ASM instructions) sequence?
Debugging (During Program Development)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Q#13.1: What debuggers are available for GNO?
Q#13.2: Why is the Splat! debugger crashing when my code calls
fork(2)?
Q#13.3: Part way through my debugging session, Splat! no longer
shows my source file. Why?
General Problems
^^^^^^^^^^^^^^^^
Q#14.1: Some programs I run have two cursors and sometimes
characters I type don't get sent to the program. When I quit
the program, the characters show up on the command line!
What's wrong?
Q#14.2: Whenever I try to launch the Finder from GNO, I am told that
the Finder needs more memory. I know there is enough memory
available. What's the deal?
Q#14.3: My program is crashing when calling open(2). Why?
Q#14.4: What are the known bugs?
General
-------
Q#1.1: What is GNO?
A#1.1: GNO is a UNIX-like multitasking environment for the Apple IIGS.
GNO provides:
1. Pre-emptive multitasking.
2. A shell that takes full advantage of the multitasking provided
(i.e., job control), and 'regular expressions', and a simple
programming language.
3. A powerful programming environment. All the calls needed to
control processes, support Inter-Process Communication (IPC),
and other tools necessary to support multitasking are
available to the programmer.
4. The first completely consistent method for accessing serial
and console I/O on the Apple II. This makes such things as
attaching terminals to your GS, multiline BBSes, remote
dial-ups, UUCP or SLIP that doesn't take over your computer,
as well as countless other applications a possibility.
Q#1.2: What is the status of GNO?
A#1.2: GNO was developed by Procyon Enterprises (Jawaid Bazyar, prop.).
Until August 1997, GNO was a commercial product. In August 1997,
Jawaid changed GNO's status to that of freeware. Procyon still
retains the copyright on the kernel, gsh, and other components
which were written by or for Procyon.
GNO IS NOT PUBLIC DOMAIN.
Q#1.3: What is the current version of GNO?
A#1.3: The currently released version is v2.0.4. The version currently
under development is v2.0.6. v2.0.5 never had a general release,
and is not available.
For those programmers using ORCA/C v2.1.x, there was a update made
available (for both GNO v2.0.4 and GNO v2.0.6 users) on 22 Dec 97.
It consists of updated headers, libraries, and manual pages. It
is available at the following site:
ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base206
Q#1.4: What are GNO's minimum system requirements?
A#1.4: The GNO documentation specifies that the minimum requirement
is an Apple IIGS with 1.25 MB of memory and a 3.5" disk drive.
Realistically (especially with all the third-party add-ons),
a hard drive (or other large mass storage device) should be
considered a necessity. An accelerator and additional memory
is recommended.
There is not an official "minimum disk space" requirement
as yet. When this information becomes available, it will
be added to this FAQ.
Q#1.5: Where can I get GNO?
A#1.5: The base GNO distribution may be obtained via anonymous ftp
from the following sites. See also Q#1.7:
ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base204
ftp://ftp.hypermall.com/pub/gno
The documentation for GNO v2.0.4 is now available via ftp and
http at the following sites. MS-Word versions are also available
via ftp:
http://www.gno.org/~gno
ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc
ftp://ftp.hypermall.com/pub/gno/docs
For those who aren't able to make decent printed copies of the
documentation on their own, Procyon still offers the printed
documentation for sale. (Do *NOT* ask Devin Reade for the
printed documentation. He does not work for Procyon and does
not sell it.) At last check, this is the Kernel Reference Manual,
the GSH Reference Manual, selected manual pages, and the release
and installation notes. This contents list is unofficial and
subject to correction by Procyon.
Procyon Enterprises Inc maintains a web page at:
http://www.hypermall.com/companies/procyon
or you can contact them by snail-mail at:
Procyon, Inc.
P.O. Box 620334
Littleton, CO 80162-0334
303/933-4649
Q#1.6: What support is available for GNO?
A#1.6: For the most part, the only support available is that given
by GNO developers in the Apple II community. In other words,
what you get is what you get. Often a polite question posted
to comp.sys.apple2.gno will result in a helpful response.
Procyon still offers limited support for people who purchased
GNO prior to August 1997. No support is available from Procyon
for those who obtained GNO after it changed to freeware status.
There is a group of programmers (known as the gno-devel list)
working toward getting v2.0.6 out the door. Information regarding
this work will be posted to comp.sys.apple2.gno as it becomes
available. Have patience; we all have day jobs and this is
a hobby.
Q#1.7: Where can I get the files/archives recommended in this FAQ?
A#1.7: The "core" files of the GNO distribution (such as the GNO
kernel and gsh(1)) are available through anonymous ftp as
described in Q#1.5.
Non-commercial files, unless otherwise specified, should be
available from major Apple ftp sites. There is often a GNO-
specific directory, but compatible programs, patches, etc,
may appear anywhere under the Apple II hierarchy. The GNO
distribution also contains many files in this category;
ensure you have newest versions by checking the ftp sites.
The three main Apple II sites are
ftp://apple2.caltech.edu/Zocalo/pub/apple2
ftp://ground.isca.uiowa.edu/apple2
ftp://ftp.gno.org/pub/apple2
The latter (also known as trenco.gno.org) is the master site for
GNO development, as of August 1997. GNO-specific files can be
found in the /pub/apple2/gs.specific/gno directory on ftp.gno.org.
Other sites are listed in the comp.sys.apple2 FAQ, which is
available from the above two sites and
http://www.visi.com/~nathan/a2/faq/csa2.html
Q#1.8: Why is this FAQ written in such a drab format?
A#1.8: Because it was considered critical that there is a easily
readable text-only version available. Combined with the fact
that the maintainer didn't want to spend a lot of time with
source translators, this placed a restriction on the type
of formatting available.
Compatibility
-------------
Q#2.1: With what standard version of UNIX is GNO compatible?
A#2.1: GNO contains components that originate with a variety of
flavors of UNIX. These include 4.3BSD, XINU, and SYSV.
It is mostly BSD. As of GNO v2.0.6, GNO has become closer
to 4.4BSD. Work is in progress to make it as compliant as
possible to POSIX 1003.1 and POSIX 1003.2.
Q#2.2: Can I run ORCA/Shell from GNO (or vice-versa)?
A#2.2: No. GNO with a shell (such as gsh) is intended to be a replacement
for ORCA/Shell. Similarly, one cannot run GNO from ORCA/Shell.
However, you can still use the various ORCA languages and (the
majority of) utilities from GNO. See the sections on "Programs"
and "Compiling", below.
Q#2.3: Is GNO compatible with the SecondSight VGA card?
A#2.3: Yes. GNO is completely compatible with the SecondSight card.
However, GNO's console driver currently does not support the
SecondSight card's VGA specific text modes. A SecondSight aware
console driver is planned as a future enhancement.
Q#2.4: Are desktop applications compatible with GNO?
A#2.4: In most cases, yes. However, GNO doesn't currently allow more than
one desktop program to run concurrently. It does allow you to
run multiple text applications with or without a desktop application,
to the limits of your available memory.
There is a program (also available from Procyon), called Switch-It!,
that allows one two switch between running desktop programs.
It is not multitasking (in that only the currently displayed
desktop program is actually running), nor does it _require_
GNO. It is, however, complementary to and compatible with GNO.
Other (text based) processes running in the background continue to
do so when Switch-It! is active.
Q#2.5: Can I use prizm (the ORCA desktop environment) with GNO?
A#2.5: In a nutshell, no. The exact reasons are not generally known,
but the author (Mike Westerfield) does not ever expect to have
a compatible version available.
Q#2.6: What new features are expected to be in the next version (2.0.6)?
A#2.6: This list is unofficial and subject to change. With that in mind:
- Complete kernel support for TCP/IP.
- Lots of little bug fixes that should improve stability.
- An updated and expanded libc.
- An OrcaLib compatible with the ORCA/C v2.1 OrcaLib.
- Updates to various shell programs.
Documentation
-------------
Q#3.1: What documentation comes with GNO?
A#3.1: GNO/ME Overview
Kernel Reference Manual
Shell (gsh) User's Manual
Manual Pages (some printed, all online)
Online versions of these documents are also available. See Q#1.5.
Q#3.2: What additional documentation is recommended for GNO?
A#3.2: The GNO Overview has quite a complete reading list for users and
programmers, and it is too long to go into detail here. However,
in general, the references are broken down into the following
categories:
- UNIX reference books.
- C reference books.
- Editor reference books.
- Apple IIgs Programming References
The following list, should also be considered "must have" for
any serious programming:
- The ORCA/C and/or ORCA/M manuals, as appropriate.
- Toolbox volumes 1, 2, 3
- Programmers' Reference for System 6.0/6.0.1
- GS/OS Reference
- Firmware Reference
- Apple Technical Notes
- Apple File Type Notes
- A manual on 65816 assembly programming, if you are
using assembly. One very good manual is:
Lichty, Ron and Eyes, David. _Programming_the_IIgs_
_in_Assembly_Language_, Brady, 1989.
ISBN 0-13-729559-6
You will likely have to get it second hand, as it is no
longer in print.
The following books are recommended:
- Hardware Reference
- Apple Numerics Manual
- Device Driver Reference
- IEEE Std 1003.1-1988 (or later) -- The POSIX standard
for computer environments.
- ANSI/ISO 9899 Standard (defines ANSI/C).
This is an expensive document, but you get a cheap copy
by purchasing Schildt, Herbert _The_Annotated_ANSI_
_C_Standard_, McGraw-Hill, ISBN 0-07-881952-0. The book
is set up so that the standard is printed on the "left"
pages and the annotations are on the "right" pages.
MAKE SURE YOU USE ONLY THE LEFT PAGES; the annotations
have just enough errors in them to be dangerous. Some
of the "left" pages (from the Standard) are also missing.
Q#3.3: What are all the numbers in parenthesis following program names?
A#3.3: When you see something like "ls(1)" in the documentation, it
refers to something called "ls" which is documented in Chapter 1
of the manual pages. Similarly, "select(2)" is refering to
something called "select" which is documented in Chapter 2. To
find out what the various chapters are for, type in the command
man 4 intro
substituting "4" for whichever chapter you wish to learn about.
Q#3.4: I've just finished writing a new program (or library or whatever).
What documentation should I include?
A#3.4: Including the following documentation components will not only
help anyone who is maintaining a GNO site, but they will also
make your contribution look more professional. Remember, if
someone can't tell what your program is supposed to do, they
are less likely to try it out.
You should have:
- A manual page (see also Q#3.5). Unless your program requires
a large reference manual ( > 5-10 pages of written text), the
manual page should be the primary document.
Ensure the man page is assigned to the correct section. One
common mistake is to mix up Section 1 (User Commands) with
Section 8 (System Administration).
- A describe(1) database entry. Try to use the ".desc" suffix
on the file name. (For example, if you wrote the "foo" program,
you should have a text file "foo.desc" containing the database
entry.) If you have WWW access, please update the online
describe database maintained by Soenke Behrens -- see Q#4.4.
The describe entry is very suitable as a brief README file
when uploading your program to ftp sites, or when posting to
comp.binaries.apple2.
Describe entries should only be written for programs, not
libraries or individual routines.
- An rVersion resource fork. If you don't want to write a rez
source file, then use setvers(1).
There is a new format out which includes rVersion as a subset.
It is called rProgramInfo (or rProgInfo), and was formalized
by Eric Shepherd. Information on this is available at the
usual ftp sites in the archive rProgInfo.shk. See also the
templates file listed later in this answer.
- "Standard" help and version flags. If possible, invoking your
program with the "-V" (capital vee) flag should print the
version number and exit. Invoking it with the "-h" flag should
print a usage (help) message and exit. Use of the "-?" flag
is discouraged because it is a meta-character in many shells.
It may not be practical to support these two flags, such as
if you are porting a program that already uses them for other
purposes, or if you are writing a daemon.
To make things easier, templates for manual pages, rVersion
source files, and describe database entries are available at
the usual sites. Look for an archive with a name similar
to
templates[version_number].shk
Q#3.5: I'm writing a manual page. What format should I use?
A#3.5: While man can handle both manually-edited preformatted pages and
pages that are aroff source (created by AppleWorks-GS or a
compatible editor), the recommended format is to use nroff source
with tmac "an" extensions.
The reason for this is that only nroff source can be reformatted
"on the fly" to suit different terminal characteristics. See also
Q#3.7.
Q#3.6: What should be in a manual page?
A#3.6: Whatever is necessary. However, there are some standard sections
for manual pages, based on which section (chapter) the manual
page is in. Templates with the suggested manual page formats
are available in the file
templates[version_number].shk
at the usual ftp sites.
For programs in particular (typically Chapters 1, 6, and 8), here
are some sections that should be in the man page. The order of
the first three are mandatory due to how some automated tools
work. The sequence on the remainder are suggested:
NAME - name and one line description
SYNOPSIS - list of options and arguments
DESCRIPTION - a detailed description
OPTIONS - explanation of the flags
ENVIRONMENT - relevant environment variables and their
semantics, if appropriate
FILES - related files, if appropriate
BUGS - known bugs, if appropriate
AUTHOR - your name and contact info, typically
an email address. Include your smail
address at your own risk.
LEGALITIES - Commercial, freeware, shareware, public
domain, copyleft, ... ?
ATTRIBUTIONS - Give credit when due. For example, if
your binary was linked with the ORCA
libraries, you should be including the
Run-Time Licence from Appendix C of the
ORCA/C manual.
SEE ALSO - related manual pages or other documents
Q#3.7: Man(3) is too slow when formatting pages. Can I speed it up?
A#3.7: Actually, it's not man(3), but nroff(3) which is slow. Nroff
is in desperate need of an update, not only for speed but for
functionality.
In the interim, however, you can get a faster response from man
at the cost of using more disk space by preformatting your man
pages. See catman(8).
Q#3.8: What are the standard manual page chapters?
A#3.8: Chapter 1: Commands and Applications
Chapter 2: System Calls
Chapter 3: Library Routines
Chapter 4: Devices
Chapter 5: File Formats
Chapter 6: Games
Chapter 7: Miscellaneous
Chapter 8: System Administration
For GNO, there should be no need to use Chapter n [New Commands],
or Chapter l (ell) [Local Commands], unless (in the latter case)
the manual page is for something that is not to be released to
the GNO community.
Chapter 3F is reserved for Fortran Routines, of which there
are none at this time (due to the lack of a publicly available
Fortran compiler).
Programs
--------
Q#4.1: What other programs come with GNO?
A#4.1: Lots of free utilities that bring some of the power of UNIX systems
to the IIGS. In addition to getting the utility executable files,
you get the source for many of these. These programs have been
provided by various authors.
Q#4.2: Are there any ftp sites for GNO utilities?
A#4.2: Yes. Many Apple II ftp sites have GNO-specific directories, although
GNO stuff can also be found in other directories on these sites.
The three primary general-purpose sites are:
ftp://apple2.caltech.edu/Zocalo/pub/apple2/shellprogs
ftp://ground.isca.uiowa.edu/apple2/apple16/gno
ftp://ftp.gno.org/pub/apple2
Trenco (trenco.gno.org or ftp.gno.org) is the master site for GNO
development as of August 1997. See Q#1.7.
See the comp.sys.apple2 FAQ for other Apple II ftp sites.
Q#4.3: I cannot ftp to caltech or ground. How can I get the GNO utilities?
A#4.3: Perhaps you could use the FTP-by-mail service. Send mail to
[email protected] with the subject line of "help" and no body
for information.
Another alternative is to use the WWW to access those sites.
WWW access information is available in the comp.sys.apple2 FAQ
(see Q#1.7).
Q#4.4: What is the most recent version of program XXXXXX?
A#4.4: The best way to find out what programs are available for GNO,
including version numbers, authors, and other information is
to use the describe(1) database. The program, database, and
maintenance utilities are available at the usual ftp sites.
Soenke Behrens <
[email protected]> also maintains an online
describe database. This tends to be the most up-to-date version,
and is available at
http://www.arrowweb.com/sbehrens/describe.htm
Q#4.5: Which editor should I use?
A#4.5: Whichever one you want. Many editors work under GNO. Some
of the more popular ones are emacs (MicroEMACS), vi (Stevie),
ORCA/Editor, Edit-16, and Rose.
Many of these editors cannot be suspended from the shell. Some
have the "eating keystrokes" problem (see Q#14.1).
Q#4.6: What command line flags does gsh(1) accept?
A#4.6: There are two. The first is "-c arg", which is supposed to allow
one to specify a script on the command line. This seems to be
broken, though.
The second one is "-f", which tells gsh not to parse its gshrc
file, nor do other initialization tasks. Think of it as "fast
startup". Unfortunately, empirical tests seem to indicate that
gsh is no faster with this flag than without.
System Installation
-------------------
Q#5.1: For what are the various directories used?
A#5.1: The following is the suggested layout and use of various directories.
Any given site will likely have more, but these are the "standard"
ones. Note that these don't necessarily have to be on different
physical partitions due to the GNO namespace facility (see Q#7.3).
This FAQ assumes the following directory structure:
/HFSinclude GNO standard C header files (required if and
only if /usr/include is not on an HFS
partition)
/bin basic standard programs
/dev device drivers
/etc configuration files
/lang languages
/lang/orca ORCA languages
/lang/orca/languages compilers
/lang/orca/libraries standard ORCA libraries (not used
for GNO; see /lib instead)
/lang/orca/libraries/orcacdefs standard ORCA/C header files
/lang/orca/release.notes READMEs, release notes, etc
/lang/orca/shell ORCA editor and ORCA/Shell config files
/lang/orca/utilities ORCA/Shell compatible programs
/lang/orca/utilities/help These are the ORCA utility help files,
which show brief usage information.
The preformatted manual pages that
come with some utils should _not_ go
here.
/lang/orca/man/man1 manual pages for ORCA/Shell compatible
programs (nroff, troff, or aroff source)
/lang/orca/man/cat1 manual pages for ORCA/Shell compatible
programs (preformatted). These should not
be confused with the "help" files in
/lang/orca/utilities/help.
/lib standard GNO libraries
/lib/RInclude resource compiler include files
/lib/orcacdefs holds defaults.h; otherwise empty
/tmp scratch directory (for temporary files)
/usr UNIX system resources
/usr/X X (graphical interface) -related files
/usr/X/bin X programs
/usr/X/lib X libraries and configuration files
/usr/X/man X manual pages
/usr/bin additional standard programs
/usr/games games
/usr/games/lib game configuration files
/usr/include GNO standard C header files
/usr/lib optional libraries
/usr/lib/sendmail.d sendmail configuration files
/usr/lib/tmac nroff/troff macro files
/usr/local custom and local files
/usr/local/bin custom programs
/usr/local/etc custom configuration files
/usr/local/include custom C header files
/usr/local/lib custom libraries and configuration files
/usr/local/man manual pages for custom files
/usr/man standard manual pages
/usr/man/cat[1-8] standard manual pages (preformatted)
/usr/man/man[1-8] standard manual pages (nroff, troff, aroff)
/usr/sbin system maintenance programs
/var heavy write-use (variable) filesystem
/var/adm system administratin and log files
/var/mail user mailboxes
/var/spool spool directories for various daemons
/var/spool/lpq line printer spool directory
/var/spool/news news daemon spool directory
Q#5.2: What should be in my gshrc file?
A#5.2: Whatever you find necessary, keeping in mind that the gshrc file
is parsed whenever an instantiation of gsh is started. This implies
that a long gshrc file can slow down your system.
Here is one example of a minimal gshrc file. For formatting reasons
in the FAQ, long lines have been split with a trailing '\' on
the line to be continued. Gsh doesn't understand this syntax, so
be sure to enter them as a single line.
# set prefixes for ORCA languages (see also Q#6.3)
prefix 13 /lib
prefix 14 /tmp
prefix 15 /lang/orca/shell
prefix 16 /lang/orca/languages
prefix 17 /lang/orca/utilities
# match lower prefixes. gsh _should_ update these
# automatically, but doesn't.
prefix 2 13
prefix 3 14
prefix 4 15
prefix 5 16
prefix 6 17
# set search path -- gsh parses it backwards!
set path="/usr/games /lang/orca/utilities /usr/X/bin /usr/bin\
/bin /usr/local/bin"
export path
rehash
# search path for man pages
setenv MANPATH /man:/usr/man:/usr/local/man:/local/man:\
/usr/X/man:/lang/orca/man
# settings for occ(1):
# create *.o files instead of *.a files
setenv CCEMULATE 1
# set the if and only if you are using ORCA/C 2.0.x.
setenv CCOLD 1
Q#5.3: Where should I install custom additions to GNO?
A#5.3: Anything you add to your GNO installation beyond what is in the
base installation should go into the /usr/local hierarchy.
This will facilitate future updates, in that you will only have
to replace those directories used by the GNO base distribution,
and your customized files will not be overwritten.
There are some exceptions to this. For example, /etc/passwd,
/etc/namespace, and a few other files that have to be customized
do not and will not reside in the /usr/local hierarchy. However,
these will be kept to a minimum and will be explicitly mentioned
in future release notes.
If your installed man(1) cannot cannot handle manual pages in
more than one directory hierarchy, then you need to upgrade your
man to version 3.0 or later.
GNO v2.0.4 CAVEAT
^^^^^^^^^^^^^^^^^
When GNO v2.0.4 (and earlier versions) was released, there
was no attempt made to have users put add-ons in the /usr/local
hierarchy. Therefore, if you're currently running GNO v2.0.4
it is likely that you have a lot of custom items in /bin,
/usr/bin, /usr/man, and related directories. This is complicated
by the fact that various packages that are considered "standard"
(such as the Multiuser Update) were not part of the base GNO
v2.0.4 distribution.
If you are in this situation, then I suggest that you not
worry at this time about moving existing programs to the
/usr/local hierarchy. Instead, defer this to when GNO v2.0.6
is released. In the interim, there is nothing stopping you
from using the /usr/local hierarchy for anything new that you
download ...
Installing GNO with ORCA
------------------------
Q#6.1: Do I need separate installations of ORCA/C for use with GNO and
ORCA/Shell?
A#6.1: At least partly, yes, although it is possible to reduce duplication
to a minimum.
GNO requires modifications to some header files and libraries,
as well as the additions of others that don't come with ORCA/C.
The remaining questions in this section of the FAQ explain how
to set up such a split installation. This will allow you run
both GNO and ORCA/Shell (but not concurrently). The latter is
necessary when submitting bug reports to the Byte Works. Mike
Westerfield (quite rightly) does not generally accept bug reports
about programs that fail under GNO but run correctly under
ORCA/Shell.
CAVEAT: For the methods explained in this section to work, you must
be using occ v1.14 when doing compilations with ORCA/C
v2.0.x. This is because occ v1.14 will allow older versions
of ORCA/C to #include the 13/orcacdefs/defaults.h file which
is automatically included by ORCA/C v2.1.x.
If you are using ORCA/C v2.0.x but not occ, you will have
to use the #pragma path directive in all of your sources.
Failure to do so may result in compilation errors or
unexplained crashes.
Any version of occ may be used when compiling with ORCA/C
v2.1.x.
These methods are not quite error-free. See Q#11.11 for
details.
The information in this section has been used to set up combinations
of GNO v2.0.4 and GNO v2.0.6 with ORCA/C v2.0.3 and ORCA/C v2.1.x.
Q#6.2: How do I set up ORCA/C so that I can use it with GNO?
A#6.2: === See the CAVEAT in Q#6.1 ===
There are a few aspects to this, so it has been split into various
questions in this section of the FAQ. You should read each of
those questions when so directed, below. The following instructions
assume that you have already installed your ORCA languages; various
files and directories will be moved from their original locations.
If you haven't already done so, change the auxtype of
(original_orca_directory)/shell/Editor to hex DC00 (see Q#14.1).
Next, create the directory /lang/orca. This will be the new
location of your ORCA distribution. You should move all the
files and directories from you original ORCA location to /lang/orca.
You will therefore have directories like /lang/orca/shell,
/lang/orca/languages, and so forth.
The next step is to set up the appropriate GS/OS prefix numbers.
This procedure is documented in Q#6.3 (don't forget to update
both your 15/login and ~/gshrc files).
Next, set up your defaults.h file as described in Q#6.5. As per
the caveat in Q#6.1, this file will be parsed regardless of which
version of ORCA/C you're using.
Now, if you're running GNO v2.0.4, you have to modify some header
files. See Q#6.6.
Next you have to set up your libraries. This information is specific
to your GNO-ORCA/C version combination. See questions Q#6.7, Q#6.8,
Q#6.9, or Q#6.10 as appropriate. Note that the library /lib/libgno
is obsolete in both GNO v2.0.4 and v2.0.6. If your /lib directory
resides on an HFS partition, you will need to rename some of your
libraries (see also Q#11.4).
If you're using an older version of ORCA/C, you should prototype
your headers (this is already done for newer versions of ORCA/C).
Using prototyped headers and #pragma lint -1 can catch a lot of
bugs, both in user code and in the compiler. Be very careful that
you use the correct prototypes.
For programs in your 17 directory that don't work with GNO (such
as prizm), I recommend putting something like the following in
your ~/gshrc:
alias prizm echo "prizm not available under GNO"
Remember to put 17 in your PATH environment variable. See the
Gsh Reference Manual if you don't know how to do this.
Finally, if you're using ORCA/C v2.0.x, ensure you have occ v1.14
installed (other versions -- earlier or later -- will not suffice).
Also edit both 15/login and ~/gshrc to define the CCOLD environment
variable. Do NOT define the CCOLD environment variable if you are
using ORCA/C v2.1.x; you will slow down your compilations.
Q#6.3: GNO with ORCA: What should I use for compilation directories and
prefixes?
A#6.3: === See the CAVEAT in Q#6.1 ===
In order to minimize file duplication for running GNO and ORCA/Shell
(but not concurrently -- see Q#2.2), you should set your prefixes up
as follows. For GNO, these "volumes" may be defined in /etc/namespace
(see Q#7.3). For ORCA/Shell, these pathnames may be relative to
one or more volumes.
SHARED (used by both GNO and ORCA/Shell)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15 /lang/orca/shell configuration files
16 /lang/orca/languages compilers
- /lang/orca/include ORCA headers
17 /lang/orca/utilities ORCA-compatible utilities
- /lang/orca/utilities/help ORCA-compatible utility
descriptions
14 /tmp scratch (work) directory
GNO (not used by ORCA/Shell)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13 /lib main GNO libraries
- /usr/lib secondary GNO libraries
- /usr/local/lib secondary GNO libraries
ORCA (not used by GNO)
^^^^^^^^^^^^^^^^^^^^^^
13 /lang/orca/libraries ORCA libraries
The prefixes shown should be set up in your ~/gshrc file (for GNO),
or your 15/login file (for ORCA/Shell).
Q#6.4: GNO with ORCA: Where should my C header files go?
A#6.4: === See the CAVEAT in Q#6.1 ===
While it is possible to have all of your header files in one
directory hierarchy (this is how it was done in the stock v2.0.4
distribution), it is STRONGLY advised that you keep separate
directory hierarchies. They are:
/usr/include
/HFSinclude
/lang/orca/libraries/orcacdefs
/lib/orcacdefs
/usr/local/include
The /usr/include directory should contain all the header files
that ship with GNO. This will include some subdirectories like
sys, machine, and net.
In GNO v2.0.6 there are a few files that don't conform to ProDOS
naming conventions. These files should be placed in the /HFSinclude
hierarchy.
ORCA/C comes with its own set of header files. Some of these
are used by GNO while others are ignored (because header files
of the same names exist in one of the other directory hierarchies).
All of these header files should be left in the
/lang/orca/libraries/orcacdefs directory (see Q#6.2).
/lib/orcacdefs corresponds to 13/orcacdefs under GNO. It should
contain only one file, defaults.h. See Q#6.5.
/usr/local/include, like everything else in the /usr/local hierarchy,
is not used by the GNO base install. This hierarchy is reserved
for site-specific packages that you decide to add. In particular,
/usr/local/include should be used for any header files that you
decide to add to your system, and which are not part of the
base installation.
Q#6.5: GNO with ORCA: What goes in the 13/orcacdefs/defaults.h file?
A#6.5: === See the CAVEAT in Q#6.1 ===
There are two versions of this file, one for GNO and one for
ORCA/Shell. For GNO, the /lib/orcacdefs/defaults.h file should
contain:
#define __appleiigs__
#define __GNO__
#pragma path "/usr/include"
#pragma path "/HFSinclude" /* needed for GNO v2.0.6 */
#pragma path "/lang/orca/libraries/orcacdefs"
(See Q#11.11 regarding a problem with using the "path" pragma.)
For ORCA/Shell, the /lang/orca/libraries/orcacdefs/defaults.h
file should contain:
#define __appleiigs__
Q#6.6: GNO with ORCA: What header file modifications are necessary?
A#6.6: === See the CAVEAT in Q#6.1 ===
If you're using GNO v2.0.6, no modifications should be necessary
provided you've placed all the GNO header files into /usr/include
and /HFSinclude as appropriate. This applies to both ORCA/C v2.0.3
and ORCA/C v2.1.x.
There are various header files included with the GNO v2.0.1
distribution. These should all be copied into the /usr/include
directory hierarchy as discussed in Q#6.4. (Versions 2.0.2,
2.0.3, and 2.0.4 were incremental changes, not complete
distributions, and therefore did not include header files.)
If you are using the Multiuser package, then you should also
copy over the <time.h> and <utmp.h> files from that package.
The files in the following lists are used instead of their ORCA/C
counterparts, except where noted by "+++"; those so marked need
to be modified as described.
Note the last section in this question is a list of suggested
changes to the GNO v2.0.4 header files. These changes you should
make yourself.
GNO v2.0.4 with ORCA/C v2.0.3
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
errno.h This one has many GNO error codes added.
fcntl.h Differs in the prototypes of open(2), read(2),
write(2), and definition of OPEN_MAX.
signal.h Completely different for GNO.
stdio.h Differs in the prototypes of fread(3) and
fwrite(3). The FILE structure uses an
older name for one of its members, but it
doesn't matter. A prototype for fdopen(3)
and the fileno() macro was added.
+++ stdlib.h You should delete this one and copy the
ORCA/C v2.0.3 stdlib.h from
/lang/orca/libraries/orcacdefs to
/usr/include. See the "common" changes
below for more information on this file.
string.h Many new functions were added in the GNO one.
+++ types.h You should delete this one and copy the
ORCA/C v2.0.3 types.h from
/lang/orca/libraries/orcacdefs to
/usr/include. See the "common" changes
below for more information on this file.
GNO v2.0.4 with ORCA/C v2.1.x
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
errno.h This one has many GNO error codes added.
fcntl.h Differs in the prototypes of open(2), read(2),
write(2), and definition of OPEN_MAX.
signal.h Completely different for GNO.
+++ stdio.h You should delete this file, then copy the
one from your ORCA/C distribution into
the /usr/include directory. See the "common"
changes below for more information on this
file. Note that there was a critical change
to the FILE structure as of ORCA/C v2.1.1b2;
ensure your header file matches your OrcaLib.
+++ stdlib.h You should delete this one and copy the
ORCA/C v2.1.x stdlib.h from
/lang/orca/libraries/orcacdefs to
/usr/include. See the "common" changes
below for more information on this file.
+++ string.h You should rename this file to something
else (like "string.old"), then copy the
one from your ORCA/C distribution into
the /usr/include directory. Finally, you
should copy the prototypes for the following
functions from the old GNO file into the new
one copied from the ORCA/C distribution:
bcopy bzero
index rindex
strdup strupr
strlwr strset
strnset strrev
strpblnks strrpblnks
strpad strrpad
stricmp strncmp
+++ types.h You should delete this one and copy the
ORCA/C v2.1.x types.h from
/lang/orca/libraries/orcacdefs to
/usr/include. See the "common" changes
below for more information on this file.
GNO v2.0.4 common changes
^^^^^^^^^^^^^^^^^^^^^^^^^
The following is a list of suggested changes to the GNO v2.0.4
header files. You have to make these changes yourself; they are
not part of the distributed header files.
For any files below that don't appear in /usr/include, you should
copy the file from /lang/orca/libraries/orcacdefs into /usr/include,
then edit the copy in /usr/include. Do not modify files in
/lang/orca/libraries/orcacdefs.
dirent.h (possibly sys/dirent.h):
Ensure that in struct dirent, the d_namelen field
appears before the d_name field, as described in the
GNO v2.0.4 release notes.
gno/gno.h:
Rename send(2) to procsend(2) and receive(2) to procreceive(2).
stdio.h:
Add the following:
#define fileno(f) ((f)->_file)
#define P_tmpdir "/tmp"
FILE * fdopen(int, const char *);
char * tempnam(char *, char *);
char * mktemp(char *);
int mkstemp(char *);
FILE * popen(const char *, const char *);
int pclose(FILE *);
Add the following if you're using ORCA/C v2.1.x:
#define setbuffer(stream,buf,size) ((buf==NULL) ? \
(void)__setvbuf(stream,NULL,_IONBF,0L) : \
(void)__setvbuf(stream,buf,_IOFBF,\
(size_t)size))
#define setlinebuf(stream) (__setvbuf(stream,NULL,\
_IOLBF,0L))
int __fseek(FILE *, long, int);
int __setvbuf(FILE *, char *, int, size_t);
stdlib.h:
Add the following declarations:
int initenv(void);
void popenv(void);
int pushenv(void);
int putenv(const char *);
int setenv(const char *, const char *, int);
void unsetenv(const char *);
sys/ports.h:
Change the prototypes of pdelete(2) and preset(2) to:
int pdelete(int, int (*)(void));
int preset(int, int (*)(void));
sys/stat.h:
Add the following prototype:
int umask(int);
This header file contains the following guard macro:
#ifndef __BSD_TYPES__
#include <sys/types.h>
#endif
it should be changed to:
#ifndef __SYS_TYPES__
#include <sys/types.h>
#endif
sys/times.h:
The last line should be modified so that the text following
the #endif is in a comment, otherwise it is not legal C
source code:
#endif /* _SYS_TIMES_H_ */
sys/types.h:
Change the typedef of sig_t to:
typedef void (*sig_t)(void);
The typedef for use_t has an extraneous '_' character. Of
course, if you hit this and aren't compiling the kernel
you're doing something wrong since the _IN_KERNEL macro
should not normally be defined:
typedef unsigned char use_t;
sys/wait.h:
Add the following declaration:
int wait(union wait *);
time.h:
Add the following declarations:
void tzset(void);
#ifndef _SVR4
struct tz * timezone(void);
#endif
types.h:
Before the definition of TRUE, add in the following:
#undef TRUE
#undef true
#undef FALSE
#undef false
unistd.h:
As explained in the lenviron documentation, rename the
execve() system call to _execve() (if you have installed
/usr/lib/lenviron as described in Q#6.7 or Q#6.8). Insert
or uncomment prototypes for execl(), execlp(), execv(),
execve(), and execvp(). The execve() prototype should be:
int execve(const char *,char * const *,char * const *);
Insert the following prototypes. They are not yet defined
in any standard, however they are common routines and are
provided in libc for GNO v2.0.6:
char * dirname (const char *);
char * basename (const char *);
Q#6.7: GNO with ORCA: What libraries are used for the combination of
GNO v2.0.4 and ORCA/C v2.0.x?
A#6.7: You must have the following libraries in the sequence given:
/lib/lcrypt (GNO v2.0.1)
/lib/lregexp (GNO v2.0.1)
/lib/lstring (GNO v2.0.1)
/lib/ltermcap (GNO v2.0.1)
/lib/libc (GNO v2.0.4) [rename to "nlibc" for HFS]
/lib/OrcaLib (GNO v2.0.1)
/lib/PasLib (ORCA/Pascal v2.0.x, required if and only if
you use ORCA Pascal)
/lib/SysFloat (ORCA/C v2.0.x)
/lib/SysLib (ORCA/C v2.0.x)
The following libraries are recommended. The sequence here is not
important as they will be read in the order specified on the occ(1)
command line:
/usr/lib/lflex
This provides a main() routine suitable for a
flex(1) generated parser.
/usr/lib/lgnoasm
Provides asm replacements for some libgno symbols.
These include "CommandLine", "timezone", "tmpnam".
/usr/lib/lenviron
[This library is obsoleted as of GNO v2.0.6 --
these routines have been incorporated into libc.]
This has a replacement for getenv/setenv, exec*,
and other routines that ease the porting of UNIX
programs. Note that the prototype and implementation
of execve(2) changes from that defined in the GNO
docs.
/usr/lib/lgetline
GNU line input editing.
/usr/lib/lgetopt
A GNU replacement for the getopt(3) package.
/usr/lib/lttylock
Provides locktty(3) and unlocktty(3) routines.
/usr/lib/lstack
[This library is obsoleted as of GNO v2.0.6 --
these routines have been incorporated into libc.]
Stack checking routines. These are useful for
verifying how much stack space your final program
uses so that it may be reduced to a minimum. The
currently available archive contains an object file
which may be converted to a library file by
makelib(1).
/usr/lib/gnulib
A GNU replacement for the alloca(3) routine and
the getopt(3) package. This partially overlaps
the lgetopt library.
Q#6.8: GNO with ORCA: What libraries are used for the combination of
GNO v2.0.4 and ORCA/C v2.1.x?
A#6.8: You must have the following libraries in the sequence given:
/lib/lcrypt (GNO v2.0.1)
/lib/lregexp (GNO v2.0.1)
/lib/lstring (GNO v2.0.1)
/lib/ltermcap (GNO v2.0.1)
/lib/libc (GNO v2.0.4) [rename to "nlibc" for HFS]
/lib/OrcaLib (ORCA/C v2.1.x)
/lib/PasLib (ORCA/Pascal v2.1.x, required if and only if
you use ORCA Pascal)
/lib/SysFloat (ORCA/C v2.1.x)
/lib/SysLib (ORCA/C v2.1.x)
Note the OrcaLib should be the one shipped with ORCA/C v2.1.x.
You can use it provided that you apply the va_end fix described
in Q#11.1.
You should also install the list of recommended libraries listed
in the latter part of Q#6.7.
Some people believe the ORCA/C v2.1.x library won't work properly
with pipes. This has neither been demonstrated nor disproved.
If you find hard evidence either way, please contact Devin Reade
at the address at the top of this FAQ.
If you need pipes, you can try the libraries that shipped with GNO
v2.0.1, but you will not get any of the Byte Works bug fixes. Also,
it has been reported that the GNO modifications introduced stdio
bugs that weren't in the original version (no details available).
Note that you _must_ keep the versions of OrcaLib, SysFloat, and
SysLib consistent; you cannot use some from OrcaC v2.0.x and others
from OrcaC v2.1.x. You may run into problems from unexpected
behavior to memory trashing.
Q#6.9: GNO with ORCA: What libraries are used for the combination of
GNO v2.0.6 and ORCA/C v2.0.x?
A#6.9: This combination is no longer supported. You will have to
upgrade to ORCA/C v2.1.x.
Q#6.10: GNO with ORCA: What libraries are used for the combination of
GNO v2.0.6 and ORCA/C v2.1.x?
A#6.10: You must have the following libraries in the sequence given. You
should not add any other libraries to this directory as it will
slow down linking for all programs.
/lib/libc (GNO v2.0.6) [rename to "nlibc" for HFS]
/lib/lsaneglue (GNO v2.0.6) [renaem to "nlsaneglue" for HFS]
/lib/OrcaLib (GNO v2.0.6)
/lib/PasLib (ORCA/Pascal v2.1.x, required if and only if
you use ORCA Pascal)
/lib/SysFloat (GNO v2.0.6)
/lib/SysLib (ORCA/C v2.1.x)
The following libraries are recommended. The sequence here is not
important as they will be read in the order specified on the occ(1)
command line:
/usr/lib/lflex
This provides a main() routine suitable for a
flex(1) generated parser.
/usr/lib/lgetline
GNU line input editing.
/usr/lib/lgetopt
A GNU replacement for the getopt(3) package.
/lib/lstring
Non standard string routines. (*** Obsolete?)
/lib/ltermcap
Terminal capabilities library. Moved from /lib.
/usr/lib/lttylock
Provides locktty(3) and unlocktty(3) routines.
/usr/lib/gnulib
A GNU replacement for the alloca(3) routine and
the getopt(3) package. This partially overlaps
the lgetopt library.
The following libraries either are obsolete or have been merged with
libc and should NOT be used:
/lib/lcrypt
/usr/lib/lgnoasm
/usr/lib/lenviron
/usr/lib/lregexp
/usr/lib/lstack
System Configuration
--------------------
Q#7.1: What patches should I have applied for GNO?
A#7.1: GUPP (Grand Unified Patch Program by Nathan Mates) is recommended
for fixing memory-trashing bugs present in GNO kernel versions
v2.0.4 and v2.0.6-beta. GUPP also does other patches that may be
applicable to programs running under GNO. GUPP will not touch
kernels earlier than v2.0.4 even though those bugs probably exist
in earlier versions of the kernel.
GUPP is available from the ground and caltech sites, and also
at
ftp://ftp.visi.com/users/nathan/a2software/gupp.shk. See also
Q#14.4.
Q#7.2: How do I change the information that's printed before the login
prompt?
A#7.2: Check in the /etc/gettytab file. There's a line near the top that
contains the login string. It is preceded by an "im:", which is
an acronym for "initial message".
Q#7.3: How do I map /usr, /local, /var, and other partitions to GS/OS
volume or directory names?
A#7.3: The kernel provides this functionality through the namespace
facility, which is configured in /etc/namespace. See the Kernel
Reference Manual for details. See also the Kernel Bugs section
of question #704 regarding the format of the file.
Q#7.4: How do I set up cron?
A#7.4: There are man pages for this that were distributed with the v2.0.4
GNO update, but they don't quite match the implementation provided
with the Multi-user 2.0 package.
To activate cron, you must uncomment its entry in the /etc/inittab
file. See the init(8) man page for the format of this file.
Cron is controlled through the /etc/crontab file. Unlike its UNIX
counterparts, the GNO cron does *not* support setting of environment
variables in the crontab file. These would be lines of the form:
SHELL=/bin/sh
MAILTO=gdr
Any line which begins with a hash (#) character is considered
to be a comment and is ignored.
All other lines in this file are expected to have five space-
delimited date/time fields, followed by a user name field, followed
by a command. The first five fields are:
minute (0-59)
hour (0-23)
day of month (1-31)
month (0-11)
day of week (0-6) (appears to be ignored)
Multiple values may be specified either separated by commas,
or as a range separated with a hyphen.
Following the five date/time fields is a username field.
Although it has to be present, it does not appear to be used
by the current cron implementation.
The last field is the command to be executed at the specified
time. Unlike UNIX cron implementations, these commands _are_not_
executed from a subshell, so meta characters and file redirection
cannot be used.
You cannot split cron commands into separate lines of the crontab
file. Any '%'s in the command are replaced by newlines. Unlike
UNIX crons, the text appearing after a '%' character _is_not_
piped to the input of the command.
BUG WARNING: Do not use more than 10 multiple values in each
of the date-time fields; if there are more than
10, cron's memory structures are reported to get
corrupted.
Q#7.5: Why won't my entry in the inittab file work correctly?
A#7.5: There are two common sources of problems. The first is due
to improper syntax in the inittab file. See the inittab(5) and
initd(8) manual pages for the correct syntax.
The second common problem is not due to the inittab file, but
rather because the command you are trying to invoke is being
invoked incorrectly. The way to check if this is the case is
to run the command interactively and see what diagnostic messages
appear. You should also check the system log files for messages
(see syslogd(8)).
Networking
----------
Q#8.1: Does GNO provide TCP/IP and/or SLIP support?
A#8.1: Most of the required kernel support is available in GNO v2.0.4,
but it is not complete and there is nothing to take advantage
of it. However, the remaining kernel support has been added
to the upcoming version. This, however, does not include the
TCP stack, which is considered to be a separate product from
GNO.
At this time, the kernel has only been modified to recognize
GS/TCP.
Q#8.2: Is GS/TCP available? Where can I get it?
A#8.2: GS/TCP is not yet available to the general public. Information
on it's status and an overview of the project is available from
the GS/TCP web page:
http://www.geeks.org/~taubert/gstcp/index.html
Q#8.3: Does Marinetti work with GNO?
A#8.3: Recently, Richard Bennett has released Marinetti, a beta-level
TCP/IP stack for the IIgs that does not require GNO.
Experimentation with the Marinetti/GNO combination has been
sketchy so far. However, here are some initial observations,
in no particular order:
- Running individual programs that rely on Marinetti seem
to work the same way under GNO as they do without GNO.
(However, see the following observations.)
- Processes are unable to block while waiting for input.
Therefore, they must do a "busy wait". While this does
not normally matter on the GS, it is considered to be
Rude Behavior under GNO since it steals clock cycles that
could be used by other processes.
- It would be inadvisable to have Marinetti block a process
that is waiting on input, since GNO is in a mutex state when
accessing the ToolBox. Therefore, if Marinetti were to block
a process, then all of GNO would be blocked.
- Development on the Marinetti/GNO combination is still in the
planning stage.
- The optimal method for programs running under the GNO/Marinetti
combination seems to be the the same way that GNO interacts
with GS/TCP; through the kernel. If programs limit themselves
to using the kernel interface (which uses BSD sockets) then
the kernel could potentially use either GS/TCP or Marinetti,
whichever is active. The kernel could worry about blocking
processes, ensuring an appropriate use of resources. The
kernel interfaces (user libraries) could perhaps be written
to use Marinetti directly in the case where GNO is not running.
This would allow a GNO-aware program to work either with
or without GNO.
Programs that use the Marinetti IPC mechanism directly will
probably still work under GNO, but can be expected to have
problems multitasking.
By the way, the above paragraph is pure rambling and supposition
by the FAQ maintainer. The GNO kernel currently knows nothing
about Marinetti.
- Richard has expressed a willingness to work with the GNO
development team to ensure that the two products can coexist.
For the latest status on Marinetti, see the Marinetti home page:
http://www.zip.com.au/~kashum/marinetti
If you have additional information regarding the Marinetti/GNO
combination, please email the maintainer of this FAQ.
Q#8.4: What TCP/IP network utilities are available?
A#8.4: Several utilities have been written and should be made available
with the release of GS/TCP. They include:
ftp, telnet, irc, ping, finger, rcp
Q#8.5: Is there a WWW browser for GNO and GS/TCP?
A#8.5: A text oriented browser has been ported by Derek Taubert and
requires the GS/TCP package. Derek has also done some work on
a Graphics based WWW browser. Neither package has as yet been
released.
There are no known WWW browsers available yet that are based
on Marinetti. This is subject to change, and you should see
the Marinetti web page for the latest details. See Q#8.3.
Q#8.6: Can I use a serial card or internal modem with GNO?
A#8.6: Currently the GNO serial drivers only support the two built-in
serial ports. This does not imply that you cannot use a
serial card in a remote machine (such as a IIe) that is connecting
to your IIgs running GNO.
Q#8.7: What should I use for my modem port control panel settings.
A#8.7: These settings will usually work. See the Notes, below.
Device Connected: Modem
Line Length: Unlimited
Delete first LF after CR: No
Add LF after CR: No
Echo: No
Buffering: Yes
Baud: 19200 (1)
Data/Stop Bits: 8/1 (2)
Parity: None (2)
DCD Handshake: Yes
DSR/DTR Handshake: Yes
XON/XOFF Handshake: No
Notes: 1. The baud should be set to whatever is appropriate
to your system. Unless you are using a modem or
serial line that is slower than 14400 bps, this will
almost always be "19200".
2. Set data/stop bits and parity as appropriate for your
site. 8N1 is the most common setting.
Q#8.8: How can I initialize my serial ports at GNO "boot" time?
A#8.8: The easiest way to do this is through initd(8). Add the following
lines to your /etc/initab file:
# this will initialize the modem port on startup
md:b:once:i:/usr/sbin/runover .ttya /bin/stty 38400
You should of course change "38400" to whatever speed is appropriate
for your site.
Q#8.9: How do I hook up a terminal to the IIgs' printer/modem port?
A#8.9: This answer describes hooking up a terminal to the printer port.
Hooking one up to the modem port will be similar except that
.ttya should be used instead of .ttyb.
On the hardware side, you will need a mini DIN 8 to DB25 printer
cable. This should be connected from the IIgs' printer port
to the port on the terminal that would normally be hooked to
a modem.
Next, you have to run a getty(8) over the printer port. Add
this line to your /etc/inittab file:
pp:23478:rest::/usr/sbin/getty 8bit.xxxx .ttyb
where xxxx is the speed. Remove '78' from '23478' if you want
to run it only in multiuser mode. See also Q#8.8 regarding
initialization of the serial port.
In order for the change to take effect, you either have to quit
and restart GNO, or type '/bin/init q' (without the quotes).
Q#8.10: How do I enable GNO to activate dialup access.
A#8.10: This question is not about using your IIgs to dial _out_ to another
machine. It means that you're allowing _other_ machines to
dial _in_ to your IIgs running GNO.
The first thing you should consider is whether you _really_ want
to do this. GNO doesn't have any user/group file permissions,
so as soon as someone is logged into your IIgs, they will have
read/write access to _all_ of your files. Because of this, the
only layer of protection you have is dialup/getty and the security
of the password file (including how well _all_ passwords are
chosen). There has been no known investigation into the security
of the GNO dialup/getty.
That said, the way to enable dialup access is through the dialup(8)
program. It is invoked as
dialup tty [speed [init_string]]
Normally this would be done at GNO "boot" time through the initd(8)
facility. Add the following to your /etc/inittab file:
# This enables the modem for remote dialup (_into_ the IIgs)
# when in multiuser mode (run level 2 or 3).
t2:23:rest::/usr/sbin/dialup .ttya 38400 ate1qs0=1s11=50\\r
Ensure you substitute the "38400" with a speed appropriate to your
hardware. Note that "14400" is not considered to be a valid speed.
If you are using a 14400 kb/s modem, you should use "19200" as the
speed setting.
See also Q#8.8 regarding initialization of the serial port.
You should also replace the initialization string with one suitable
for your modem (consult your modem manual). The one shown above
contains the following HAYES commands:
at (start command)
e1 local echo on
s0=1 auto answer on
s11=50 set touch tone duration to 50ms
\\r escaped carriage return (ends command)
Q#8.11: What do I use for a ProTERM termcap entry?
A#8.11: This termcap entry is suitable for use with any UNIX machine
(that uses termcap rather than terminfo) being accessed from
ProTERM:
#
# ProTerm Special
#
pt|pse|proterm-special|Proterm Special Emulation:\
:ae=^N:am:al=^V:bl=^T^A^E@:bs:bw:cl=^L:cm=^^%r%+ %+ :co#80:ce=^Y:\
:cd=^W:dc=^D:dl=^Z:do=^J:eo:eA=^P:ho=^X:ic=^F:il=^N:i3=^L:\
:is=^L^N:kd=^J:kl=^H:kr=^U:ku=^K:le=^H:li#24:ll=^^ 8:mb=^O:md=^O:\
:me=^N:mh=^O:mr=^O:nd=^U:nl=\n+^A:pt:rs=^N:se=^N:so=^O:ta=^I:\
:ue=^N:up=^K:us=^O:xn:ns:as=^P:bc=^H:r1=^N:r2=^N:r3=^N:\
:ms:mi:sf=^J:sr=^K:as=^P:i1=^N:i3=^N:NP:dn=^J:
Q#8.12: Is there a mail/news package available for GNO?
A#8.12: There is a rudimentary one called MuGS by Brian Tao. It requires
a shell account (presumably on a UNIX box) for part of the
software. The base MuGS package handles news articles that
are spooled on the UNIX machine's local disk. There is an NNTP
(Net News Transfer Protocol) patch by Devin Reade that allows
MuGS to work with an NNTP server. MuGS is available as described
in its describe(1) entry (see Q#4.4).
Because of a lack of TCP/IP there is no software for GNO v2.0.4
that allows a IIgs to connect to the 'net via NNTP or SMTP.
Jeff Markham provided the following suggestion:
I've been using the gmail system, and I've come up with
something that seems to work ok with gmail and sendmail.
Create the following two files. The first is /bin/send:
[gdr: The second and third lines should be a single line
without the escaped newline. It has been printed
here as is for clarity:
#!/bin/gsh
/bin/foreach x /var/spool/sendmail/out/* \
< /bin/send.dat > .null
The second is /bin/send.dat:
tail +2 $x | /usr/sbin/sendmail
rm $x
That combo works well enough to send the mail on it's way.
The way I use to get around gmail's need for all config
files to be in the same folder as the exe is by using the
following /bin/mail file:
#! /bin/gsh
rm /bin/signature /bin/gmail.cf > .null
cp $HOME/gmail/* /bin
gmail
mv /bin/gmail.o $HOME/gmail
send
It copies all the set-up files, calls gmail, returns the
only needed file to the users account and sends any mail.
Comments on my process are welcome.
Q#8.13: How do I use copycat?
A#8.13: There seem to be two versions of copycat available. One version
takes two tty names on the command line, the other takes only one.
It is unclear which version numbers correspond to which behavior;
the version that takes only one argument lists itself as v1.5.0,
however the documentation for v1.5.0 definitely lists a requirement
for two arguments.
That said, there are a few ways to use copycat. This answer will
assume that you wish to communicate from the GNO console with a
terminal hooked to your modem port. If you are using the TMTerm
NDA, then substitute ".ttyco" in this example with ".ttyq0".
The first thing you must do to use copycat is ensure that your
serial port is properly initialized. Use the stty(1) command
like this:
stty 38400 < .ttya
You should substitute "38400" with whatever speed was used for
setting up your link. ".ttya" is the modem port device. (For
the printer port, use ".ttyb".)
Now all you have to do is issue the following command. The second
argument may not be required or accepted in your version of copycat:
copycat .ttya .ttyco
You will see the prompt:
Break character is '^\'
You are now connected with whatever is hooked up to your modem
port. To get the copycat command prompt, type the control
character (CONTROL-\).
See the copycat documentation and man page for more details.
It explains how to do interesting things like allowing a terminal
on your printer port to use your modem without interfering with
the GNO console.
Q#8.14: How do I use rz/sz?
A#8.14: rz/sz are usually used in conjunction with copycat. The important
part to remember is that while copycat is used to control the
remote end of the file transfer, it must not be running _during_
the transfer.
The following example assumes you are sending a file from the
remote machine to the IIgs. Steps taken to go the other direction
will be similar.
The first step is to initialize your modem port and start copycat
as explained in Q#8.13. In this example, "unix% " is used as the
prompt on the remote machine, and "gno% " as the prompt on the
IIgs. Extraneous blank lines have been deleted.
gno% stty 38400 < .ttya
gno% copycat .ttya
Break character is '^\'
unix%
Next, start the file transfer on the UNIX end. There are problems
with some versions of UNIX sz if the "-l1024" flag is not given
(others don't recognize this flag). See the rz/sz README.GNO
file and the UNIX sz man page for details. Remember to use the
"-a" flag if you want a text file transfer:
unix% sz -a testfile.bsq
**B00000000000 14
Now type the copycat break character, CONTROL-\, quit from copycat,
and start rz on the GNO side:
copycat> quit
gno% rz < .ttya > .ttya &
When the file transfer is finished, don't forget to log off the
remote machine. To get there, you have to restart copycat:
gno% copycat .ttya
Break character is '^\'
unix% logout
^\
copycat> quit
gno%
Q#8.15: Why do I get errors when trying to access the (modem/serial) port?
A#8.15: This is usually caused by serial port configuration problems.
Common symptoms may be:
% copycat .ttyco .ttya
Error opening tty .ttya, aborting.
or
% /usr/sbin/getty 8bit.38400 .ttya
getty: .ttya: I/O error
The first thing to check is that the following GNO serial port
drivers exist:
/dev/modem
/dev/printer
Next, ensure the following two lines are in your /etc/tty.config
file, and that they are uncommented:
modem 2 .ttya
printer 1 .ttyb
Finally, ensure that SIM (the Serial Interrupt Manager) is present
and active. This is an init in your system.setup directory:
*/system/system.setup/sim
Remember to reboot your system if you've made any changes in
or to comply with the above requirements.
Porting UNIX Programs to the GNO Environment
--------------------------------------------
Q#9.1: What programs/utilities should I have to port UNIX source code to GNO?
A#9.1: Strictly speaking, all you need is a C compiler (since UNIX source
tends to be in C). However, there are a few programs that
can be considered "essentials" for doing ports. All of these
are mentioned in the section on "Compiling":
ORCA/C, occ, dmake
Q#9.2: What are the common problems encountered when porting UNIX source
to GNO?
A#9.2: The first thing to watch for is known compiler and library bugs.
Soenke Behrens maintains the current ORCA/C bug report list.
You should keep the contents of this list in mind when examining
the target source code. The ORCA/C bug report list may be found at
http://www.arrowweb.com/sbehrens/obugs.htm
This list has been considerably shorted since the release of
ORCA/C v2.1.0. If you have an earlier version of ORCA/C, you
should seriously consider an upgrade.
The following items should be watched for, in no particular order.
Since UNIX source is usually in C, that language is assumed for
the rest of this section, where relevant:
sizeof(int)
The size of the type "int" is implementation-defined.
While most modern C compilers use 32 bits, ORCA/C still
uses 16 bits since this is the "natural" integer size of
the 65816. This also results in more effective code
generation.
While the size of an int shouldn't make a difference to
any well-written code, there is some available source code
that assumes that ints are 32 bits. You should watch for
this in any code that does bit manipulations. You should
also watch for code that freely converts between integers
and pointers. GNU (Free Software Foundation) software
is often bad for this.
recursion
When possible, recursion should be avoided when programming
on the Apple IIgs. This is because recursion invariably
causes stack growth and the stack can only exist in bank
zero. This means that the maximum space available for
the stack is 64k. In practise, it is much smaller.
This problem is exacerbated under GNO where all processes
must share the available stack space (each process has its
own stack, though).
Any program that uses recursion can be rewritten to use
iteration instead. You should try to do this when possible.
If you _do_ use recursion, don't allocate a huge stack;
this will keep other programs from executing. Also, you
should leave in stack checking and stack repair (if
programming with ORCA/C) to ensure that your recursion
does not crash the machine if it goes too far.
reference to absolute file descriptors
True UNIX machines invariably use the file descriptors 0, 1,
and 2 for standard input, standard output, and standard error,
respectively. Under GNO, the file descriptors used are 1,
2, and 3.
This causes a problem when source code is written to use
these descriptors directly. You should search your code
for references to these descriptors, typically in calls
to open, close, read, write, dup, dup2, and fcntl.
Instead of replacing these digits with other digits though,
you should use the macros STDIN_FILENO, STDOUT_FILENO, and
STDERR_FILENO defined in <unistd.h>. This will ensure
that your source is kept portable.
fork
Because of problems that are discussed in the fork(2) man
page and the kernel reference, the fork system call under
GNO is different than other versions of UNIX. Besides
having a different prototype, the parent and child process
share the same address space. In this respect, GNO is less
a multitasking environment than it is a multithreading
environment.
Search for calls to fork; you will have to rewrite these
sections of code. See also the man page for fork2(2); it
may be more suited to your purposes.
Also note than when compiling routines that make a call
to fork, you should turn off ORCA/C's stack repair code.
This means that you should be using an optimization level
of at least 8.
read/write of newline character
Most UNIX systems use LF (ASCII 0x0a) as the line delimiter.
Both Apple II and Macintosh computers use CR (ASCII 0x0d)
as the line delimiter. The C newline character is '\n';
ASCII 0x0a.
While the stdio routines (fprintf(3), fread(3), etc) usually
make this difference unnoticable by doing CR-->LF translation
on input and LF-->CR translation on output, no such
translation is done on files accessed through read(2) and
write(2). Specifically, the GNO open(2) does not recognize
the ORCA/C O_BINARY bit in it's second argument.
Therefore, if the program you are porting makes calls to
read(2) and write(2), watch for the '\n' character in your
code. You may have to change this to '\r'. Don't do it
blindly, because many programs will use both stdio and
operations on the bare file descriptors.
One suggestion is to modify your programs low-level I/O
routines to modify the I/O buffer prior to calling write(2)
and after calling read(2).
variadic functions
Some (poorly written) UNIX programs have variadic functions
where the number of provided arguments don't match the
number of arguments expected by the called routine. Even
though this is in some cases legal ANSI/C, versions of
ORCA/C prior to v2.1 would puke magnificently when encountering
such code. Some of these cases are now handled in a more
robust fashion by ORCA/C v2.1 and later.
If you are _defining_ (as opposed to using) variadic functions,
you must turn off stack repair code around the definitions
of those functions.
The ORCA/C manual (and especially the release notes for
v2.1) have important and detailed information on this topic.
See the sections on the optimize and debug #pragmas.
open, chmod, fchmod, creat, st_mode, stat, fstat, lstat
In general, the bits in the mode parameter of these
functions do not directly map between UNIX and GNO
implementations. If your application is using macros
such as S_IREAD or S_IWRITE for the mode parameters, and
those macros are taken from the system header file
<sys/stat.h>, then you probably don't need to modify your
application.
If, on the other hand, your application is using its own
constants for the mode parameter, you should convert it
to use the standard macros. Failure to do so may result
in files with strange GS/OS flags set, or file tests failing
in your program.
/dev
One of the UNIX philosophies is that "everything is a file".
The /dev directory on UNIX systems contain device special
files. Accessing these files is the way to access the
relevant hardware.
For GNO programs, you should not access devices in the
/dev directory. For example, opening "/dev/console" for
writing will not have the expected effect. Instead you
should open the corresponding GS/OS device, ".ttyco".
The portable (and suggested) method of handling these cases
is not to change the value of the string (in this example)
from "/dev/console" to ".ttyco". Instead, use the macros
defined in the file <paths.h>. For this example, one would
use the macro _PATH_CONSOLE.
standard path assumptions
This one is closely tied in with the "/dev" description
above. The <paths.h> file contains macros for various
standard paths. The macros, instead of the actual paths,
should be used to maximize portability.
signal handlers
When a signal handler is called, the data bank register
may not have an expected value. If your program references
global scalars, it may crash. To avoid this, all functions
used as signal handlers should have their definition
preceded by
#pragma databank 1
and followed by
#pragma databank 0
validity of pathnames
Most programs make assumptions about what constitutes
a valid file name. For most modern Unices, a valid
file name follows the POSIX portable filename character
set: The characters a-z and A-Z, the digits 0-9, and
'.', '_', and '-'. The '-' is not used as the first
character of a file name, and '/' is the directory
separator character. The maximum filename length is
at least 14 characters, and the maximum pathname length
is at least 255 characters.
Now this is different from what is available under GNO.
The ProDOS FST provides only a subset of the above. The
HFS FST provides a superset, but HFS is too slow, too
buggy, and too unmaintainable for many users.
The problem is also compounded by the fact that under
GS/OS, the ':' is a directory separator. '/' may be used
but it is mapped internally to ':'.
Unfortunately, there is no general consensus on how to
handle pathnames under GNO. Here are some opinions, all
of which refer to user code; the GNO kernel treats pathnames
the same way that GS/OS does:
- the ':' character should be mapped to '/'. This prohibits
the use of '/' in _file_ names. It also provides the
highest degree of "UNIX compatibility"; or
- the '/' character should be mapped to ':'. This is more
in line with GS/OS, but can require extensive rewrites
of ported UNIX programs; or
- use dynamic directory delimiters. The ':' character is
always considered to be a directory separator. The '/'
character is considered to be a directory separator unless
it was preceded at some point by a ':', in which case it
is part of the file name. Having a '/' appear before ':'
in a pathname is illegal. This is the closest to GS/OS,
but also has some problems with POSIX compliance. For
example, the PATH environment variable is _supposed_ to
be a list of pathnames delimited by the ':' character.
This implies that one cannot use the ':' as a directory
delimiter when defining PATH, and that directories in
PATH must not contain '/' as a regular character.
Regardless of which method you use to do filename, pathname,
and directory separator mapping, you should verify that
the pathname is legal for your target filesystem. GS/OS
provides a mechanism to do this through the JudgeName
system call.
Also watch out for references to the root partition. For
other UNIXs, this is the pathname "/", which is a not legal
directory under GS/OS (and therefore GNO). Hopefully the
context of your program will give you an idea how to handle
such a directory reference in a sensible manner.
unlink
Many UNIX programs unlink (delete) files while they still
have them open. Under true UNIX systems, this means that
the file will be deleted as soon as it is closed. This is
is not done under GNO, and attempting to unlink an open file
will fail, and the file will remain on the file system after
it is closed. If your program relies on this behavior, you
will have to find a work-around. One partial solution is
to register a clean-up function via atexit(3) that deletes
your files for you. [This method is not suitable for
daemons or other long-running programs.]
Q#9.3: Are there any other recommendations for porting programs?
A#9.3: There probably are as many opinions as there are programmers.
However, here is a list that seems to work well. Using C as
the source language is assumed:
- Use the occ(1) "-w" flag (#pragma lint -1) whenever possible.
You will have to modify your code if it doesn't use prototypes,
but this is more likely to catch errors and incorrect assumptions.
If you really need to be compatible with K&R compilers, you
can use the following paradigm in your code:
#include <sys/cdefs.h>
int main __P((int argc, char **argv));
int main
#ifdef __STDC__
(int argc, char **argv)
#else
(argc, argv)
#endif
int argc;
char **argv;
{
...
You may have to prototype some of your system header files.
This should not be necessary with the ORCA/C v2.1 header files
(they're already prototyped), but is likely necessary with
earlier versions and some of the GNO v2.0.4 (and earlier) system
header files. See also Q#6.2 and Q#6.6.
- Whenever possible, compile with the occ(1) "-G25" during
development. This will ensure that, in the event of stack
trashing and similar problems, that you get a meaningful
traceback and that your machine (usually) doesn't crash.
If you are using the Splat! debugger, you should use "-g" instead
of "-G25". See also the notes on fork(2) in question Q#9.2.
Make sure you read the both the ORCA/C manual and release notes;
there are times (such as within variadic functions) that you
cannot use stack checking or repair code.
When you're finished development, you can replace the debugging
flag with "-O" for optimization. Don't forget to test your
optimized program before you release it!
Compiling
---------
Q#10.1: Which language should I use?
A#10.1: Since GNO is not language-specific, it doesn't really matter.
From a practical stand point though, either assembly or C tend
to be the languages of choice. Both have their strengths and
weaknesses. Assembly can be more efficient but in general requires
more time to program and more attention to detail. Much of the
available UNIX source code is in C. Using C can result in a quicker
development cycle and more portable code, but it often results in
a slower program.
A big part of the decision is dependent on which language you
already know. If you are comfortable in one, stick with it
until you need to try something else. If you know neither,
then the decision becomes religious -- ie: there is no correct
answer, and the response you get will depend on whom you ask.
Some people have also successfully used Pascal for GNO
programming, although it is not as suited to GNO as is C or
assembly.
If you program in C, the only realistic choice for a compiler
is Byte Works' ORCA/C. As of v2.1.0, it is relatively bug free
and close to ANSI-compliant.
If you program in assembler, Byte Works' ORCA/M is recommended.
Merlin-8/16 (by Roger Wagner) is also reputed to be suitable
(although not as common).
Q#10.2: Should I purchase the ORCA Subroutine Library Source?
A#10.2: The sources are not required, but they are recommended. Some
reasons are:
- they allow you to see how a function is implemented
- they allow you to investigate possible library bugs
- they are good examples of assembly programming
- they are inexpensive
Q#10.3: What is occ?
A#10.3: occ is a front end to ORCA/C written by Soenke Behrens. It makes
ORCA/C's invocation more "UNIX-ish" and is the recommended
interface between dmake(1) and ORCA/C.
Q#10.4: What is dmake?
A#10.4: dmake is a variation of the UNIX "make" facility. It is used
on large software projects for defining when and how files should
be updated (typically compiled or linked), based on dependency
lists. It's behavior is controlled through the use of a
"makefile" (sometimes "makefile.mk"), which is a text file
defining dependency graphs, rules, and actions.
After definition of the makefile, a project can often be built
(perhaps tested and installed as well) just by typing "dmake",
assuming there are no compilation or other errors. Only the
work that is required will be done.
For more details, see the dmake(1) man page.
Q#10.5: What macros should I be using for conditional compilation?
A#10.5: There are four general areas where certain "standard" macros
are used ("standard" is quoted because only those explicitly
annotated correspond to ISO/ANSI or other standards). Where
the macros aren't predefined by current compilers, they should
be defined in source, header, or makefiles when necessary:
- Architecture:
These macros tend to be lower case with double leading-
or trailing-underscores, such as "__sun4__" or "__parisc__".
No IIgs compilers currently predefine an architecture,
but "__appleiigs__" is recommended for Apple IIgs
specific code.
- Operating System:
These macros tend to be upper case and may or may not
use underscores. Examples are "_AIX" and "SunOS".
No IIgs compilers currently predefine an os macro,
but "__GNO__" is recommended for GNO-specific code.
- Compiler:
These macros tend to be upper case and may or may not
use underscores. Examples are "__LCC__" and "__GNUC__".
ORCA/C predefines "__ORCAC__". APW/C predefines "APW".
- Language and other standards:
The "__STDC__" macro may be used for determining ISO/ANSI C
compliance. It is the responsibility of the compiler to
define (or not define) this macro appropriately.
If "_POSIX_SOURCE" source is defined, the source may
be written with the assumption that all symbols defined
by POSIX Standard 1003.1 are available in the environment.
This symbol is expected to be defined by the user as
necessary. GNO isn't yet POSIX compliant, but it's getting
there.
If "_BSD_SOURCE" is defined, all symbols are expected to
be 4.3BSD compliant. This implies "_POSIX_SOURCE". Again,
GNO isn't there yet but it's progressing.
"KERNEL" is defined when building the GNO kernel. You will
see this macro in the GNO header files, but you should not
define it.
"__cplusplus" is predefined by C++ compilers, of which there
are none for the IIgs. It is the responsibility of the
compiler to define (or not define) this macro appropriately.
Explanation of this macro was given since you occasionally
see it in GNO header files ...
Other macros are defined either by the compiler or in header files,
but these are the main ones for user code conditional compilation.
See the relevant documentation (compiler manual, ISO/ANSI or POSIX
standards, GS/OS reference manual) for more details.
Q#10.6: When I'm using the new header files (post-v2.0.4), sometimes ORCA/C
can't find my header files. Why?
A#10.6: There are a few potential causes for this problem, some of which
are not completely understood. You should try the following
steps:
1. Ensure that the correct "#pragma path" values are in your
13/orcacdefs/defaults.h file (see Q#6.5).
2. Ensure that all of your header files are of type SRC and
auxiliary type CC. This includes headers in the directories
specified via "#pragma path" in 13/orcacdefs/defaults.h
(see Q#6.5), any directories specified by the occ(1) "-I"
flag, and your current directory.
3. Remove any *.sym files you have and try compiling with the
occ "-i" flag. This has been reported to eliminate the
problem; presumbably there is an out-of-date cache being
used in the precompiled header file.
If you are using dmake, you can add "-i" to your default
CFLAGS environment variable in /usr/local/lib/startup.mk.
If you use neither dmake nor occ, you can add "#pragma ignore"
to your 13/orcacdefs/defaults.h file.
4. If your problem is intermittent, try calling the purge(1)
command when the problem occurs.
Libraries and Header Files
--------------------------
Q#11.1: I keep getting "va_end" as an unresolved symbol when linking. Why?
A#11.1: You should only be seeing this if you are trying to use the
ORCA/C v2.1.x libraries with GNO v2.0.4. (See Q#6.1 and Q#6.8).
The GNO v2.0.4 libraries were compiled with a version of ORCA/C
that still used a function version of va_end(3). ORCA/C now
correctly defines va_end(3) as a macro.
If you attempt to use a variadic function from the GNO v2.0.4
libraries (such as open(2)), then you will get an unresolved
va_end reference. To solve this problem, download and install
the archive "vaendPatch.shk", available from ground or caltech.
Q#11.2: Why do I keep getting "getc" and "putc" as unresolved symbols
when linking?
A#11.2: This is an indication that the files 13/OrcaLib, 13/SysFloat,
and 13/SysLib are not properly matched. You cannot mix these
files from different versions of ORCA/C. The OrcaLib shipped
with GNO can only be used with particular versions of the other
two libraries. You should (re)read the section in this FAQ on
"Installing GNO with ORCA".
Q#11.3: How can I tell what order my libraries are in?
A#11.3: Try the command 'ls -1n' or 'ls -ln'.
Q#11.4: How can I sort my libraries (or other files)?
A#11.4: This isn't really a GNO question, but it's included here because
of its relevance to Q#11.3 and the section on "Installing GNO with
ORCA".
For ProDOS Partitions:
There are various ways to do this. One of the easiest is to
use ProSEL or another utility which sorts directory entries
(such as the ORCA/Shell compress command -- *don't* confuse
this with the GNO compress(1) command).
If you do not have a utility that does this, you can do it
manually by moving all the files into another (scratch)
directory, then moving them back one at a time in the order
in which you wish them to appear.
For HFS Partitions:
The files in a given directory on HFS partitions are always
sorted by name, case insensitive. You can change the sequence
in the directory only be changing the names of the files
involved.
Specific to GNO installations, if your /lib directory resides
on an HFS volume, you should rename /lib/libc to /lib/nlibc.
Q#11.5: How can I tell what is in library XXXX?
A#11.5: The only way to tell for sure what is in a library is to
look at the symbol table. The most common way to do this
is to get a listing by using Byte Works' makelib(1) utility,
which comes with their various language packages (see the -D
and -F flags).
There is also a program available, listlib(1), which is a
front end to makelib. It provides the same information as
makelib, but in an alternate format more suited to cross
referencing symbols to the files containing them.
Of course, knowing what symbols are _in_ a library doesn't help
unless one knows _what_ the symbols are for. Every library should
have at least one header (*.h) file. This tells the compiler
the type, size, and other important information for each symbol.
Header files, however, are intended for the compiler. A good
library should come with documentation, preferably manual pages
(see Q#3.4, Q#3.5, and Q#3.6).
If documentation isn't available and the symbols appear to be
common UNIX symbols, then try reading a manual page from any
available UNIX box. It might not be right, but it may give you
a start. Next try posting a question to comp.sys.apple2.gno.
Perhaps you will be able to contact the author (not likely if there
wasn't any documentation). When all else fails, there's always
disassembly of the object files ...
Q#11.6: Why isn't the common function XXXX in the libraries?
A#11.6: The GNO libraries are still undergoing active development. If you
find that a standard or common routine is missing, then contact
Devin Reade <
[email protected]> who is currently the primary
maintainer of the GNO libc.
If the function is not yet in libc you are requested to contribute
an implementation and a man page, preferably in nroff(1) source
(see Q#3.5). Distributing the work results in faster updates.
Q#11.7: Function XXXX is declared in the GNO header files, but it's not in
the libraries. Why?
A#11.7: Just because a function is declared, that doesn't necessarily mean
that it's been implemented. However, it is useful to keep those
declarations in the system header files. Not only does it minimize
namespace conflicts with user code (application programmers are
less likely to use function names that conflict with system header
files), but it ensures that the interface is defined for anyone
who wishes to contribute an implementation. Declaring those
functions early also minimizes updates to the system header files
as the function implementations are added.
See also Q#11.6.
Q#11.8: I want to release my library to the GNO community. Is there anything
in particular that I should do?
A#11.8: Here's a checklist:
- Any symbols which should not be available to the user should
have their private flag set. In C, this corresponds to using
the "static" storage class specifier whenever possible.
- Ensure your library is compatible with ORCA/C's large memory
model.
- Write documentation, preferably one or more manual pages, for
any exported symbols. If your library uses configuration files,
write manual pages for those too (they belong in chapter 5).
- Specify in the manual pages any dependency on non-standard
libraries. Specify dependencies for all header files, whether
standard or not.
- Consider including your source code with your library. This
allows your contribution to survive even if your hard drive
crashes, your backups are destroyed, or you leave the GNO
community.
Q#11.9: How do I get the file descriptor from a stdio FILE pointer?
A#11.9: Use the fileno() macro.
This is defined in <stdio.h> as of GNO v2.0.6. For earlier
versions you will have to add it in yourself. The proper
macro definition for the ORCA/C headers is:
#define fileno(p) ((p)->_file)
Q#11.10: My (ported) source requires <sys/file.h>. Why isn't it there?
A#11.10: <sys/file.h> has been superceded by <sys/fcntl.h>. Update your
sources.
Q#11.11: Why, when I '#include <types.h>' (or some other file), does the
compiler take it out of my current directory instead of out of
the system header directories?
A#11.11: This is an unfortunate side-effect of using the ORCA/C "path"
pragma to avoid duplication of system header files between your
GNO and ORCA installations. (See Q#5.1, Q#6.1, Q#6.4, and
Q#6.5.)
The reason for the problem is that when the file is included
with the angle bracket syntax (vice double quotes), ORCA/C
will still search the current directory before those specified
by the "path" pragma.
At this time, the only known work-around is to avoid, in your
own sources, using file names used by the system header files.
Q#11.12: When using the December 1997 libraries (or later version), why are
my programs larger than they used to be?
A#11.12: There are a few reasons for this.
The first one is that when the libraries (which are mostly written
in C) are compiled, aggressive optimizations are not currently used.
This is because certain optimizations in ORCA/C are known to be
broken. This, combined with the fact that we are missing a lot
of automated test suites for the GNO (non-ORCA/C) additions to the
libraries, indicated that it would be best to ship the libraries
without much in the way of optimizations.
The second reason is probably more significant. When Jawaid provided
a libc and ORCALib for GNO v2.0.4, he made significant changes to
the stdio portion of ORCALib so that it would work with pipes and
sockets. Unfortunately, for whatever reason, the two versions of
ORCALib (the original version from Byte Works, and the modified
version from Procyon) were never merged. Therefore, when ORCALib
was updated for ORCA/C v2.1.x, the GNO-specific changes were
effectively lost.
When Devin took over maintenance of the GNO libraries in the spring
of 1997, he was (in order to get a stdio package that worked with
pipes) faced with the choice of either reimplementing Jawaid's
changes to stdio, or to use another implementation of stdio that
was written with pipes in mind.
The tradeoff is one of development time versus code size (and probably
speed). The ORCA stdio implementation is in assembly, so it is
small and fast. On the other hand, GNO v2.0.6 had been in the
"it's not ready yet" stage for quite a while. The choice was made
to use the 4.4BSD stdio implementation. This is the primary reason
why programs which use stdio are now larger than they were.
If your program does not use stdio, but is still significantly
larger, then it may be due to dependancies in libc; there are
some routines which currently depend on stdio but which need not.
These dependancies will be removed as time is available to do so.
Kernel Internals
----------------
Q#12.1: Can task-switching occur during an interrupt?
A#12.1: No.
Q#12.2: Can I tell GNO/ME to not task switch during a short (like a couple
of ASM instructions) sequence?
A#12.2: Turn off interrupts, or increment the busy flag around the code.
Debugging (During Program Development)
--------------------------------------
Q#13.1: What debuggers are available for GNO?
A#13.1: There are no GNO-specific debuggers, however there are at least two
popular ones that are compatible with GNO.
If you are programming in C, it is highly recommended that you
purchase "Splat!", written by Michael Hackett of Some Assembly
Required. This is also available from Procyon. See also Q#13.2.
If you are programming in assembly, it is recommended that you
install GSBug. This comes bundled with ORCA/M and is also available
for download from the Apple Inc dts ftp site. GSBug has many
add-on packages used to increase its functionality. Two of these
are Niftylist and Nexus.
Q#13.2: Why is the Splat! debugger crashing when my code calls fork(2)?
A#13.2: Splat was not originally designed for GNO. When GNO does a fork(2)
or fork2(2) call, some very non-standard things are happening in
the IIgs execution environment. Splat cannot currently handle
these operations.
A request has been submitted to the author of Splat! for an upgrade
to handle this behavior but he has not yet had time to do it; he
is also busy working on other IIgs projects.
Q#13.3: Part way through my debugging session, Splat! no longer shows my
source file. Why?
A#13.3: Your program is probably changing its current working directory.
The C preprocessor inserts tokens that tell the compiler which
file (and on which line) it is currently processing. This
information is eventually passed to the debugger. Some of the
pathnames are, in general, relative to the directory from which
your program was compiled.
Splat! uses these relative pathnames to locate the source files
that it is supposed to display. Unfortunately, the current version
of Splat! always searches for these files relative to the current
directory, not relative to the directory that was current at the
time which Splat! was invoked. Therefore, if your program changes
the current directory, the source files can no longer be found.
This problem can be avoided by inserting following preprocessor
directive at the top of all your source files:
#line 1 "/fully/qualified/path/name.c"
Of course, you should use the real path names to your source files,
not the one shown above. Do not use the __FILE__ macro as it
will be expanded to only a partial pathname under some circumstances,
such as when using occ(1).
There is a utility which automates this process, including an
option to remove the preprocessor directive. See the splatprep(1)
manual page for details.
General Problems
----------------
Q#14.1: Some programs I run have two cursors and sometimes characters I
type don't get sent to the program. When I quit the program, the
characters show up on the command line! What's wrong?
A#14.1: You need to set the auxiliary file type of the program in question
to $DC00. Use the chtyp command:
chtyp -a \$DC00 ProgramName
Note the '\' character; it must be there to escape the '$' character
from the shell, otherwise the $DC00 would be treated as a shell
variable.
Also note that this fix will not work if the program's file type
is S16 and the file resides on an HFS volume. (An EXE file on
an HFS volume should be fine.)
Q#14.2: Whenever I try to launch the Finder from GNO, I am told that the
Finder needs more memory. I know there is enough memory available.
What's the deal?
A#14.2: This was a bug in the GNO 1.0 kernel. Unfortunately, there is no
workaround. The only option is to upgrade to a current version
of GNO.
Q#14.3: My program is crashing when calling open(2). Why?
A#14.3: It may be due to a prototype/library mismatch. The GNO implementation
of open(2) is a variadic function. The third "mode" parameter must
be provided if and only if the second "oflag" parameter has the
O_CREAT flag set.
If calls to open result in a crash or stack error, you may have
either the wrong definition of open in <fcntl.h>, or you are not
getting open from 13/libc. See also Q#9.2, Q#11.2, Q#11.3, and Q#6.6.
Q#14.4: What are the known bugs?
A#14.4: First off, this answer only refers to GNO-specific bugs. You
should also consult the ORCA/C bug list (see Q#9.2).
As of mid-March 1998, there is an online bug tracking system
for GNO. You can get to it off of the GNO Documentation Page.
Its direct URL is:
http://www.gno.org/~gno/bugs.html
If you know of specific problems with GNO that are not listed
in the database, please enter them. The web interface is the
preferred method of submitting reports, but if that is not
feasible you can also send bug reports to the following address:
[email protected]
If you do not have a web browser, you can view current reports
by obtaining them through anonymous ftp at the following URL:
ftp://ftp.gno.org/pub/gno-bugs
You shouldn't archive these reports since they are continually
being updated; view them and throw them away.
*** The anon ftp directory has not yet been set up.
--
Tomorrow I will seven eagles see, a great comet will appear, and voices will
speak from whirlwinds foretelling monstrous and fearful things -- This
Universe never did make sense; I suspect that it was built on government
contract. - Robert Heinlein
