GNO Frequently Asked Questions (FAQ) List

Version: 1.18
Last Modified: 1998/05/06 05:12:23

Preamble

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,
<cmcurtin@interhack.net>.  It contains contributions (intentional
or otherwise) from many users of GNO.

The FAQ is currently maintained by Devin Reade, <gdr@eddore.myrias.com>.
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

Section 1: General

Section 2: Compatibility

Section 3: Documentation

Section 4: Programs

Section 5: System Installation

Section 6: Installing GNO with ORCA

Section 7: System Configuration

Section 8: Networking

Section 9: Porting UNIX Programs to the GNO Environment

Section 10: Compiling

Section 11: Libraries and Header Files

Section 12: Kernel Internals

Section 13: Debugging (During Program Development)

Section 14: General Problems


Section 1: General

Q#1.1: What is GNO?

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?

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?

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?

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?

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?

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?

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?

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.

Section 2: Compatibility

Q#2.1: With what standard version of UNIX is GNO compatible?

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)?

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?

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?

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?

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)?

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.

Section 3: Documentation

Q#3.1: What documentation comes with GNO?

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?

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?

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? 

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?

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?

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?

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?

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).

Section 4: Programs

Q#4.1: What other programs come with GNO?

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?

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?

Perhaps you could use the FTP-by-mail service. Send mail to
ftpmail@decwrl.dec.com 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?

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 <sbehrens@bigfoot.com> 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?

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?

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.

Section 5: System Installation

Q#5.1: For what are the various directories used?

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?

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?

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 ...

Section 6: Installing GNO with ORCA

Q#6.1: Do I need separate installations of ORCA/C for use with GNO and ORCA/Shell? 

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?

=== 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? 

=== 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?

=== 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?

=== 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?

=== 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? 

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? 

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? 

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? 

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

Section 7: System Configuration

Q#7.1: What patches should I have applied for GNO?

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? 

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? 

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?

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?

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)).

Section 8: Networking

Q#8.1: Does GNO provide TCP/IP and/or SLIP support?

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?

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?

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?

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 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?

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.

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?

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?

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.

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?

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?

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?

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?

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?

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.

Section 9: Porting UNIX Programs to the GNO Environment

Q#9.1: What programs/utilities should I have to port UNIX source code to GNO?

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? 

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?

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!

Section 10: Compiling

Q#10.1: Which language should I use?

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?

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?

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?

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?

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? 

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.

Section 11: Libraries and Header Files

Q#11.1: I keep getting "va_end" as an unresolved symbol when linking. Why?

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? 

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?

Try the command 'ls -1n' or 'ls -ln'.

Q#11.4: How can I sort my libraries (or other files)?

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?

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?

The GNO libraries are still undergoing active development.  If you
find that a standard or common routine is missing, then contact
Devin Reade <gdr@eddore.myrias.com> 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? 

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? 

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?

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?

<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? 

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? 

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.

Section 12: Kernel Internals

Q#12.1: Can task-switching occur during an interrupt?

No.

Q#12.2: Can I tell GNO/ME to not task switch during a short (like a couple of ASM instructions) sequence? 

Turn off interrupts, or increment the busy flag around the code.

Section 13: Debugging (During Program Development)

Q#13.1: What debuggers are available for GNO?

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)?

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? 

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.

Section 14: 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? 

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? 

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?

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?

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:

	gno-bugs@trenco.gno.org

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.
Devin Reade <gdr@eddore.myrias.com>