Subject: Frequently Asked Questions (FAQ) for comp.sys.apple2.gno
From: [email-masked] (Devin Reade)
Date: 27 Sep 1997 03:44:21 GMT
Newsgroups: comp.sys.apple2.gno

Last-modified: 1997/09/27 03:36:34
Version: 1.8
URL: http://web.cs.ualberta.ca/~glyn/FAQ.csa2g

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 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.cs.ualberta.ca/pub/glyn/FAQs/comp.sys.apple2.gno
	http://web.cs.ualberta.ca/~glyn/FAQ.csa2g

The FAQ was originally maintained by C. Matthew Curtin,
<[email-masked]>, <[email-masked]>.  It contains
contributions (intentional or otherwise) from many users of GNO.

The FAQ is currently maintained by Devin Reade, <[email-masked]>.
Questions, comments, suggestions, and submissions to this FAQ are welcome
and should be emailed to Devin Reade or posted to comp.sys.apple2.gno.

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.

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.

Table of Contents
=================

	General
	^^^^^^^
	Q#1:	What is GNO?
	Q#2:	What is the status of GNO?
	Q#3:	What is the current version of GNO?
	Q#4:	What are GNO's mininum system requirements?
	Q#5:	Where can I get GNO?
	Q#6:	What support is available for GNO?
	Q#7:	Where can I get the files/archives recommended in this FAQ?
	Q#8:	Why is this FAQ written in such a drab format?

	Compatibility
	^^^^^^^^^^^^^
	Q#9:	With what standard version of UNIX is GNO compatible?
	Q#10:	Can I run ORCA/Shell from GNO (or vice-versa)?
	Q#11:	Is GNO compatible with the SecondSight VGA card?
	Q#12:	Are desktop applications compatible with GNO?
	Q#13:	Can I use prizm (the ORCA desktop environment) with GNO?
	Q#14:	What new features are expected to be in the next version
		(2.0.6)?

	Documentation
	^^^^^^^^^^^^^
	Q#15:	What documentation comes with GNO?
	Q#16:	What additional documentation is recommended for GNO?
	Q#17:	What are all the numbers in parenthesis following program
		names?
	Q#18:	I've just finished writing a new program (or library or
		whatever). What documentation should I include?
	Q#19:	I'm writing a manual page. What format should I use?
	Q#20:	What should be in a manual page?
	Q#21:	Man(3) is too slow when formatting pages. Can I speed it up?
	Q#22:	What are the standard manual page chapters?

	Programs
	^^^^^^^^
	Q#23:	What other programs come with GNO?
	Q#24:	Are there any ftp sites for GNO utilities?
	Q#25:	I cannot ftp to caltech or ground. How can I get the GNO
		utilities?
	Q#26:	What is the most recent version of program XXXXXX?
	Q#27:	Which editor should I use?

	System Installation
	^^^^^^^^^^^^^^^^^^^
	Q#28:	For what are the various directories used?
	Q#29:	What should be in my gshrc file?

	Installing GNO with ORCA
	^^^^^^^^^^^^^^^^^^^^^^^^
	Q#30:	Do I need separate installations of ORCA/C for use with GNO
		and ORCA/Shell?
	Q#31:	How do I set up ORCA/C so that I can use it with GNO?
	Q#32:	GNO with ORCA: What should I use for compilation directories
		and prefixes?
	Q#33:	GNO with ORCA: Where should my C header files go?
	Q#34:	GNO with ORCA: What goes in the 13/orcacdefs/defaults.h
		file?
	Q#35:	GNO with ORCA: What header file modifications are necessary?
	Q#36:	GNO with ORCA: What libraries are used for the combination
		of GNO v2.0.4 and ORCA/C v2.0.x?
	Q#37:	GNO with ORCA: What libraries are used for the combination
		of GNO v2.0.4 and ORCA/C v2.1.x?
	Q#38:	GNO with ORCA: What libraries are used for the combination
		of GNO v2.0.6 and ORCA/C v2.0.x?
	Q#39:	GNO with ORCA: What libraries are used for the combination
		of GNO v2.0.6 and ORCA/C v2.1.x?

	System Configuration
	^^^^^^^^^^^^^^^^^^^^
	Q#40:	What patches should I have applied for GNO?
	Q#41:	How do I change the information that's printed before the
		login prompt?
	Q#42:	How do I map /usr, /local, /var, and other partitions to
		GS/OS volume or directory names?
	Q#43:	How do I set up cron?
	Q#44:	Why won't my entry in the inittab file work correctly?

	Networking
	^^^^^^^^^^
	Q#45:	Does GNO provide TCP/IP and/or SLIP support?
	Q#46:	What TCP/IP network utilities are available?
	Q#47:	Is there a WWW browser for GNO and GS/TCP?
	Q#48:	Can I use a serial card or internal modem with GNO?
	Q#49:	What should I use for my modem port control panel settings.
	Q#50:	How can I initialize my serial ports at GNO "boot" time?
	Q#51:	How do I hook up a terminal to the IIgs' printer/modem port?
	Q#52:	How do I enable GNO to activate dialup access.
	Q#53:	What do I use for a ProTERM termcap entry?
	Q#54:	Is there a mail/news package available for GNO?
	Q#55:	How do I use copycat?
	Q#56:	How do I use rz/sz?
	Q#57:	Why do I get errors when trying to access the (modem/serial)
		port?

	Porting UNIX Programs to the GNO Environment
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	Q#58:	What programs/utilities should I have to port UNIX source
		code to GNO?
	Q#59:	What are the common problems encountered when porting UNIX
		source to GNO?
	Q#60:	Are there any other recommendations for porting programs?

	Compiling
	^^^^^^^^^
	Q#61:	Which language should I use?
	Q#62:	Should I purchase the ORCA Subroutine Library Source?
	Q#63:	What is occ?
	Q#64:	What is dmake?
	Q#65:	What macros should I be using for conditional compilation?

	Libraries and Header Files
	^^^^^^^^^^^^^^^^^^^^^^^^^^
	Q#66:	I keep getting "va_end" as an unresolved symbol when
		linking. Why?
	Q#67:	Why do I keep getting "getc" and "putc" as unresolved
		symbols when linking?
	Q#68:	How can I tell what order my libraries are in?
	Q#69:	How can I sort my libraries (or other files)?
	Q#70:	How can I tell what is in library XXXX?
	Q#71:	Why isn't the common function XXXX in the libraries?
	Q#72:	Function XXXX is declared in the GNO header files, but it's
		not in the libraries. Why?
	Q#73:	I want to release my library to the GNO community. Is there
		anything in particular that I should do?
	Q#74:	How do I get the file descriptor from a stdio FILE pointer?
	Q#75:	My (ported) source requires <sys/file.h>. Why isn't it
		there?

	Kernel Internals
	^^^^^^^^^^^^^^^^
	Q#76:	Can task-switching occur during an interrupt?
	Q#77:	Can I tell GNO/ME to not task switch during a short (like a
		couple of ASM instructions) sequence?

	Debugging (During Program Development)
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	Q#78:	What debuggers are available for GNO?
	Q#79:	Why is the Splat! debugger crashing when my code calls
		fork(2)?
	Q#80:	Part way through my debugging session, Splat! no longer
		shows my source file. Why?

	General Problems
	^^^^^^^^^^^^^^^^
	Q#81:	Some programs I run have two cursors and sometimes
		characters I type don't get sent to the program. When I quit
		the program, the characters show up on the command line!
		What's wrong?
	Q#82:	Whenever I try to launch the Finder from GNO, I am told that
		the Finder needs more memory. I know there is enough memory
		available. What's the deal?
	Q#83:	My program is crashing when calling open(2). Why?
	Q#84:	What are the known bugs?

General
-------

Q#1:	What is GNO?
 
A#1:	GNO is a UNIX-like multitasking environment for the Apple IIGS.
	GNO provides:

        1. Pre-emptive multitasking.
        2. A shell that takes full advantage of the multitasking provided
	   (i.e., job control), and 'regular expressions', and a simple
	   programming language.
	3. A powerful programming environment. All the calls needed to
	   control processes, support Inter-Process Communication (IPC),
	   and other tools necessary to support multitasking are
	   available to the programmer.
	4. The first completely consistent method for accessing serial
	   and console I/O on the Apple II.  This makes such things as
	   attaching terminals to your GS, multiline BBSes, remote
	   dial-ups, UUCP or SLIP that doesn't take over your computer,
	   as well as countless other applications a possibility.

Q#2:	What is the status of GNO?
 
A#2:	GNO was developed by Procyon Enterprises (Jawaid Bazyar, prop.).
	Until August 1997, Procyon 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#3:	What is the current version of GNO?

A#3:	The currently released version is v2.0.4.  The version currently
	under development is v2.0.6.  v2.0.5 never had a general release,
	and is not available.

Q#4:	What are GNO's mininum system requirements?

A#4:	The GNO documentation specifies that the minimum requirement
	is an Apple IIGS with 1.25 megs 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#5:	Where can I get GNO?

A#5	The base GNO distribution may be obtained via anonymous ftp
	from the following sites.  See also Q#7:

		ftp://ftp.hypermall.com/pub/gno
		ftp://trenco.myrias.com/pub/apple2/gno/Version_2.0.4_base

	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.  At last check, this is the Kernel
	Reference Manual, the GSH Reference Manual, selected manual
	pages, and the release 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#6:	What support is available for GNO?

A#6:	For the most part, the only support available is that given
	by GNO developers in the Apple II community.  In other words,
	what you get is what you get.  Often a polite question posted
	to comp.sys.apple2.gno will result in a helpful response.

	Procyon still offers limited support for people who purchased
	GNO prior to August 1997.  No support is available from Procyon
	for those who obtained GNO after it changed to freeware status.

	There is a group of programmers (known as the gno-devel list)
	working toward getting v2.0.6 out the door.  Information regarding
	this work will be posted to comp.sys.apple2.gno as it becomes
	available.  Have patience; we all have day jobs and this is
	a hobby.

Q#7:	Where can I get the files/archives recommended in this FAQ?

A#7:	The "core" files of the GNO distribution (such as the GNO
	kernel and gsh(1)) are available through anonymous ftp as
	described in Q#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://trenco.myrias.com/pub/apple2
	The latter is the master site for GNO development, as of
	August 1997.  GNO-specific files can be found in the
	/pub/apple2/gno directory on trenco.

	*** trenco does not, as yet, have many files on it.  This
	    will change.

	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#8:	Why is this FAQ written in such a drab format?

A#8:	Because it was considered critical that there is a easily
	readable text-only version available.  Combined with the fact
	that the maintainer didn't want to spend a lot of time with
	source translators, this placed a restriction on the type
	of formatting available.

Compatibility
-------------

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

A#9:	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#10:	Can I run ORCA/Shell from GNO (or vice-versa)?

A#10:	No.  GNO with a shell (such as gsh) is intended to be a replacement
	for ORCA/Shell.  Similarily, 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#11:	Is GNO compatible with the SecondSight VGA card?

A#11:	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#12:	Are desktop applications compatible with GNO?
 
A#12:	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#13:	Can I use prizm (the ORCA desktop environment) with GNO?

A#13:	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#14:	What new features are expected to be in the next version (2.0.6)?

A#14:	This list is unofficial and subject to change.  With that in mind:

	- Complete kernel support for TCP/IP.
	- Lots of little bug fixes that should improve stability.
	- An updated and expanded libc.
	- An OrcaLib compatible with the ORCA/C v2.1 OrcaLib.
	- Updates to various shell programs.

Documentation
-------------

Q#15:	What documentation comes with GNO?

A#15:	GNO/ME Overview
	Kernel Reference Manual
	Shell (gsh) User's Manual
	Manual Pages (some printed, all online)

	*** As of this writing, the (originally printed) documentation for
	GNO v2.0.4 is not yet available online.  This will be changing,
	hopefully soon.

Q#16:	What additional documentation is recommended for GNO?

A#16:	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#17:	What are all the numbers in parenthesis following program names?

A#17:	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.  Similarily, "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#18:	I've just finished writing a new program (or library or whatever).
	What documentation should I include?

A#18:	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#19).  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#26.

	  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#19:	I'm writing a manual page.  What format should I use?

A#19:	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 souce can be reformatted
	"on the fly" to suit different terminal characteristics.  See also
	Q#21.

Q#20:	What should be in a manual page?

A#20:	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	- relevent 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#21:	Man(3) is too slow when formatting pages.  Can I speed it up?

A#21:	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#22:	What are the standard manual page chapters?

A#22:	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 publically available
	Fortran compiler).

Programs
--------

Q#23:	What other programs come with GNO?
 
A#23:	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#24:	Are there any ftp sites for GNO utilities?

A#24:	Yes.  Many Apple II ftp sites have GNO-specific directories, although
	GNO stuff can also be found in other directories on these sites.

	The two primary sites are:
		ftp://apple2.caltech.edu/Zocalo/pub/apple2/shellprogs
		ftp://ground.isca.uiowa.edu/apple2/apple16/gno

	See the comp.sys.apple2 FAQ for other Apple II ftp sites.

	*** trenco.myrias.com is coming online but is not quite ready yet.

Q#25:	I cannot ftp to caltech or ground.  How can I get the GNO utilities?

A#25:	Perhaps you could use the FTP-by-mail service. Send mail to
	[email-masked] 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#7).

Q#26:	What is the most recent version of program XXXXXX?

A#26:	The best way to find out what programs are available for GNO,
	including version numbers, authors, and other information is
	to use the describe(1) database.  The program, database, and
	maintenance utilities are available at the usual ftp sites.

	Soenke Behrens <[email-masked]> 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#27:	Which editor should I use?

A#27:	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#81).

System Installation
-------------------

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

A#28:	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#42).
	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/doc		READMEs, release notes, etc
	/lang/orca/include	standard ORCA/C header files
	/lang/orca/languages	compilers
	/lang/orca/lib		standard ORCA libraries (not used for GNO)
	/lang/orca/lib/orcacdefs	contains defaults.h; otherwise empty
	/lang/orca/shell	ORCA editor and ORCA/Shell config files
	/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/orca		ORCA support files
	/usr/orca/bin		ORCA/Shell compatible programs
	/usr/orca/man/man1	manual pages for ORCA/Shell programs (nroff,
				troff, or aroff source)
	/usr/orca/man/cat1	manual pages for ORCA/Shell programs 
				(preformatted)
	/usr/sbin		system maintenance programs
	/var			heavy write-use (variable) partion
	/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#29:	What should be in my gshrc file?

A#29:	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#32)
		prefix	13	/lib
		prefix	14	/tmp
		prefix	15	/lang/orca/shell
		prefix	16	/lang/orca/languages
		prefix	17	/usr/orca/bin

		# 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 /usr/orca/bin /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:/usr/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

Installing GNO with ORCA
------------------------

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

A#30:	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.

	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#31:	How do I set up ORCA/C so that I can use it with GNO?

A#31:	=== See the CAVEAT in Q#30 ===

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

	The next step is to create the required directories and set up
	the appropriate GS/OS prefix numbers.  This procedure is documented
	in Q#32 (don't forget to update your 15/login and ~/gshrc files).

	Now move files from your ORCA distribution into directories 15,
	16, 17, and 17/help, as appropriate.  Don't overwrite the 15/login
	file you just edited.

	The next step is to move your C header files to the appropriate
	directories.  This is explained in Q#33.

	Next, set up your defaults.h file as described in Q#34.  As per
	the caveat in Q#30, 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#35.

	Next you have to set up your libraries.  This information is specific
	to your GNO-ORCA/C version combination.  See questions Q#36, Q#37,
	Q#38, or Q#39 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#69).

	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.

Q#32:	GNO with ORCA: What should I use for compilation directories and
	prefixes?

A#32:	=== See the CAVEAT in Q#30 ===

	In order to minimize file duplication for running GNO and ORCA/Shell
	(but not concurrently -- see Q#10), you should set your prefixes up
	as follows.  For GNO, these "volumes" may be defined in /etc/namespace
	(see Q#42).  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	/usr/orca/bin			ORCA-compatible utils
	-	/usr/orca/bin/help		ORCA-compatible util desc.
	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
	-	/usr/orca/man/man1		3rd party ORCA man pages

		ORCA (not used by GNO)
		^^^^^^^^^^^^^^^^^^^^^^
	13	/lang/orca/lib			ORCA libraries

	The prefixes shown should be set up in your ~/gshrc file (for GNO),
	or your 15/login file (for ORCA/Shell).

Q#33:	GNO with ORCA: Where should my C header files go?

A#33:	=== See the CAVEAT in Q#30 ===

	First, the only file that should be in 13/orcacdefs is your
	defaults.h file.  Since prefix 13 is different for GNO and ORCA/Shell
	(see Q#32), there will be two versions of defaults.h.  See Q#34
	regarding the contents of this file.

	C header files should be kept in the following locations:

		/lang/orca/include		ORCA/C header files
		/usr/include			GNO header files
		/HFSinclude			GNO header files (GNO v2.0.6,
						only if /usr is not an HFS
						volume.)

	If you already have a /usr/include directory containing custom
	or other third-party header files, I recommend moving them to
	/usr/local/include or /local/include.

Q#34:	GNO with ORCA: What goes in the 13/orcacdefs/defaults.h file?

A#34:	=== See the CAVEAT in Q#30 ===

	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/include"

	For ORCA/Shell, the /lang/orca/lib/orcacdefs/defaults.h file
	should contain:

		#define __appleiigs__
		#pragma path "/lang/orca/include"

Q#35:	GNO with ORCA: What header file modifications are necessary?

A#35:	=== See the CAVEAT in Q#30 ===

	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 GNO distributions
	v2.0.1 through v2.0.4.  These should all be copied, in sequence,
	into the /usr/include directory as discussed in Q#33.	(Versions
	2.0.2, 2.0.3, and 2.0.4 were incremental changes, not complete
	distributions.)

	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/include
				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/include
				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/include
				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/include
				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/include into /usr/include, then edit
	the copy in /usr/include.  Do not modify files in /lang/orca/include.

	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 *);
			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/types.h:
		Change the typedef of sig_t to:

			typedef void (*sig_t)(void);

	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#36 or Q#37). 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:

			int umask(int);
			char *dirname (const char *);
			char *basename (const char *);

Q#36:	GNO with ORCA: What libraries are used for the combination of
	GNO v2.0.4 and ORCA/C v2.0.x?

A#36:	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#37:	GNO with ORCA: What libraries are used for the combination of
	GNO v2.0.4 and ORCA/C v2.1.x?

A#37:	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#66.

	You should also install the list of recommended libraries listed
	in the latter part of Q#36.

	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#38:	GNO with ORCA: What libraries are used for the combination of
	GNO v2.0.6 and ORCA/C v2.0.x?

A#38:	This combination is no longer supported.  You will have to
	upgrade to ORCA/C v2.1.x.

Q#39:	GNO with ORCA: What libraries are used for the combination of
	GNO v2.0.6 and ORCA/C v2.1.x?

A#39:	You must have the following libraries in the sequence given:

		/lib/lcrypt	(GNO v2.0.6)
		/lib/lregexp	(GNO v2.0.6)
		/lib/lstring	(GNO v2.0.6)
		/lib/ltermcap	(GNO v2.0.6)
		/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.
		/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:

		/usr/lib/lgnoasm
		/usr/lib/lenviron
		/usr/lib/lstack

System Configuration
--------------------

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

A#40:	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.ugcs.caltech.edu/pub/nathan/gupp1.04.shk.  See also Q#84.

Q#41:	How do I change the information that's printed before the login
	prompt?

A#41:	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#42:	How do I map /usr, /local, /var, and other partitions to GS/OS
	volume or directory names?

A#42:	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#43:	How do I set up cron?

A#43:	There should be man pages for this, but there doesn't seem to be
	any yet.  (There should be a cron(8), crontab(1), and crontab(5).)

	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 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.  This field is IIgs specific;
	it does not appear in UNIX crontab files.

	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#44:	Why won't my entry in the inittab file work correctly?

A#44:	There are two common sources of problems.  The first is due
	to improper syntax in the inittab file.  See the inittab(5) and
	initd(8) manual pages for the correct syntax.

	The second common problem is not due to the inittab file, but
	rather because the command you are trying to invoke is being
	invoked incorrectly.  The way to check if this is the case is
	to run the command interactively and see what diagnostic messages
	appear.  You should also check the system log files for messages
	(see syslogd(8)).

Networking
----------

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

A#45:	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.  Furthermore, GS/TCP is being developed
	by Derek Taubert.  Extra information (including current status)
	on this project is available on the GS/TCP web page:

		http://www.geeks.org/~taubert/gstcp/index.html

Q#46:	What TCP/IP network utilities are available?

A#46:	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#47:	Is there a WWW browser for GNO and GS/TCP?

A#47:	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.

Q#48:	Can I use a serial card or internal modem with GNO?

A#48:	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#49:	What should I use for my modem port control panel settings.

A#49:	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#50:	How can I initialize my serial ports at GNO "boot" time?

A#50:	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#51:	How do I hook up a terminal to the IIgs' printer/modem port?

A#51:	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#50 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#52:	How do I enable GNO to activate dialup access.

A#52:	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#50 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 caridge return (ends command)

Q#53:	What do I use for a ProTERM termcap entry?

A#53:	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#54:	Is there a mail/news package available for GNO?

A#54:	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#26).

	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#55:	How do I use copycat?

A#55:	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#56:	How do I use rz/sz?

A#56:	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#55.  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 recognise 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#57:	Why do I get errors when trying to access the (modem/serial) port?

A#57:	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		2	.ttyb

	Finally, ensure that SIM (the Serial Interrupt Manager) is present
	and active.  This is an init in your system.setup directory:
		*/system/system.setup/sim

	Remember to reboot your system if you've made any changes in
	or to comply with the above requirements.
		
Porting UNIX Programs to the GNO Environment
--------------------------------------------

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

A#58:	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#59:	What are the common problems encountered when porting UNIX source
	to GNO?

A#59:	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 relevent:

	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 recognise
		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
		relevent 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
		preceeded 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 concensus 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 preceeded 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#60:	Are there any other recommendations for porting programs?

A#60:	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#31 and Q#35.

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

	  Make sure you read the both the ORCA/C manual and release notes;
	  there are times (such as within variadic functions) that you
	  cannot use stack checking or repair code.

	  When you're finished development, you can replace the debugging
	  flag with "-O" for optimization.  Don't forget to test your
	  optimized program before you release it!
	
Compiling
---------

Q#61:	Which language should I use?

A#61:	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 dependant 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#62:	Should I purchase the ORCA Subroutine Library Source?

A#62:	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#63:	What is occ?

A#63:	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#64:	What is dmake?

A#64:	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 dependancy
	lists.  It's behavior is controlled through the use of a 
	"makefile" (sometimes "makefile.mk"), which is a text file
	defining dependancy 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#65:	What macros should I be using for conditional compilation?

A#65:	There are four general areas where certain "standard" macros
	are used ("standard" is quoted because only those explicity
	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 relevent documentation (compiler manual, ISO/ANSI or POSIX
	standards, GS/OS ref manual) for more details.

Libraries and Header Files
--------------------------

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

A#66:	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#30 and Q#37).

	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#67:	Why do I keep getting "getc" and "putc" as unresolved symbols
	when linking?

A#67:	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#68:	How can I tell what order my libraries are in?

A#68:	Try the command 'ls -1n' or 'ls -ln'.

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

A#69:	This isn't really a GNO question, but it's included here because
	of its relevence to Q#68 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#70:	How can I tell what is in library XXXX?

A#70:	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#18, Q#19, and Q#20).

	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#71:	Why isn't the common function XXXX in the libraries?

A#71:	The GNO libraries are still undergoing active development.  If you
	find that a standard or common routine is missing, then contact
	Devin Reade <[email-masked]> 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#19).  Distributing the work results in faster updates.

Q#72:	Function XXXX is declared in the GNO header files, but it's not in
	the libraries.  Why?

A#72:	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#71.

Q#73:	I want to release my library to the GNO community.  Is there anything
	in particular that I should do?

A#73:	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 dependancy on non-standard
	  libraries.  Specify dependancies 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#74:	How do I get the file descriptor from a stdio FILE pointer?

A#74:	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#75:	My (ported) source requires <sys/file.h>.  Why isn't it there?

A#75:	<sys/file.h> has been superceded by <sys/fcntl.h>.  Update your
	sources.

Kernel Internals
----------------

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

A#76:	No.

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

A#77:	Turn off interrupts, or increment the busy flag around the code.

Debugging (During Program Development)
--------------------------------------

Q#78:	What debuggers are available for GNO?

A#78:	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#79.

	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#79:	Why is the Splat! debugger crashing when my code calls fork(2)?

A#79:	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#80:	Part way through my debugging session, Splat! no longer shows my
	source file.  Why?

A#80:	Your program is probably changing its current working directory.

	The C preprocessor inserts tokens that tell the compiler which
	file (and on which line) it is currently processing.  This
	information is eventually passed to the debugger.  Some of the
	pathnames are, in general, relative to the directory from which
	your program was compiled.

	Splat! uses these relative pathnames to locate the source files
	that it is supposed to display.  Unfortunately, the current version
	of Splat! always searches for these files relative to the current
	directory, not relative to the directory that was current at the
	time which Splat! was invoked.  Therefore, if your program changes
	the current directory, the source files can no longer be found.

	This problem can be avoided by inserting following preprocessor
	directive at the top of all your source files:
		#line 1 "/fully/qualified/path/name.c"
	Of course, you should use the real path names to your source files,
	not the one shown above.  Do not use the __FILE__ macro as it
	will be expanded to only a partial pathname under some circumstances,
	such as when using occ(1).

	There is a utility which automates this process, including an
	option to remove the preprocessor directive.  See the splatprep(1)
	manual page for details.

General Problems
----------------

Q#81:	Some programs I run have two cursors and sometimes characters I
        type don't get sent to the program. When I quit the program, the
        characters show up on the command line! What's wrong?
 
A#81:	You need to set the auxilliary 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#82:	Whenever I try to launch the Finder from GNO, I am told that the 
        Finder needs more memory. I know there is enough memory available.
        What's the deal?

A#82:	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#83:	My program is crashing when calling open(2).  Why?

A#83:	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#59, Q#67, Q#68, and Q#35.

Q#84:	What are the known bugs?

	First off, this is only a list of GNO-specific bugs.  You should
	also consult the ORCA/C bug list (see Q#59).  If this answer
	gets too long, it will be moved off to another document.

	This list refers to GNO v2.0.4.  In some cases, the problems
	have also been present in earlier versions.  This list does
	not include any information on GNO v2.0.6.

	KERNEL:
		The following are known kernel bugs that are patched by
		GUPP.  All are believed to be fixed in GNO v2.0.6. (GUPP
		may still be left active for its other bug fixes.)

			- The kernel would sometimes trash two bytes of
			  memory when pathnames were expanded (such as
			  /usr or 13:).  This would occur when the
			  expanded pathname was too long for a preallocated
			  buffer.  (The buffer allocation didn't take
			  into account the prepended length word.)

			- When an application was launched, there was an
			  unallocated byte past the end of a memory block
			  which was being zeroed.
		
			- For the v2.0.4 kernel, the kernVersion(2) call 
			  was returning v2.0.0.

		In the InitWildcardGS shell call, bit 0x2000 (traverse
		subdirectories) is not honoured.

		If there is a trailing delimiter in the first field 
		of /etc/namespace, the mappings do not occur as expected.
		For example, if the first field is ":lib:" instead of
		":lib", then doing an "ls /lib" fails but "ls /lib:"
		works.

		If a process does a wait(2), and that process doesn't have
		any children, then the process will hang (in the wait).
		The wait(2) man page says that in such a case wait will
		return -1 and set errno to ECHILD.

		In pathnames, the kernel should collapse multiple adjacent
		occurances of the pathname delimiter (':' or '/') into
		a single occurance.  It doesn't currently do so.

		The fstat(2) system call, when called on a pipe or character
		special file, does not set the appropriate S_IREAD or
		S_IWRITE bits (they are clear).

	DRIVERS:
		Problems have been reported when attempting to use .ttyb
		(the printer port) with a modem, in that the modem does
		not respond.  The modem port (.ttya) works fine.

	LIBRARIES:
		The rexit(3) implementation is missing.  It's available
		at the ftp sites.

		In the libc(3) man page, the documented return value for
		access(3) is incorrect.  The implementation (correctly)
		returns -1 on failure, 0 on success.

		The implementation of chdir(2) doesn't check to see
		if the target directory exists; it just changes the
		prefix.

		fdopen(3) is missing as of GNO v2.0.4.  (It was present
		in earlier versions.)

		The prototype and implementation of mkdir(2) is nonstandard;
		normally this function should take a second (mode) parameter.

		For creat(2), the libc man page specifies that the semantics
		are similar to the ORCA/C implementation.  However, the
		ORCA/C man page specifies a zero return value on success
		(I suspect this is incorrect).  The GNO implementation
		definitely returns a non-negative file descriptor on success,
		and -1 on failure.

		sleep(3) invoked with a zero argument will hang the process.

		system(3) always returns zero, due to a faulty ExecuteGS
		implementation.

		opendir(3) appears to fail for pathnames containing the
		colon (':') character.

	GSH:
		There is a bug in the default gshrc file created by the
		installer.  See the GNO release notes for details.

		gsh's command line parser seems to get confused when 
		handling nested quotes, especially when there are spaces
		inside the quotes.  For example, this command should work
		but doesn't:
		   awk ' { print "Hello, world" } ' file
		The arguments awk receives look like this:
		   arg 0 (length 3) = awk
		   arg 1 (length 9) =  { print 
		   arg 2 (length 6) = Hello,
		   arg 3 (length 6) = world"
		   arg 4 (length 1) = }
		   arg 5 (length 5) =  file

		The ExecuteGS shell call always returns zero for an exit
		status.  This also indirectly affects system(3) and pclose(3).

		gsh seems only to honour the "prefix" command on the initial
		parsing of the gshrc file, or on the command line.  In
		particular, resetting your prefix in your gshrc file and
		then sourcing that file doesn't always reset the prefix.
		You have to log out and log in again for it to work
		consistentley.

		When invoked by popen(3), gsh will occasionally fail to 
		exit, and _may_ be failing to produce output.  This does
		not appear to be the fault of the popen(3) implementation,
		but it is the only place where the problem has been observed
		as yet.

	SYSTEM DAEMONS AND SUPPORT PROGRAMS:
		syslogd:	The LOG_LOCAL facilities don't appear to
				be recognised.

		init:		This should be located in /sbin/init, not
				/bin/init.

		cron:		The day-of-week and username fields seem
				to be ignored.

				If more than 10 values are specified in
				any of the date-time fields, cron corrupts
				its memory structures.

		su:		This appears to be broken.  It will lock
				up many systems.

	USER PROGRAMS:
		launch:		If GNO uses an HFS volume for its root 
				partition, then launch(1) cannot be used
				to launch ProDOS-8 programs (even though
				those programs reside on a ProDOS partition).
				You must quit GNO (without first using
				launch), and start the P8 program from 
				your regular program launcher.

				If you try to use launch(1) when GNO is
				installed on an HFS root partition, then
				after you switch to P8, you will be prompted
				to insert the HFS partition.  P8 cannot
				see any HFS partition, so your computer
				will be in an infinite loop.  You only choice
				is to reboot.

		rm:		(Really "cp -p rm".)  On HFS partitions, rm(1)
				will sometimes fail to remove directories 
				containing subdirectories.  The source of the
				problem is not yet known.  The failure will
				be accompanied by the message:

				$0061 GS/OS: End of directory has been reached

		more:		When multiple files are viewed using more:
					more file1 file2 file3 file4
				The bottom portions of the files are 
				sometimes not shown.  More also appears
				to dump random control characters to the
				console under these conditions.  Consider
				using less(1) until this problem is fixed.
--
	Devin Reade	[email-masked]