ftp.pasteur.org/FAQ//ftp-pasteur-org-FAQ.zip/FAQ/apple2/GNO-faq

Internet Message Format | 1999-11-07 | 103.4 KB

Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!news-out.cwix.com!newsfeed.cwix.com!newshub.northeast.verio.net!news.he.net!feeder.via.net!newshub1.home.com!news.home.com!news1.rdc1.ab.home.com.POSTED!not-for-mail
From: [e-mail] (Devin Reade)
Newsgroups: comp.sys.apple2.gno,comp.answers,news.answers
Subject: comp.sys.apple2.gno FAQ (v1.18)
Supersedes: <[e-mail]>
Followup-To: comp.sys.apple2.gno
Organization: Myrias Computer Technologies Corp
Lines: 2693
Sender: [e-mail]
Approved: [e-mail]
Distribution: world
Expires: 12/11/99 17:20:02
Message-ID: <[e-mail]>
Reply-To: [e-mail] (Devin Reade)
Summary: Contains information on the UNIX-like OS for the Apple IIgs.
Keywords: FAQ, GNO, Apple-II, UNIX, ORCA
X-Content-Currency: This FAQ changes regularly.  When a saved or printed copy
   is over 6 months old, please obtain a new one.  Instructions in the
   preamble indicate where to find them via NetNews, FTP, and the WWW.
Date: Sun, 07 Nov 1999 00:20:12 GMT
NNTP-Posting-Host: 24.64.124.43
X-Complaints-To: [e-mail]
X-Trace: news1.rdc1.ab.home.com 941934012 24.64.124.43 (Sat, 06 Nov 1999 16:20:12 PST)
NNTP-Posting-Date: Sat, 06 Nov 1999 16:20:12 PST
Xref: senator-bedfellow.mit.edu comp.sys.apple2.gno:7160 comp.answers:38387 news.answers:170492

Archive-name: apple2/GNO-faq
Last-modified: 06 May 1998 05:12:23
Version: 1.18
URL: http://www.gno.org/~gno/FAQ.html
Posting-Frequency: monthly

This is the Frequently Asked Questions (FAQ) posting of the
comp.sys.apple2.gno newsgroup.  This document can be freely copied so
long as
    1. it is not sold (although it may be included in commercial
       distributions of Apple II archives such as the Golden Orchard
       CD series); and
    2. any sections reposted elsewhere from it are credited back to
       this FAQ with the FAQ's copyright info and official FTP and
       WWW location left in place.
Explicit permission is granted to carry this FAQ on electronic forums
dealing with Apple II computers such as BBSs and service providers
such as Genie and Delphi.

This FAQ is available via ftp and on the WWW at

    ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/faq/CURRENT
    http://www.gno.org/~gno/FAQ.html

A summary of recent updates may be found at

    ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/faq/LOG
    http://www.gno.org/~gno/FAQ-log.html

This FAQ may also be found in archives of comp.answers and news.answers,
such as those at rtfm.mit.edu.

The question numbers in this FAQ are auto-generated.  Therefore, when
referring to questions in this FAQ, please either give the version number
of the FAQ or (preferably) give some context that identifies to which
question you refer.

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

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

This FAQ is undergoing active development. Consequently, some questions
may have annotations starting with three asterisks ("***").  These are
questions that are in the process of having their answers written or
modified.

In the event that this FAQ appears to be abandoned, someone else is
welcome to take it over as the official maintainer or to use this FAQ
as the basis for a new one, provided that you credit the previous
maintainers.  The criteria for abandonment are:
    1.  The FAQ has not been updated nor posted to comp.sys.apple2.gno
        for a period of at least six months;
    2.  Attempts to contact the current maintainer (Devin Reade)
        have failed.  You must try for a period not less than 30
        days, and you must try contacting the maintainer through
        email, and postings to comp.sys.apple2.gno and the Delphi
        (delphi.com) Apple II Programmers' Forum.
In addition, please ensure that there is a general consensus on
comp.sys.apple2.gno that the FAQ is indeed abandoned before you attempt
to take it over.  I have not included this as a criterion since a
"general consensus" is difficult to quantify in any practical sense.

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

    General
    ^^^^^^^
    Q#1.1:    What is GNO?
    Q#1.2:    What is the status of GNO?
    Q#1.3:    What is the current version of GNO?
    Q#1.4:    What are GNO's minimum system requirements?
    Q#1.5:    Where can I get GNO?
    Q#1.6:    What support is available for GNO?
    Q#1.7:    Where can I get the files/archives recommended in this FAQ?
    Q#1.8:    Why is this FAQ written in such a drab format?

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

    Documentation
    ^^^^^^^^^^^^^
    Q#3.1:    What documentation comes with GNO?
    Q#3.2:    What additional documentation is recommended for GNO?
    Q#3.3:    What are all the numbers in parenthesis following program
        names?
    Q#3.4:    I've just finished writing a new program (or library or
        whatever). What documentation should I include?
    Q#3.5:    I'm writing a manual page. What format should I use?
    Q#3.6:    What should be in a manual page?
    Q#3.7:    Man(3) is too slow when formatting pages. Can I speed it up?
    Q#3.8:    What are the standard manual page chapters?

    Programs
    ^^^^^^^^
    Q#4.1:    What other programs come with GNO?
    Q#4.2:    Are there any ftp sites for GNO utilities?
    Q#4.3:    I cannot ftp to caltech or ground. How can I get the GNO
        utilities?
    Q#4.4:    What is the most recent version of program XXXXXX?
    Q#4.5:    Which editor should I use?
    Q#4.6:    What command line flags does gsh(1) accept?

    System Installation
    ^^^^^^^^^^^^^^^^^^^
    Q#5.1:    For what are the various directories used?
    Q#5.2:    What should be in my gshrc file?
    Q#5.3:    Where should I install custom additions to GNO?

    Installing GNO with ORCA
    ^^^^^^^^^^^^^^^^^^^^^^^^
    Q#6.1:    Do I need separate installations of ORCA/C for use with GNO
        and ORCA/Shell?
    Q#6.2:    How do I set up ORCA/C so that I can use it with GNO?
    Q#6.3:    GNO with ORCA: What should I use for compilation directories
        and prefixes?
    Q#6.4:    GNO with ORCA: Where should my C header files go?
    Q#6.5:    GNO with ORCA: What goes in the 13/orcacdefs/defaults.h
        file?
    Q#6.6:    GNO with ORCA: What header file modifications are necessary?
    Q#6.7:    GNO with ORCA: What libraries are used for the combination
        of GNO v2.0.4 and ORCA/C v2.0.x?
    Q#6.8:    GNO with ORCA: What libraries are used for the combination
        of GNO v2.0.4 and ORCA/C v2.1.x?
    Q#6.9:    GNO with ORCA: What libraries are used for the combination
        of GNO v2.0.6 and ORCA/C v2.0.x?
    Q#6.10:    GNO with ORCA: What libraries are used for the combination
        of GNO v2.0.6 and ORCA/C v2.1.x?

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

    Networking
    ^^^^^^^^^^
    Q#8.1:    Does GNO provide TCP/IP and/or SLIP support?
    Q#8.2:    Is GS/TCP available? Where can I get it?
    Q#8.3:    Does Marinetti work with GNO?
    Q#8.4:    What TCP/IP network utilities are available?
    Q#8.5:    Is there a WWW browser for GNO and GS/TCP?
    Q#8.6:    Can I use a serial card or internal modem with GNO?
    Q#8.7:    What should I use for my modem port control panel settings.
    Q#8.8:    How can I initialize my serial ports at GNO "boot" time?
    Q#8.9:    How do I hook up a terminal to the IIgs' printer/modem port?
    Q#8.10:    How do I enable GNO to activate dialup access.
    Q#8.11:    What do I use for a ProTERM termcap entry?
    Q#8.12:    Is there a mail/news package available for GNO?
    Q#8.13:    How do I use copycat?
    Q#8.14:    How do I use rz/sz?
    Q#8.15:    Why do I get errors when trying to access the (modem/serial)
        port?

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

    Compiling
    ^^^^^^^^^
    Q#10.1:    Which language should I use?
    Q#10.2:    Should I purchase the ORCA Subroutine Library Source?
    Q#10.3:    What is occ?
    Q#10.4:    What is dmake?
    Q#10.5:    What macros should I be using for conditional compilation?
    Q#10.6:    When I'm using the new header files (post-v2.0.4), sometimes
        ORCA/C can't find my header files. Why?

    Libraries and Header Files
    ^^^^^^^^^^^^^^^^^^^^^^^^^^
    Q#11.1:    I keep getting "va_end" as an unresolved symbol when
        linking. Why?
    Q#11.2:    Why do I keep getting "getc" and "putc" as unresolved
        symbols when linking?
    Q#11.3:    How can I tell what order my libraries are in?
    Q#11.4:    How can I sort my libraries (or other files)?
    Q#11.5:    How can I tell what is in library XXXX?
    Q#11.6:    Why isn't the common function XXXX in the libraries?
    Q#11.7:    Function XXXX is declared in the GNO header files, but it's
        not in the libraries. Why?
    Q#11.8:    I want to release my library to the GNO community. Is there
        anything in particular that I should do?
    Q#11.9:    How do I get the file descriptor from a stdio FILE pointer?
    Q#11.10:  My (ported) source requires <sys/file.h>. Why isn't it
        there?
    Q#11.11:  Why, when I '#include <types.h>' (or some other file), does
        the compiler take it out of my current directory instead of
        out of the system header directories?
    Q#11.12:  When using the December 1997 libraries (or later version),
        why are my programs larger than they used to be?

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

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

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

General
-------

Q#1.1:    What is GNO?

A#1.1:    GNO is a UNIX-like multitasking environment for the Apple IIGS.
    GNO provides:

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

Q#1.2:    What is the status of GNO?

A#1.2:    GNO was developed by Procyon Enterprises (Jawaid Bazyar, prop.).
    Until August 1997, GNO was a commercial product.  In August 1997,
    Jawaid changed GNO's status to that of freeware.  Procyon still
    retains the copyright on the kernel, gsh, and other components
    which were written by or for Procyon.

    GNO IS NOT PUBLIC DOMAIN.

Q#1.3:    What is the current version of GNO?

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

    For those programmers using ORCA/C v2.1.x, there was a update made
    available (for both GNO v2.0.4 and GNO v2.0.6 users) on 22 Dec 97.
    It consists of updated headers, libraries, and manual pages.  It
    is available at the following site:

        ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base206

Q#1.4:    What are GNO's minimum system requirements?

A#1.4:    The GNO documentation specifies that the minimum requirement
    is an Apple IIGS with 1.25 MB of memory and a 3.5" disk drive.
    Realistically (especially with all the third-party add-ons),
    a hard drive (or other large mass storage device) should be
    considered a necessity.  An accelerator and additional memory
    is recommended.

    There is not an official "minimum disk space" requirement
    as yet.  When this information becomes available, it will
    be added to this FAQ.

Q#1.5:    Where can I get GNO?

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

        ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base204
        ftp://ftp.hypermall.com/pub/gno

    The documentation for GNO v2.0.4 is now available via ftp and
    http at the following sites.  MS-Word versions are also available
    via ftp:

        http://www.gno.org/~gno
        ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc
        ftp://ftp.hypermall.com/pub/gno/docs

    For those who aren't able to make decent printed copies of the
    documentation on their own, Procyon still offers the printed
    documentation for sale.  (Do *NOT* ask Devin Reade for the
    printed documentation.  He does not work for Procyon and does
    not sell it.)  At last check, this is the Kernel Reference Manual,
    the GSH Reference Manual, selected manual pages, and the release
    and installation notes.  This contents list is unofficial and
    subject to correction by Procyon.

    Procyon Enterprises Inc maintains a web page at:

        http://www.hypermall.com/companies/procyon

    or you can contact them by snail-mail at:

        Procyon, Inc.
        P.O. Box 620334
        Littleton, CO 80162-0334
        303/933-4649

Q#1.6:    What support is available for GNO?

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

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

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

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

A#1.7:    The "core" files of the GNO distribution (such as the GNO
    kernel and gsh(1)) are available through anonymous ftp as
    described in Q#1.5.

    Non-commercial files, unless otherwise specified, should be
    available from major Apple ftp sites.  There is often a GNO-
    specific directory, but compatible programs, patches, etc,
    may appear anywhere under the Apple II hierarchy.  The GNO
    distribution also contains many files in this category;
    ensure you have newest versions by checking the ftp sites.

    The three main Apple II sites are
        ftp://apple2.caltech.edu/Zocalo/pub/apple2
        ftp://ground.isca.uiowa.edu/apple2
        ftp://ftp.gno.org/pub/apple2
    The latter (also known as trenco.gno.org) is the master site for
    GNO development, as of August 1997.  GNO-specific files can be
    found in the /pub/apple2/gs.specific/gno directory on ftp.gno.org.

    Other sites are listed in the comp.sys.apple2 FAQ, which is
    available from the above two sites and
        http://www.visi.com/~nathan/a2/faq/csa2.html

Q#1.8:    Why is this FAQ written in such a drab format?

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

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

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

A#2.1:    GNO contains components that originate with a variety of
    flavors of UNIX.  These include 4.3BSD, XINU, and SYSV.
    It is mostly BSD.  As of GNO v2.0.6, GNO has become closer
    to 4.4BSD.  Work is in progress to make it as compliant as
    possible to POSIX 1003.1 and POSIX 1003.2.

Q#2.2:    Can I run ORCA/Shell from GNO (or vice-versa)?

A#2.2:    No.  GNO with a shell (such as gsh) is intended to be a replacement
    for ORCA/Shell.  Similarly, one cannot run GNO from ORCA/Shell.
    However, you can still use the various ORCA languages and (the
    majority of) utilities from GNO.  See the sections on "Programs"
    and "Compiling", below.

Q#2.3:    Is GNO compatible with the SecondSight VGA card?

A#2.3:    Yes. GNO is completely compatible with the SecondSight card.
    However, GNO's console driver currently does not support the
    SecondSight card's VGA specific text modes.  A SecondSight aware
    console driver is planned as a future enhancement.

Q#2.4:    Are desktop applications compatible with GNO?

A#2.4:    In most cases, yes. However, GNO doesn't currently allow more than
    one desktop program to run concurrently.  It does allow you to
    run multiple text applications with or without a desktop application,
    to the limits of your available memory.

    There is a program (also available from Procyon), called Switch-It!,
    that allows one two switch between running desktop programs.
    It is not multitasking (in that only the currently displayed
    desktop program is actually running), nor does it _require_
    GNO.  It is, however, complementary to and compatible with GNO.
    Other (text based) processes running in the background continue to
    do so when Switch-It! is active.

Q#2.5:    Can I use prizm (the ORCA desktop environment) with GNO?

A#2.5:    In a nutshell, no.  The exact reasons are not generally known,
    but the author (Mike Westerfield) does not ever expect to have
    a compatible version available.

Q#2.6:    What new features are expected to be in the next version (2.0.6)?

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

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

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

Q#3.1:    What documentation comes with GNO?

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

    Online versions of these documents are also available.  See Q#1.5.

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

A#3.2:    The GNO Overview has quite a complete reading list for users and
    programmers, and it is too long to go into detail here.  However,
    in general, the references are broken down into the following
    categories:
        - UNIX reference books.
        - C reference books.
        - Editor reference books.
        - Apple IIgs Programming References

    The following list, should also be considered "must have" for
    any serious programming:

        - The ORCA/C and/or ORCA/M manuals, as appropriate.
        - Toolbox volumes 1, 2, 3
        - Programmers' Reference for System 6.0/6.0.1
        - GS/OS Reference
        - Firmware Reference
        - Apple Technical Notes
        - Apple File Type Notes
        - A manual on 65816 assembly programming, if you are
          using assembly.  One very good manual is:
            Lichty, Ron and Eyes, David.  _Programming_the_IIgs_
            _in_Assembly_Language_, Brady, 1989.
            ISBN 0-13-729559-6
          You will likely have to get it second hand, as it is no
          longer in print.

    The following books are recommended:

        - Hardware Reference
        - Apple Numerics Manual
        - Device Driver Reference
        - IEEE Std 1003.1-1988 (or later) -- The POSIX standard
          for computer environments.
        - ANSI/ISO 9899 Standard (defines ANSI/C).
          This is an expensive document, but you get a cheap copy
          by purchasing Schildt, Herbert _The_Annotated_ANSI_
          _C_Standard_, McGraw-Hill, ISBN 0-07-881952-0.  The book
          is set up so that the standard is printed on the "left"
          pages and the annotations are on the "right" pages.
          MAKE SURE YOU USE ONLY THE LEFT PAGES; the annotations
          have just enough errors in them to be dangerous.  Some
          of the "left" pages (from the Standard) are also missing.

Q#3.3:    What are all the numbers in parenthesis following program names?

A#3.3:    When you see something like "ls(1)" in the documentation, it
    refers to something called "ls" which is documented in Chapter 1
    of the manual pages.  Similarly, "select(2)" is refering to
    something called "select" which is documented in Chapter 2.  To
    find out what the various chapters are for, type in the command
        man 4 intro
    substituting "4" for whichever chapter you wish to learn about.

Q#3.4:    I've just finished writing a new program (or library or whatever).
    What documentation should I include?

A#3.4:    Including the following documentation components will not only
    help anyone who is maintaining a GNO site, but they will also
    make your contribution look more professional.  Remember, if
    someone can't tell what your program is supposed to do, they
    are less likely to try it out.

    You should have:

    - A manual page (see also Q#3.5).  Unless your program requires
      a large reference manual ( > 5-10 pages of written text), the
      manual page should be the primary document.

      Ensure the man page is assigned to the correct section.  One
      common mistake is to mix up Section 1 (User Commands) with
      Section 8 (System Administration).

    - A describe(1) database entry.  Try to use the ".desc" suffix
      on the file name.  (For example, if you wrote the "foo" program,
      you should have a text file "foo.desc" containing the database
      entry.)  If you have WWW access, please update the online
      describe database maintained by Soenke Behrens -- see Q#4.4.

      The describe entry is very suitable as a brief README file
      when uploading your program to ftp sites, or when posting to
      comp.binaries.apple2.

      Describe entries should only be written for programs, not
      libraries or individual routines.

    - An rVersion resource fork.  If you don't want to write a rez
      source file, then use setvers(1).

      There is a new format out which includes rVersion as a subset.
      It is called rProgramInfo (or rProgInfo), and was formalized
      by Eric Shepherd.  Information on this is available at the
      usual ftp sites in the archive rProgInfo.shk.  See also the
      templates file listed later in this answer.

    - "Standard" help and version flags.  If possible, invoking your
      program with the "-V" (capital vee) flag should print the
      version number and exit.  Invoking it with the "-h" flag should
      print a usage (help) message and exit.  Use of the "-?" flag
      is discouraged because it is a meta-character in many shells.

      It may not be practical to support these two flags, such as
      if you are porting a program that already uses them for other
      purposes, or if you are writing a daemon.

    To make things easier, templates for manual pages, rVersion
    source files, and describe database entries are available at
    the usual sites.  Look for an archive with a name similar
    to
        templates[version_number].shk

Q#3.5:    I'm writing a manual page.  What format should I use?

A#3.5:    While man can handle both manually-edited preformatted pages and
    pages that are aroff source (created by AppleWorks-GS or a
    compatible editor), the recommended format is to use nroff source
    with tmac "an" extensions.

    The reason for this is that only nroff source can be reformatted
    "on the fly" to suit different terminal characteristics.  See also
    Q#3.7.

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

A#3.6:    Whatever is necessary.  However, there are some standard sections
    for manual pages, based on which section (chapter) the manual
    page is in.  Templates with the suggested manual page formats
    are available in the file
        templates[version_number].shk
    at the usual ftp sites.

    For programs in particular (typically Chapters 1, 6, and 8), here
    are some sections that should be in the man page.  The order of
    the first three are mandatory due to how some automated tools
    work.  The sequence on the remainder are suggested:
        NAME        - name and one line description
        SYNOPSIS    - list of options and arguments
        DESCRIPTION    - a detailed description
        OPTIONS        - explanation of the flags
        ENVIRONMENT    - relevant environment variables and their
                  semantics, if appropriate
        FILES        - related files, if appropriate
        BUGS        - known bugs, if appropriate
        AUTHOR        - your name and contact info, typically
                  an email address.  Include your smail
                  address at your own risk.
        LEGALITIES    - Commercial, freeware, shareware, public
                  domain, copyleft, ... ?
        ATTRIBUTIONS    - Give credit when due.  For example, if
                  your binary was linked with the ORCA
                  libraries, you should be including the
                  Run-Time Licence from Appendix C of the
                  ORCA/C manual.
        SEE ALSO    - related manual pages or other documents

Q#3.7:    Man(3) is too slow when formatting pages.  Can I speed it up?

A#3.7:    Actually, it's not man(3), but nroff(3) which is slow.  Nroff
    is in desperate need of an update, not only for speed but for
    functionality.

    In the interim, however, you can get a faster response from man
    at the cost of using more disk space by preformatting your man
    pages.  See catman(8).

Q#3.8:    What are the standard manual page chapters?

A#3.8:    Chapter 1:    Commands and Applications
    Chapter 2:    System Calls
    Chapter 3:    Library Routines
    Chapter 4:    Devices
    Chapter 5:    File Formats
    Chapter 6:    Games
    Chapter 7:    Miscellaneous
    Chapter 8:    System Administration

    For GNO, there should be no need to use Chapter n [New Commands],
    or Chapter l (ell) [Local Commands], unless (in the latter case)
    the manual page is for something that is not to be released to
    the GNO community.

    Chapter 3F is reserved for Fortran Routines, of which there
    are none at this time (due to the lack of a publicly available
    Fortran compiler).

Programs
--------

Q#4.1:    What other programs come with GNO?

A#4.1:    Lots of free utilities that bring some of the power of UNIX systems
    to the IIGS.  In addition to getting the utility executable files,
    you get the source for many of these.  These programs have been
    provided by various authors.

Q#4.2:    Are there any ftp sites for GNO utilities?

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

    The three primary general-purpose sites are:
        ftp://apple2.caltech.edu/Zocalo/pub/apple2/shellprogs
        ftp://ground.isca.uiowa.edu/apple2/apple16/gno
        ftp://ftp.gno.org/pub/apple2

    Trenco (trenco.gno.org or ftp.gno.org) is the master site for GNO
    development as of August 1997.  See Q#1.7.

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

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

A#4.3:    Perhaps you could use the FTP-by-mail service. Send mail to
    [e-mail] with the subject line of "help" and no body
    for information.

    Another alternative is to use the WWW to access those sites.
    WWW access information is available in the comp.sys.apple2 FAQ
    (see Q#1.7).

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

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

    Soenke Behrens <[e-mail]> also maintains an online
    describe database.  This tends to be the most up-to-date version,
    and is available at

        http://www.arrowweb.com/sbehrens/describe.htm

Q#4.5:    Which editor should I use?

A#4.5:    Whichever one you want.  Many editors work under GNO.  Some
    of the more popular ones are emacs (MicroEMACS), vi (Stevie),
    ORCA/Editor, Edit-16, and Rose.

    Many of these editors cannot be suspended from the shell.  Some
    have the "eating keystrokes" problem (see Q#14.1).

Q#4.6:    What command line flags does gsh(1) accept?

A#4.6:    There are two.  The first is "-c arg", which is supposed to allow
    one to specify a script on the command line.  This seems to be
    broken, though.

    The second one is "-f", which tells gsh not to parse its gshrc
    file, nor do other initialization tasks.  Think of it as "fast
    startup".  Unfortunately, empirical tests seem to indicate that
    gsh is no faster with this flag than without.

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

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

A#5.1:    The following is the suggested layout and use of various directories.
    Any given site will likely have more, but these are the "standard"
    ones.  Note that these don't necessarily have to be on different
    physical partitions due to the GNO namespace facility (see Q#7.3).
    This FAQ assumes the following directory structure:

    /HFSinclude        GNO standard C header files (required if and
                only if /usr/include is not on an HFS
                partition)
    /bin            basic standard programs
    /dev            device drivers
    /etc            configuration files
    /lang            languages
    /lang/orca        ORCA languages
    /lang/orca/languages        compilers
    /lang/orca/libraries        standard ORCA libraries (not used
                    for GNO; see /lib instead)
    /lang/orca/libraries/orcacdefs    standard ORCA/C header files
    /lang/orca/release.notes    READMEs, release notes, etc
    /lang/orca/shell        ORCA editor and ORCA/Shell config files
    /lang/orca/utilities        ORCA/Shell compatible programs
    /lang/orca/utilities/help    These are the ORCA utility help files,
                    which show brief usage information.
                    The preformatted manual pages that
                    come with some utils should _not_ go
                    here.
    /lang/orca/man/man1    manual pages for ORCA/Shell compatible
                programs (nroff, troff, or aroff source)
    /lang/orca/man/cat1    manual pages for ORCA/Shell compatible
                programs (preformatted).  These should not
                be confused with the "help" files in
                /lang/orca/utilities/help.
    /lib            standard GNO libraries
    /lib/RInclude        resource compiler include files
    /lib/orcacdefs        holds defaults.h; otherwise empty
    /tmp            scratch directory (for temporary files)
    /usr            UNIX system resources
    /usr/X            X (graphical interface) -related files
    /usr/X/bin        X programs
    /usr/X/lib        X libraries and configuration files
    /usr/X/man        X manual pages
    /usr/bin        additional standard programs
    /usr/games        games
    /usr/games/lib        game configuration files
    /usr/include        GNO standard C header files
    /usr/lib        optional libraries
    /usr/lib/sendmail.d    sendmail configuration files
    /usr/lib/tmac        nroff/troff macro files
    /usr/local        custom and local files
    /usr/local/bin        custom programs
    /usr/local/etc        custom configuration files
    /usr/local/include    custom C header files
    /usr/local/lib        custom libraries and configuration files
    /usr/local/man        manual pages for custom files
    /usr/man        standard manual pages
    /usr/man/cat[1-8]    standard manual pages (preformatted)
    /usr/man/man[1-8]    standard manual pages (nroff, troff, aroff)
    /usr/sbin        system maintenance programs
    /var            heavy write-use (variable) filesystem
    /var/adm        system administratin and log files
    /var/mail        user mailboxes
    /var/spool        spool directories for various daemons
    /var/spool/lpq        line printer spool directory
    /var/spool/news        news daemon spool directory

Q#5.2:    What should be in my gshrc file?

A#5.2:    Whatever you find necessary, keeping in mind that the gshrc file
    is parsed whenever an instantiation of gsh is started.  This implies
    that a long gshrc file can slow down your system.

    Here is one example of a minimal gshrc file. For formatting reasons
    in the FAQ, long lines have been split with a trailing '\' on
    the line to be continued.  Gsh doesn't understand this syntax, so
    be sure to enter them as a single line.

        # set prefixes for ORCA languages (see also Q#6.3)
        prefix    13    /lib
        prefix    14    /tmp
        prefix    15    /lang/orca/shell
        prefix    16    /lang/orca/languages
        prefix    17    /lang/orca/utilities

        # match lower prefixes. gsh _should_ update these
        # automatically, but doesn't.
        prefix    2    13
        prefix    3    14
        prefix    4    15
        prefix    5    16
        prefix    6    17

        # set search path -- gsh parses it backwards!
        set path="/usr/games /lang/orca/utilities /usr/X/bin /usr/bin\
            /bin /usr/local/bin"
        export path
        rehash

        # search path for man pages
        setenv MANPATH /man:/usr/man:/usr/local/man:/local/man:\
            /usr/X/man:/lang/orca/man

        # settings for occ(1):
        #    create *.o files instead of *.a files
        setenv CCEMULATE 1
        #    set the if and only if you are using ORCA/C 2.0.x.
        setenv CCOLD 1

Q#5.3:    Where should I install custom additions to GNO?

A#5.3:    Anything you add to your GNO installation beyond what is in the
    base installation should go into the /usr/local hierarchy.
    This will facilitate future updates, in that you will only have
    to replace those directories used by the GNO base distribution,
    and your customized files will not be overwritten.

    There are some exceptions to this.  For example, /etc/passwd,
    /etc/namespace, and a few other files that have to be customized
    do not and will not reside in the /usr/local hierarchy.  However,
    these will be kept to a minimum and will be explicitly mentioned
    in future release notes.

    If your installed man(1) cannot cannot handle manual pages in
    more than one directory hierarchy, then you need to upgrade your
    man to version 3.0 or later.

    GNO v2.0.4 CAVEAT
    ^^^^^^^^^^^^^^^^^

    When GNO v2.0.4 (and earlier versions) was released, there
    was no attempt made to have users put add-ons in the /usr/local
    hierarchy.  Therefore, if you're currently running GNO v2.0.4
    it is likely that you have a lot of custom items in /bin,
    /usr/bin, /usr/man, and related directories.  This is complicated
    by the fact that various packages that are considered "standard"
    (such as the Multiuser Update) were not part of the base GNO
    v2.0.4 distribution.

    If you are in this situation, then I suggest that you not
    worry at this time about moving existing programs to the
    /usr/local hierarchy.  Instead, defer this to when GNO v2.0.6
    is released.  In the interim, there is nothing stopping you
    from using the /usr/local hierarchy for anything new that you
    download ...

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

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

A#6.1:    At least partly, yes, although it is possible to reduce duplication
    to a minimum.

    GNO requires modifications to some header files and libraries,
    as well as the additions of others that don't come with ORCA/C.

    The remaining questions in this section of the FAQ explain how
    to set up such a split installation.  This will allow you run
    both GNO and ORCA/Shell (but not concurrently).  The latter is
    necessary when submitting bug reports to the Byte Works.  Mike
    Westerfield (quite rightly) does not generally accept bug reports
    about programs that fail under GNO but run correctly under
    ORCA/Shell.

    CAVEAT:    For the methods explained in this section to work, you must
        be using occ v1.14 when doing compilations with ORCA/C
        v2.0.x.  This is because occ v1.14 will allow older versions
        of ORCA/C to #include the 13/orcacdefs/defaults.h file which
        is automatically included by ORCA/C v2.1.x.

        If you are using ORCA/C v2.0.x but not occ, you will have
        to use the #pragma path directive in all of your sources.
        Failure to do so may result in compilation errors or
        unexplained crashes.

        Any version of occ may be used when compiling with ORCA/C
        v2.1.x.

        These methods are not quite error-free.  See Q#11.11 for
        details.

    The information in this section has been used to set up combinations
    of GNO v2.0.4 and GNO v2.0.6 with ORCA/C v2.0.3 and ORCA/C v2.1.x.

Q#6.2:    How do I set up ORCA/C so that I can use it with GNO?

A#6.2:    === See the CAVEAT in Q#6.1 ===

    There are a few aspects to this, so it has been split into various
    questions in this section of the FAQ.  You should read each of
    those questions when so directed, below.  The following instructions
    assume that you have already installed your ORCA languages; various
    files and directories will be moved from their original locations.

    If you haven't already done so, change the auxtype of
    (original_orca_directory)/shell/Editor to hex DC00 (see Q#14.1).

    Next, create the directory /lang/orca.  This will be the new
    location of your ORCA distribution.  You should move all the
    files and directories from you original ORCA location to /lang/orca.
    You will therefore have directories like /lang/orca/shell,
    /lang/orca/languages, and so forth.

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

    Next, set up your defaults.h file as described in Q#6.5.  As per
    the caveat in Q#6.1, this file will be parsed regardless of which
    version of ORCA/C you're using.

    Now, if you're running GNO v2.0.4, you have to modify some header
    files.  See Q#6.6.

    Next you have to set up your libraries.  This information is specific
    to your GNO-ORCA/C version combination.  See questions Q#6.7, Q#6.8,
    Q#6.9, or Q#6.10 as appropriate.  Note that the library /lib/libgno
    is obsolete in both GNO v2.0.4 and v2.0.6.  If your /lib directory
    resides on an HFS partition, you will need to rename some of your
    libraries (see also Q#11.4).

    If you're using an older version of ORCA/C, you should prototype
    your headers (this is already done for newer versions of ORCA/C).
    Using prototyped headers and #pragma lint -1 can catch a lot of
    bugs, both in user code and in the compiler.  Be very careful that
    you use the correct prototypes.

    For programs in your 17 directory that don't work with GNO (such
    as prizm), I recommend putting something like the following in
    your ~/gshrc:

        alias prizm echo "prizm not available under GNO"

    Remember to put 17 in your PATH environment variable.  See the
    Gsh Reference Manual if you don't know how to do this.

    Finally, if you're using ORCA/C v2.0.x, ensure you have occ v1.14
    installed (other versions -- earlier or later -- will not suffice).
    Also edit both 15/login and ~/gshrc to define the CCOLD environment
    variable.  Do NOT define the CCOLD environment variable if you are
    using ORCA/C v2.1.x; you will slow down your compilations.

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

A#6.3:    === See the CAVEAT in Q#6.1 ===

    In order to minimize file duplication for running GNO and ORCA/Shell
    (but not concurrently -- see Q#2.2), you should set your prefixes up
    as follows.  For GNO, these "volumes" may be defined in /etc/namespace
    (see Q#7.3).  For ORCA/Shell, these pathnames may be relative to
    one or more volumes.

        SHARED (used by both GNO and ORCA/Shell)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    15    /lang/orca/shell        configuration files
    16    /lang/orca/languages        compilers
    -    /lang/orca/include        ORCA headers
    17    /lang/orca/utilities        ORCA-compatible utilities
    -    /lang/orca/utilities/help    ORCA-compatible utility
                        descriptions
    14    /tmp                scratch (work) directory

        GNO (not used by ORCA/Shell)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    13    /lib                main GNO libraries
    -    /usr/lib            secondary GNO libraries
    -    /usr/local/lib            secondary GNO libraries

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


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

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

A#6.4:    === See the CAVEAT in Q#6.1 ===

    While it is possible to have all of your header files in one
    directory hierarchy (this is how it was done in the stock v2.0.4
    distribution), it is STRONGLY advised that you keep separate
    directory hierarchies.  They are:

        /usr/include
        /HFSinclude
        /lang/orca/libraries/orcacdefs
        /lib/orcacdefs
        /usr/local/include

    The /usr/include directory should contain all the header files
    that ship with GNO.  This will include some subdirectories like
    sys, machine, and net.

    In GNO v2.0.6 there are a few files that don't conform to ProDOS
    naming conventions.  These files should be placed in the /HFSinclude
    hierarchy.

    ORCA/C comes with its own set of header files.  Some of these
    are used by GNO while others are ignored (because header files
    of the same names exist in one of the other directory hierarchies).
    All of these header files should be left in the
    /lang/orca/libraries/orcacdefs directory (see Q#6.2).

    /lib/orcacdefs corresponds to 13/orcacdefs under GNO.  It should
    contain only one file, defaults.h.  See Q#6.5.

    /usr/local/include, like everything else in the /usr/local hierarchy,
    is not used by the GNO base install.  This hierarchy is reserved
    for site-specific packages that you decide to add.  In particular,
    /usr/local/include should be used for any header files that you
    decide to add to your system, and which are not part of the
    base installation.

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

A#6.5:    === See the CAVEAT in Q#6.1 ===

    There are two versions of this file, one for GNO and one for
    ORCA/Shell.  For GNO, the /lib/orcacdefs/defaults.h file should
    contain:

        #define __appleiigs__
        #define __GNO__
        #pragma path "/usr/include"
        #pragma path "/HFSinclude"    /* needed for GNO v2.0.6 */
        #pragma path "/lang/orca/libraries/orcacdefs"

    (See Q#11.11 regarding a problem with using the "path" pragma.)

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

        #define __appleiigs__

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

A#6.6:    === See the CAVEAT in Q#6.1 ===

    If you're using GNO v2.0.6, no modifications should be necessary
    provided you've placed all the GNO header files into /usr/include
    and /HFSinclude as appropriate.  This applies to both ORCA/C v2.0.3
    and ORCA/C v2.1.x.

    There are various header files included with the GNO v2.0.1
    distribution.  These should all be copied into the /usr/include
    directory hierarchy as discussed in Q#6.4. (Versions 2.0.2,
    2.0.3, and 2.0.4 were incremental changes, not complete
    distributions, and therefore did not include header files.)

    If you are using the Multiuser package, then you should also
    copy over the <time.h> and <utmp.h> files from that package.

    The files in the following lists are used instead of their ORCA/C
    counterparts, except where noted by "+++"; those so marked need
    to be modified as described.

    Note the last section in this question is a list of suggested
    changes to the GNO v2.0.4 header files.  These changes you should
    make yourself.

    GNO v2.0.4 with ORCA/C v2.0.3
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

        errno.h        This one has many GNO error codes added.
        fcntl.h        Differs in the prototypes of open(2), read(2),
                write(2), and definition of OPEN_MAX.
        signal.h    Completely different for GNO.
        stdio.h        Differs in the prototypes of fread(3) and
                fwrite(3).  The FILE structure uses an
                older name for one of its members, but it
                doesn't matter.  A prototype for fdopen(3)
                and the fileno() macro was added.
    +++    stdlib.h    You should delete this one and copy the
                ORCA/C v2.0.3 stdlib.h from
                /lang/orca/libraries/orcacdefs to
                /usr/include.  See the "common" changes
                below for more information on this file.
        string.h    Many new functions were added in the GNO one.
    +++    types.h        You should delete this one and copy the
                ORCA/C v2.0.3 types.h from
                /lang/orca/libraries/orcacdefs to
                /usr/include.  See the "common" changes
                below for more information on this file.

    GNO v2.0.4 with ORCA/C v2.1.x
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

        errno.h        This one has many GNO error codes added.
        fcntl.h        Differs in the prototypes of open(2), read(2),
                write(2), and definition of OPEN_MAX.
        signal.h    Completely different for GNO.
    +++    stdio.h        You should delete this file, then copy the
                one from your ORCA/C distribution into
                the /usr/include directory.  See the "common"
                changes below for more information on this
                file.  Note that there was a critical change
                to the FILE structure as of ORCA/C v2.1.1b2;
                ensure your header file matches your OrcaLib.
    +++    stdlib.h    You should delete this one and copy the
                ORCA/C v2.1.x stdlib.h from
                /lang/orca/libraries/orcacdefs to
                /usr/include.  See the "common" changes
                below for more information on this file.
    +++    string.h    You should rename this file to something
                else (like "string.old"), then copy the
                one from your ORCA/C distribution into
                the /usr/include directory.  Finally, you
                should copy the prototypes for the following
                functions from the old GNO file into the new
                one copied from the ORCA/C distribution:
                    bcopy        bzero
                    index        rindex
                    strdup        strupr
                    strlwr        strset
                    strnset        strrev
                    strpblnks    strrpblnks
                    strpad        strrpad
                    stricmp        strncmp
    +++    types.h        You should delete this one and copy the
                ORCA/C v2.1.x types.h from
                /lang/orca/libraries/orcacdefs to
                /usr/include.  See the "common" changes
                below for more information on this file.

    GNO v2.0.4 common changes
    ^^^^^^^^^^^^^^^^^^^^^^^^^

    The following is a list of suggested changes to the GNO v2.0.4
    header files.  You have to make these changes yourself; they are
    not part of the distributed header files.

    For any files below that don't appear in /usr/include, you should
    copy the file from /lang/orca/libraries/orcacdefs into /usr/include,
    then edit the copy in /usr/include.  Do not modify files in
    /lang/orca/libraries/orcacdefs.

    dirent.h (possibly sys/dirent.h):
        Ensure that in struct dirent, the d_namelen field
        appears before the d_name field, as described in the
        GNO v2.0.4 release notes.

    gno/gno.h:
        Rename send(2) to procsend(2) and receive(2) to    procreceive(2).

    stdio.h:
        Add the following:

            #define    fileno(f)    ((f)->_file)
            #define    P_tmpdir    "/tmp"
            FILE *    fdopen(int, const char *);
            char *    tempnam(char *, char *);
            char *    mktemp(char *);
            int    mkstemp(char *);
            FILE *    popen(const char *, const char *);
            int    pclose(FILE *);

        Add the following if you're using ORCA/C v2.1.x:

            #define setbuffer(stream,buf,size) ((buf==NULL) ? \
                (void)__setvbuf(stream,NULL,_IONBF,0L) : \
                (void)__setvbuf(stream,buf,_IOFBF,\
                    (size_t)size))
            #define    setlinebuf(stream) (__setvbuf(stream,NULL,\
                _IOLBF,0L))
            int    __fseek(FILE *, long, int);
            int    __setvbuf(FILE *, char *, int, size_t);

    stdlib.h:
        Add the following declarations:

            int    initenv(void);
            void    popenv(void);
            int    pushenv(void);
            int    putenv(const char *);
            int    setenv(const char *, const char *, int);
            void    unsetenv(const char *);

    sys/ports.h:
        Change the prototypes of pdelete(2) and preset(2) to:

            int    pdelete(int, int (*)(void));
            int    preset(int, int (*)(void));

    sys/stat.h:
        Add the following prototype:

            int    umask(int);

        This header file contains the following guard macro:

            #ifndef __BSD_TYPES__
            #include <sys/types.h>
            #endif

        it should be changed to:

            #ifndef __SYS_TYPES__
            #include <sys/types.h>
            #endif

    sys/times.h:
        The last line should be modified so that the text following
        the #endif is in a comment, otherwise it is not legal C
        source code:
            #endif    /* _SYS_TIMES_H_ */

    sys/types.h:
        Change the typedef of sig_t to:
            typedef void (*sig_t)(void);

        The typedef for use_t has an extraneous '_' character.  Of
        course, if you hit this and aren't compiling the kernel
        you're doing something wrong since the _IN_KERNEL macro
        should not normally be defined:
            typedef unsigned char    use_t;

    sys/wait.h:
        Add the following declaration:
            int    wait(union wait *);

    time.h:
        Add the following declarations:

            void        tzset(void);
            #ifndef _SVR4
            struct tz *    timezone(void);
            #endif

    types.h:
        Before the definition of TRUE, add in the following:

            #undef    TRUE
            #undef    true
            #undef    FALSE
            #undef    false

    unistd.h:
        As explained in the lenviron documentation, rename the
        execve() system call to _execve() (if you have installed
        /usr/lib/lenviron as described in Q#6.7 or Q#6.8). Insert
        or uncomment prototypes for execl(), execlp(), execv(),
        execve(), and execvp().  The execve() prototype should be:

            int execve(const char *,char * const *,char * const *);

        Insert the following prototypes.  They are not yet defined
        in any standard, however they are common routines and are
        provided in libc for GNO v2.0.6:

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

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

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

        /lib/lcrypt    (GNO v2.0.1)
        /lib/lregexp    (GNO v2.0.1)
        /lib/lstring    (GNO v2.0.1)
        /lib/ltermcap    (GNO v2.0.1)
        /lib/libc    (GNO v2.0.4)    [rename to "nlibc" for HFS]
        /lib/OrcaLib    (GNO v2.0.1)
        /lib/PasLib    (ORCA/Pascal v2.0.x, required if and only if
                 you use ORCA Pascal)
        /lib/SysFloat    (ORCA/C v2.0.x)
        /lib/SysLib    (ORCA/C v2.0.x)

    The following libraries are recommended.  The sequence here is not
    important as they will be read in the order specified on the occ(1)
    command line:

        /usr/lib/lflex
            This provides a main() routine suitable for a
            flex(1) generated parser.
        /usr/lib/lgnoasm
            Provides asm replacements for some libgno symbols.
            These include "CommandLine", "timezone", "tmpnam".
        /usr/lib/lenviron
            [This library is obsoleted as of GNO v2.0.6 --
            these routines have been incorporated into libc.]

            This has a replacement for getenv/setenv, exec*,
            and other routines that ease the porting of UNIX
            programs.  Note that the prototype and implementation
            of execve(2) changes from that defined in the GNO
            docs.
        /usr/lib/lgetline
            GNU line input editing.
        /usr/lib/lgetopt
            A GNU replacement for the getopt(3) package.
        /usr/lib/lttylock
            Provides locktty(3) and unlocktty(3) routines.
        /usr/lib/lstack
            [This library is obsoleted as of GNO v2.0.6 --
            these routines have been incorporated into libc.]

            Stack checking routines.  These are useful for
            verifying how much stack space your final program
            uses so that it may be reduced to a minimum.  The
            currently available archive contains an object file
            which may be converted to a library file by
            makelib(1).
        /usr/lib/gnulib
            A GNU replacement for the alloca(3) routine and
            the getopt(3) package.  This partially overlaps
            the lgetopt library.

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

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

        /lib/lcrypt    (GNO v2.0.1)
        /lib/lregexp    (GNO v2.0.1)
        /lib/lstring    (GNO v2.0.1)
        /lib/ltermcap    (GNO v2.0.1)
        /lib/libc    (GNO v2.0.4)    [rename to "nlibc" for HFS]
        /lib/OrcaLib    (ORCA/C v2.1.x)
        /lib/PasLib    (ORCA/Pascal v2.1.x, required if and only if
                 you use ORCA Pascal)
        /lib/SysFloat    (ORCA/C v2.1.x)
        /lib/SysLib    (ORCA/C v2.1.x)

    Note the OrcaLib should be the one shipped with ORCA/C v2.1.x.
    You can use it provided that you apply the va_end fix described
    in Q#11.1.

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

    Some people believe the ORCA/C v2.1.x library won't work properly
    with pipes.  This has neither been demonstrated nor disproved.
    If you find hard evidence either way, please contact Devin Reade
    at the address at the top of this FAQ.

    If you need pipes, you can try the libraries that shipped with GNO
    v2.0.1, but you will not get any of the Byte Works bug fixes.  Also,
    it has been reported that the GNO modifications introduced stdio
    bugs that weren't in the original version (no details available).

    Note that you _must_ keep the versions of OrcaLib, SysFloat, and
    SysLib consistent; you cannot use some from OrcaC v2.0.x and others
    from OrcaC v2.1.x.  You may run into problems from unexpected
    behavior to memory trashing.

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

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

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

A#6.10:    You must have the following libraries in the sequence given.  You
    should not add any other libraries to this directory as it will
    slow down linking for all programs.

        /lib/libc    (GNO v2.0.6)   [rename to "nlibc" for HFS]
        /lib/lsaneglue    (GNO v2.0.6)   [renaem to "nlsaneglue" for HFS]
        /lib/OrcaLib    (GNO v2.0.6)
        /lib/PasLib    (ORCA/Pascal v2.1.x, required if and only if
                 you use ORCA Pascal)
        /lib/SysFloat    (GNO v2.0.6)
        /lib/SysLib    (ORCA/C v2.1.x)

    The following libraries are recommended.  The sequence here is not
    important as they will be read in the order specified on the occ(1)
    command line:

        /usr/lib/lflex
            This provides a main() routine suitable for a
            flex(1) generated parser.
        /usr/lib/lgetline
            GNU line input editing.
        /usr/lib/lgetopt
            A GNU replacement for the getopt(3) package.
        /lib/lstring
            Non standard string routines. (*** Obsolete?)
        /lib/ltermcap
            Terminal capabilities library.  Moved from /lib.
        /usr/lib/lttylock
            Provides locktty(3) and unlocktty(3) routines.
        /usr/lib/gnulib
            A GNU replacement for the alloca(3) routine and
            the getopt(3) package.  This partially overlaps
            the lgetopt library.

    The following libraries either are obsolete or have been merged with
    libc and should NOT be used:

        /lib/lcrypt
        /usr/lib/lgnoasm
        /usr/lib/lenviron
        /usr/lib/lregexp
        /usr/lib/lstack

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

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

A#7.1:    GUPP (Grand Unified Patch Program by Nathan Mates) is recommended
    for fixing memory-trashing bugs present in GNO kernel versions
    v2.0.4 and v2.0.6-beta.  GUPP also does other patches that may be
    applicable to programs running under GNO.  GUPP will not touch
    kernels earlier than v2.0.4 even though those bugs probably exist
    in earlier versions of the kernel.

    GUPP is available from the ground and caltech sites, and also
    at ftp://ftp.visi.com/users/nathan/a2software/gupp.shk. See also
    Q#14.4.

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

A#7.2:    Check in the /etc/gettytab file. There's a line near the top that
    contains the login string.  It is preceded by an "im:", which is
    an acronym for "initial message".

Q#7.3:    How do I map /usr, /local, /var, and other partitions to GS/OS
    volume or directory names?

A#7.3:    The kernel provides this functionality through the namespace
    facility, which is configured in /etc/namespace.  See the Kernel
    Reference Manual for details.  See also the Kernel Bugs section
    of question #704 regarding the format of the file.

Q#7.4:    How do I set up cron?

A#7.4:    There are man pages for this that were distributed with the v2.0.4
    GNO update, but they don't quite match the implementation provided
    with the Multi-user 2.0 package.

    To activate cron, you must uncomment its entry in the /etc/inittab
    file.  See the init(8) man page for the format of this file.

    Cron is controlled through the /etc/crontab file.  Unlike its UNIX
    counterparts, the GNO cron does *not* support setting of environment
    variables in the crontab file.  These would be lines of the form:
        SHELL=/bin/sh
        MAILTO=gdr

    Any line which begins with a hash (#) character is considered
    to be a comment and is ignored.

    All other lines in this file are expected to have five space-
    delimited date/time fields, followed by a user name field, followed
    by a command.  The first five fields are:
        minute        (0-59)
        hour        (0-23)
        day of month    (1-31)
        month        (0-11)
        day of week    (0-6)        (appears to be ignored)
    Multiple values may be specified either separated by commas,
    or as a range separated with a hyphen.

    Following the five date/time fields is a username field.
    Although it has to be present, it does not appear to be used
    by the current cron implementation.

    The last field is the command to be executed at the specified
    time.  Unlike UNIX cron implementations, these commands _are_not_
    executed from a subshell, so meta characters and file redirection
    cannot be used.

    You cannot split cron commands into separate lines of the crontab
    file.  Any '%'s in the command are replaced by newlines.  Unlike
    UNIX crons, the text appearing after a '%' character _is_not_
    piped to the input of the command.

    BUG WARNING:    Do not use more than 10 multiple values in each
            of the date-time fields; if there are more than
            10, cron's memory structures are reported to get
            corrupted.

Q#7.5:    Why won't my entry in the inittab file work correctly?

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

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

Networking
----------

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

A#8.1:    Most of the required kernel support is available in GNO v2.0.4,
    but it is not complete and there is nothing to take advantage
    of it.  However, the remaining kernel support has been added
    to the upcoming version.  This, however, does not include the
    TCP stack, which is considered to be a separate product from
    GNO.

    At this time, the kernel has only been modified to recognize
    GS/TCP.

Q#8.2:    Is GS/TCP available?  Where can I get it?

A#8.2:    GS/TCP is not yet available to the general public.  Information
    on it's status and an overview of the project is available from
    the GS/TCP web page:

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

Q#8.3:    Does Marinetti work with GNO?

A#8.3:    Recently, Richard Bennett has released Marinetti, a beta-level
    TCP/IP stack for the IIgs that does not require GNO.

    Experimentation with the Marinetti/GNO combination has been
    sketchy so far.  However, here are some initial observations,
    in no particular order:

    - Running individual programs that rely on Marinetti seem
      to work the same way under GNO as they do without GNO.
      (However, see the following observations.)

    - Processes are unable to block while waiting for input.
      Therefore, they must do a "busy wait".  While this does
      not normally matter on the GS, it is considered to be
      Rude Behavior under GNO since it steals clock cycles that
      could be used by other processes.

    - It would be inadvisable to have Marinetti block a process
      that is waiting on input, since GNO is in a mutex state when
      accessing the ToolBox.  Therefore, if Marinetti were to block
      a process, then all of GNO would be blocked.

    - Development on the Marinetti/GNO combination is still in the
      planning stage.

    - The optimal method for programs running under the GNO/Marinetti
      combination seems to be the the same way that GNO interacts
      with GS/TCP; through the kernel.  If programs limit themselves
      to using the kernel interface (which uses BSD sockets) then
      the kernel could potentially use either GS/TCP or Marinetti,
      whichever is active.  The kernel could worry about blocking
      processes, ensuring an appropriate use of resources.  The
      kernel interfaces (user libraries) could perhaps be written
      to use Marinetti directly in the case where GNO is not running.
      This would allow a GNO-aware program to work either with
      or without GNO.

      Programs that use the Marinetti IPC mechanism directly will
      probably still work under GNO, but can be expected to have
      problems multitasking.

      By the way, the above paragraph is pure rambling and supposition
      by the FAQ maintainer.  The GNO kernel currently knows nothing
      about Marinetti.

    - Richard has expressed a willingness to work with the GNO
      development team to ensure that the two products can coexist.

    For the latest status on Marinetti, see the Marinetti home page:

        http://www.zip.com.au/~kashum/marinetti

    If you have additional information regarding the Marinetti/GNO
    combination, please email the maintainer of this FAQ.

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

A#8.4:    Several utilities have been written and should be made available
    with the release of GS/TCP.  They include:
        ftp, telnet, irc, ping, finger, rcp

Q#8.5:    Is there a WWW browser for GNO and GS/TCP?

A#8.5:    A text oriented browser has been ported by Derek Taubert and
    requires the GS/TCP package. Derek has also done some work on
    a Graphics based WWW browser.  Neither package has as yet been
    released.

    There are no known WWW browsers available yet that are based
    on Marinetti.  This is subject to change, and you should see
    the Marinetti web page for the latest details.  See Q#8.3.

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

A#8.6:    Currently the GNO serial drivers only support the two built-in
    serial ports.  This does not imply that you cannot use a
    serial card in a remote machine (such as a IIe) that is connecting
    to your IIgs running GNO.

Q#8.7:    What should I use for my modem port control panel settings.

A#8.7:    These settings will usually work.  See the Notes, below.

    Device Connected:        Modem
    Line Length:            Unlimited
    Delete first LF after CR:    No
    Add LF after CR:        No
    Echo:                No
    Buffering:            Yes
    Baud:                19200    (1)
    Data/Stop Bits:            8/1    (2)
    Parity:                None    (2)
    DCD Handshake:            Yes
    DSR/DTR Handshake:        Yes
    XON/XOFF Handshake:        No

    Notes:    1. The baud should be set to whatever is appropriate
           to your system.  Unless you are using a modem or
           serial line that is slower than 14400 bps, this will
           almost always be "19200".

        2. Set data/stop bits and parity as appropriate for your
           site.  8N1 is the most common setting.

Q#8.8:    How can I initialize my serial ports at GNO "boot" time?

A#8.8:    The easiest way to do this is through initd(8).  Add the following
    lines to your /etc/initab file:

        # this will initialize the modem port on startup
        md:b:once:i:/usr/sbin/runover .ttya /bin/stty 38400

    You should of course change "38400" to whatever speed is appropriate
    for your site.

Q#8.9:    How do I hook up a terminal to the IIgs' printer/modem port?

A#8.9:    This answer describes hooking up a terminal to the printer port.
    Hooking one up to the modem port will be similar except that
    .ttya should be used instead of .ttyb.

    On the hardware side, you will need a mini DIN 8 to DB25 printer
    cable.  This should be connected from the IIgs' printer port
    to the port on the terminal that would normally be hooked to
    a modem.

    Next, you have to run a getty(8) over the printer port.  Add
    this line to your /etc/inittab file:

        pp:23478:rest::/usr/sbin/getty 8bit.xxxx .ttyb

    where xxxx is the speed. Remove '78' from '23478' if you want
    to run it only in multiuser mode.  See also Q#8.8 regarding
    initialization of the serial port.

    In order for the change to take effect, you either have to quit
    and restart GNO, or type '/bin/init q' (without the quotes).

Q#8.10:    How do I enable GNO to activate dialup access.

A#8.10:    This question is not about using your IIgs to dial _out_ to another
    machine.  It means that you're allowing _other_ machines to
    dial _in_ to your IIgs running GNO.

    The first thing you should consider is whether you _really_ want
    to do this.  GNO doesn't have any user/group file permissions,
    so as soon as someone is logged into your IIgs, they will have
    read/write access to _all_ of your files.  Because of this, the
    only layer of protection you have is dialup/getty and the security
    of the password file (including how well _all_ passwords are
    chosen).  There has been no known investigation into the security
    of the GNO dialup/getty.

    That said, the way to enable dialup access is through the dialup(8)
    program.  It is invoked as
        dialup tty [speed [init_string]]

    Normally this would be done at GNO "boot" time through the initd(8)
    facility.  Add the following to your /etc/inittab file:

        # This enables the modem for remote dialup (_into_ the IIgs)
        # when in multiuser mode (run level 2 or 3).
        t2:23:rest::/usr/sbin/dialup .ttya 38400 ate1qs0=1s11=50\\r

    Ensure you substitute the "38400" with a speed appropriate to your
    hardware.  Note that "14400" is not considered to be a valid speed.
    If you are using a 14400 kb/s modem, you should use "19200" as the
    speed setting.

    See also Q#8.8 regarding initialization of the serial port.

    You should also replace the initialization string with one suitable
    for your modem (consult your modem manual).  The one shown above
    contains the following HAYES commands:
        at    (start command)
        e1    local echo on
        s0=1    auto answer on
        s11=50    set touch tone duration to 50ms
        \\r    escaped carriage return (ends command)

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

A#8.11:    This termcap entry is suitable for use with any UNIX machine
    (that uses termcap rather than terminfo) being accessed from
    ProTERM:

#
# ProTerm Special
#
pt|pse|proterm-special|Proterm Special Emulation:\
        :ae=^N:am:al=^V:bl=^T^A^E@:bs:bw:cl=^L:cm=^^%r%+ %+ :co#80:ce=^Y:\
        :cd=^W:dc=^D:dl=^Z:do=^J:eo:eA=^P:ho=^X:ic=^F:il=^N:i3=^L:\
        :is=^L^N:kd=^J:kl=^H:kr=^U:ku=^K:le=^H:li#24:ll=^^ 8:mb=^O:md=^O:\
        :me=^N:mh=^O:mr=^O:nd=^U:nl=\n+^A:pt:rs=^N:se=^N:so=^O:ta=^I:\
        :ue=^N:up=^K:us=^O:xn:ns:as=^P:bc=^H:r1=^N:r2=^N:r3=^N:\
        :ms:mi:sf=^J:sr=^K:as=^P:i1=^N:i3=^N:NP:dn=^J:

Q#8.12:    Is there a mail/news package available for GNO?

A#8.12:    There is a rudimentary one called MuGS by Brian Tao.  It requires
    a shell account (presumably on a UNIX box) for part of the
    software.  The base MuGS package handles news articles that
    are spooled on the UNIX machine's local disk.  There is an NNTP
    (Net News Transfer Protocol) patch by Devin Reade that allows
    MuGS to work with an NNTP server.  MuGS is available as described
    in its describe(1) entry (see Q#4.4).

    Because of a lack of TCP/IP there is no software for GNO v2.0.4
    that allows a IIgs to connect to the 'net via NNTP or SMTP.

    Jeff Markham provided the following suggestion:

        I've been using the gmail system, and I've come up with
        something that seems to work ok with gmail and sendmail.

        Create the following two files.  The first is /bin/send:
        [gdr:  The second and third lines should be a single line
               without the escaped newline.  It has been printed
               here as is for clarity:

            #!/bin/gsh
            /bin/foreach x /var/spool/sendmail/out/* \
                < /bin/send.dat > .null

        The second is /bin/send.dat:

            tail +2 $x | /usr/sbin/sendmail
            rm $x

        That combo works well enough to send the mail on it's way.
        The way I use to get around gmail's need for all config
        files to be in the same folder as the exe is by using the
        following /bin/mail file:

            #! /bin/gsh
            rm /bin/signature /bin/gmail.cf > .null
            cp $HOME/gmail/* /bin
            gmail
            mv /bin/gmail.o $HOME/gmail
            send

        It copies all the set-up files, calls gmail, returns the
        only needed file to the users account and sends any mail.

        Comments on my process are welcome.

Q#8.13:    How do I use copycat?

A#8.13:    There seem to be two versions of copycat available.  One version
    takes two tty names on the command line, the other takes only one.
    It is unclear which version numbers correspond to which behavior;
    the version that takes only one argument lists itself as v1.5.0,
    however the documentation for v1.5.0 definitely lists a requirement
    for two arguments.

    That said, there are a few ways to use copycat.  This answer will
    assume that you wish to communicate from the GNO console with a
    terminal hooked to your modem port.  If you are using the TMTerm
    NDA, then substitute ".ttyco" in this example with ".ttyq0".

    The first thing you must do to use copycat is ensure that your
    serial port is properly initialized.  Use the stty(1) command
    like this:
        stty 38400 < .ttya
    You should substitute "38400" with whatever speed was used for
    setting up your link.  ".ttya" is the modem port device.  (For
    the printer port, use ".ttyb".)

    Now all you have to do is issue the following command.  The second
    argument may not be required or accepted in your version of copycat:
        copycat .ttya .ttyco

    You will see the prompt:
        Break character is '^\'

    You are now connected with whatever is hooked up to your modem
    port.  To get the copycat command prompt, type the control
    character (CONTROL-\).

    See the copycat documentation and man page for more details.
    It explains how to do interesting things like allowing a terminal
    on your printer port to use your modem without interfering with
    the GNO console.

Q#8.14:    How do I use rz/sz?

A#8.14:    rz/sz are usually used in conjunction with copycat.  The important
    part to remember is that while copycat is used to control the
    remote end of the file transfer, it must not be running _during_
    the transfer.

    The following example assumes you are sending a file from the
    remote machine to the IIgs.  Steps taken to go the other direction
    will be similar.

    The first step is to initialize your modem port and start copycat
    as explained in Q#8.13.  In this example, "unix% " is used as the
    prompt on the remote machine, and "gno% " as the prompt on the
    IIgs.  Extraneous blank lines have been deleted.

        gno% stty 38400 < .ttya
        gno% copycat .ttya
            Break character is '^\'
        unix%

    Next, start the file transfer on the UNIX end.  There are problems
    with some versions of UNIX sz if the "-l1024" flag is not given
    (others don't recognize this flag).  See the rz/sz README.GNO
    file and the UNIX sz man page for details.  Remember to use the
    "-a" flag if you want a text file transfer:

        unix% sz -a testfile.bsq
        **B00000000000 14

    Now type the copycat break character, CONTROL-\, quit from copycat,
    and start rz on the GNO side:

        copycat> quit
        gno% rz < .ttya > .ttya &

    When the file transfer is finished, don't forget to log off the
    remote machine.  To get there, you have to restart copycat:

        gno% copycat .ttya
            Break character is '^\'
        unix% logout
        ^\
        copycat> quit
        gno%

Q#8.15:    Why do I get errors when trying to access the (modem/serial) port?

A#8.15:    This is usually caused by serial port configuration problems.
    Common symptoms may be:
        % copycat .ttyco .ttya
        Error opening tty .ttya, aborting.
    or
        % /usr/sbin/getty 8bit.38400 .ttya
        getty: .ttya: I/O error

    The first thing to check is that the following GNO serial port
    drivers exist:
        /dev/modem
        /dev/printer

    Next, ensure the following two lines are in your /etc/tty.config
    file, and that they are uncommented:
        modem        2    .ttya
        printer        1    .ttyb

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

    Remember to reboot your system if you've made any changes in
    or to comply with the above requirements.

Porting UNIX Programs to the GNO Environment
--------------------------------------------

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

A#9.1:    Strictly speaking, all you need is a C compiler (since UNIX source
    tends to be in C).  However, there are a few programs that
    can be considered "essentials" for doing ports.  All of these
    are mentioned in the section on "Compiling":

        ORCA/C, occ, dmake

Q#9.2:    What are the common problems encountered when porting UNIX source
    to GNO?

A#9.2:    The first thing to watch for is known compiler and library bugs.
    Soenke Behrens maintains the current ORCA/C bug report list.
    You should keep the contents of this list in mind when examining
    the target source code.  The ORCA/C bug report list may be found at

        http://www.arrowweb.com/sbehrens/obugs.htm

    This list has been considerably shorted since the release of
    ORCA/C v2.1.0.  If you have an earlier version of ORCA/C, you
    should seriously consider an upgrade.

    The following items should be watched for, in no particular order.
    Since UNIX source is usually in C, that language is assumed for
    the rest of this section, where relevant:

    sizeof(int)
        The size of the type "int" is implementation-defined.
        While most modern C compilers use 32 bits, ORCA/C still
        uses 16 bits since this is the "natural" integer size of
        the 65816.  This also results in more effective code
        generation.

        While the size of an int shouldn't make a difference to
        any well-written code, there is some available source code
        that assumes that ints are 32 bits.  You should watch for
        this in any code that does bit manipulations.  You should
        also watch for code that freely converts between integers
        and pointers.  GNU (Free Software Foundation) software
        is often bad for this.

    recursion
        When possible, recursion should be avoided when programming
        on the Apple IIgs.  This is because recursion invariably
        causes stack growth and the stack can only exist in bank
        zero.  This means that the maximum space available for
        the stack is 64k.  In practise, it is much smaller.

        This problem is exacerbated under GNO where all processes
        must share the available stack space (each process has its
        own stack, though).

        Any program that uses recursion can be rewritten to use
        iteration instead.  You should try to do this when possible.
        If you _do_ use recursion, don't allocate a huge stack;
        this will keep other programs from executing.  Also, you
        should leave in stack checking and stack repair (if
        programming with ORCA/C) to ensure that your recursion
        does not crash the machine if it goes too far.

    reference to absolute file descriptors
        True UNIX machines invariably use the file descriptors 0, 1,
        and 2 for standard input, standard output, and standard error,
        respectively.  Under GNO, the file descriptors used are 1,
        2, and 3.

        This causes a problem when source code is written to use
        these descriptors directly.  You should search your code
        for references to these descriptors, typically in calls
        to open, close, read, write, dup, dup2, and fcntl.

        Instead of replacing these digits with other digits though,
        you should use the macros STDIN_FILENO, STDOUT_FILENO, and
        STDERR_FILENO defined in <unistd.h>.  This will ensure
        that your source is kept portable.

    fork
        Because of problems that are discussed in the fork(2) man
        page and the kernel reference, the fork system call under
        GNO is different than other versions of UNIX.  Besides
        having a different prototype, the parent and child process
        share the same address space.  In this respect, GNO is less
        a multitasking environment than it is a multithreading
        environment.

        Search for calls to fork; you will have to rewrite these
        sections of code.  See also the man page for fork2(2); it
        may be more suited to your purposes.

        Also note than when compiling routines that make a call
        to fork, you should turn off ORCA/C's stack repair code.
        This means that you should be using an optimization level
        of at least 8.

    read/write of newline character
        Most UNIX systems use LF (ASCII 0x0a) as the line delimiter.
        Both Apple II and Macintosh computers use CR (ASCII 0x0d)
        as the line delimiter.  The C newline character is '\n';
        ASCII 0x0a.

        While the stdio routines (fprintf(3), fread(3), etc) usually
        make this difference unnoticable by doing CR-->LF translation
        on input and LF-->CR translation on output, no such
        translation is done on files accessed through read(2) and
        write(2).  Specifically, the GNO open(2) does not recognize
        the ORCA/C O_BINARY bit in it's second argument.

        Therefore, if the program you are porting makes calls to
        read(2) and write(2), watch for the '\n' character in your
        code.  You may have to change this to '\r'.  Don't do it
        blindly, because many programs will use both stdio and
        operations on the bare file descriptors.

        One suggestion is to modify your programs low-level I/O
        routines to modify the I/O buffer prior to calling write(2)
        and after calling read(2).

    variadic functions
        Some (poorly written) UNIX programs have variadic functions
        where the number of provided arguments don't match the
        number of arguments expected by the called routine.  Even
        though this is in some cases legal ANSI/C, versions of
        ORCA/C prior to v2.1 would puke magnificently when encountering
        such code.  Some of these cases are now handled in a more
        robust fashion by ORCA/C v2.1 and later.

        If you are _defining_ (as opposed to using) variadic functions,
        you must turn off stack repair code around the definitions
        of those functions.

        The ORCA/C manual (and especially the release notes for
        v2.1) have important and detailed information on this topic.
        See the sections on the optimize and debug #pragmas.

    open, chmod, fchmod, creat, st_mode, stat, fstat, lstat
        In general, the bits in the mode parameter of these
        functions do not directly map between UNIX and GNO
        implementations.  If your application is using macros
        such as S_IREAD or S_IWRITE for the mode parameters, and
        those macros are taken from the system header file
        <sys/stat.h>, then you probably don't need to modify your
        application.

        If, on the other hand, your application is using its own
        constants for the mode parameter, you should convert it
        to use the standard macros.  Failure to do so may result
        in files with strange GS/OS flags set, or file tests failing
        in your program.

    /dev
        One of the UNIX philosophies is that "everything is a file".
        The /dev directory on UNIX systems contain device special
        files.  Accessing these files is the way to access the
        relevant hardware.

        For GNO programs, you should not access devices in the
        /dev directory.  For example, opening "/dev/console" for
        writing will not have the expected effect.  Instead you
        should open the corresponding GS/OS device, ".ttyco".

        The portable (and suggested) method of handling these cases
        is not to change the value of the string (in this example)
        from "/dev/console" to ".ttyco".  Instead, use the macros
        defined in the file <paths.h>.  For this example, one would
        use the macro _PATH_CONSOLE.

    standard path assumptions
        This one is closely tied in with the "/dev" description
        above.  The <paths.h> file contains macros for various
        standard paths.  The macros, instead of the actual paths,
        should be used to maximize portability.

    signal handlers
        When a signal handler is called, the data bank register
        may not have an expected value.  If your program references
        global scalars, it may crash.  To avoid this, all functions
        used as signal handlers should have their definition
        preceded by
            #pragma databank 1
        and followed by
            #pragma databank 0

    validity of pathnames
        Most programs make assumptions about what constitutes
        a valid file name.  For most modern Unices, a valid
        file name follows the POSIX portable filename character
        set:  The characters a-z and A-Z, the digits 0-9, and
        '.', '_', and '-'.  The '-' is not used as the first
        character of a file name, and '/' is the directory
        separator character.  The maximum filename length is
        at least 14 characters, and the maximum pathname length
        is at least 255 characters.

        Now this is different from what is available under GNO.
        The ProDOS FST provides only a subset of the above.  The
        HFS FST provides a superset, but HFS is too slow, too
        buggy, and too unmaintainable for many users.

        The problem is also compounded by the fact that under
        GS/OS, the ':' is a directory separator.  '/' may be used
        but it is mapped internally to ':'.

        Unfortunately, there is no general consensus on how to
        handle pathnames under GNO.  Here are some opinions, all
        of which refer to user code; the GNO kernel treats pathnames
        the same way that GS/OS does:

        - the ':' character should be mapped to '/'.  This prohibits
          the use of '/' in _file_ names.  It also provides the
          highest degree of "UNIX compatibility"; or

        - the '/' character should be mapped to ':'.  This is more
          in line with GS/OS, but can require extensive rewrites
          of ported UNIX programs; or

        - use dynamic directory delimiters.  The ':' character is
          always considered to be a directory separator.  The '/'
          character is considered to be a directory separator unless
          it was preceded at some point by a ':', in which case it
          is part of the file name.  Having a '/' appear before ':'
          in a pathname is illegal.  This is the closest to GS/OS,
          but also has some problems  with POSIX compliance.  For
          example, the PATH environment variable is _supposed_ to
          be a list of pathnames delimited by the ':' character.
          This implies that one cannot use the ':' as a directory
          delimiter when defining PATH, and that directories in
          PATH must not contain '/' as a regular character.

        Regardless of which method you use to do filename, pathname,
        and directory separator mapping, you should verify that
        the pathname is legal for your target filesystem.  GS/OS
        provides a mechanism to do this through the JudgeName
        system call.

        Also watch out for references to the root partition.  For
        other UNIXs, this is the pathname "/", which is a not legal
        directory under GS/OS (and therefore GNO).  Hopefully the
        context of your program will give you an idea how to handle
        such a directory reference in a sensible manner.

    unlink
        Many UNIX programs unlink (delete) files while they still
        have them open.  Under true UNIX systems, this means that
        the file will be deleted as soon as it is closed.  This is
        is not done under GNO, and attempting to unlink an open file
        will fail, and the file will remain on the file system after
        it is closed.  If your program relies on this behavior, you
        will have to find a work-around.  One partial solution is
        to register a clean-up function via atexit(3) that deletes
        your files for you.  [This method is not suitable for
        daemons or other long-running programs.]

Q#9.3:    Are there any other recommendations for porting programs?

A#9.3:    There probably are as many opinions as there are programmers.
    However, here is a list that seems to work well.  Using C as
    the source language is assumed:

    - Use the occ(1) "-w" flag (#pragma lint -1) whenever possible.
      You will have to modify your code if it doesn't use prototypes,
      but this is more likely to catch errors and incorrect assumptions.
      If you really need to be compatible with K&R compilers, you
      can use the following paradigm in your code:

        #include <sys/cdefs.h>
        int main __P((int argc, char **argv));

        int main
        #ifdef __STDC__
        (int argc, char **argv)
        #else
        (argc, argv)
        #endif
            int argc;
            char **argv;
        {
            ...

      You may have to prototype some of your system header files.
      This should not be necessary with the ORCA/C v2.1 header files
      (they're already prototyped), but is likely necessary with
      earlier versions and some of the GNO v2.0.4 (and earlier) system
      header files.  See also Q#6.2 and Q#6.6.

    - Whenever possible, compile with the occ(1) "-G25" during
      development.  This will ensure that, in the event of stack
      trashing and similar problems, that you get a meaningful
      traceback and that your machine (usually) doesn't crash.

      If you are using the Splat! debugger, you should use "-g" instead
      of "-G25".  See also the notes on fork(2) in question Q#9.2.

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

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

Compiling
---------

Q#10.1:    Which language should I use?

A#10.1:    Since GNO is not language-specific, it doesn't really matter.

    From a practical stand point though, either assembly or C tend
    to be the languages of choice.  Both have their strengths and
    weaknesses.  Assembly can be more efficient but in general requires
    more time to program and more attention to detail.  Much of the
    available UNIX source code is in C. Using C can result in a quicker
    development cycle and more portable code, but it often results in
    a slower program.

    A big part of the decision is dependent on which language you
    already know.  If you are comfortable in one, stick with it
    until you need to try something else.  If you know neither,
    then the decision becomes religious -- ie: there is no correct
    answer, and the response you get will depend on whom you ask.

    Some people have also successfully used Pascal for GNO
    programming, although it is not as suited to GNO as is C or
    assembly.

    If you program in C, the only realistic choice for a compiler
    is Byte Works' ORCA/C.  As of v2.1.0, it is relatively bug free
    and close to ANSI-compliant.

    If you program in assembler, Byte Works' ORCA/M is recommended.
    Merlin-8/16 (by Roger Wagner) is also reputed to be suitable
    (although not as common).

Q#10.2:    Should I purchase the ORCA Subroutine Library Source?

A#10.2:    The sources are not required, but they are recommended.  Some
    reasons are:
        - they allow you to see how a function is implemented
        - they allow you to investigate possible library bugs
        - they are good examples of assembly programming
        - they are inexpensive

Q#10.3:    What is occ?

A#10.3:    occ is a front end to ORCA/C written by Soenke Behrens.  It makes
    ORCA/C's invocation more "UNIX-ish" and is the recommended
    interface between dmake(1) and ORCA/C.

Q#10.4:    What is dmake?

A#10.4:    dmake is a variation of the UNIX "make" facility.  It is used
    on large software projects for defining when and how files should
    be updated (typically compiled or linked), based on dependency
    lists.  It's behavior is controlled through the use of a
    "makefile" (sometimes "makefile.mk"), which is a text file
    defining dependency graphs, rules, and actions.

    After definition of the makefile, a project can often be built
    (perhaps tested and installed as well) just by typing "dmake",
    assuming there are no compilation or other errors.  Only the
    work that is required will be done.

    For more details, see the dmake(1) man page.

Q#10.5:    What macros should I be using for conditional compilation?

A#10.5:    There are four general areas where certain "standard" macros
    are used ("standard" is quoted because only those explicitly
    annotated correspond to ISO/ANSI or other standards).  Where
    the macros aren't predefined by current compilers, they should
    be defined in source, header, or makefiles when necessary:

    - Architecture:
        These macros tend to be lower case with double leading-
        or trailing-underscores, such as "__sun4__" or "__parisc__".

        No IIgs compilers currently predefine an architecture,
        but "__appleiigs__" is recommended for Apple IIgs
        specific code.

    - Operating System:
        These macros tend to be upper case and may or may not
        use underscores.  Examples are "_AIX" and "SunOS".

        No IIgs compilers currently predefine an os macro,
        but "__GNO__" is recommended for GNO-specific code.

    - Compiler:
        These macros tend to be upper case and may or may not
        use underscores.  Examples are "__LCC__" and "__GNUC__".

        ORCA/C predefines "__ORCAC__".  APW/C predefines "APW".

    - Language and other standards:
        The "__STDC__" macro may be used for determining ISO/ANSI C
        compliance.  It is the responsibility of the compiler to
        define (or not define) this macro appropriately.

        If "_POSIX_SOURCE" source is defined, the source may
        be written with the assumption that all symbols defined
        by POSIX Standard 1003.1 are available in the environment.
        This symbol is expected to be defined by the user as
        necessary.  GNO isn't yet POSIX compliant, but it's getting
        there.

        If "_BSD_SOURCE" is defined, all symbols are expected to
        be 4.3BSD compliant.  This implies "_POSIX_SOURCE".  Again,
        GNO isn't there yet but it's progressing.

        "KERNEL" is defined when building the GNO kernel.  You will
        see this macro in the GNO header files, but you should not
        define it.

        "__cplusplus" is predefined by C++ compilers, of which there
        are none for the IIgs.  It is the responsibility of the
        compiler to define (or not define) this macro appropriately.
        Explanation of this macro was given since you occasionally
        see it in GNO header files ...

    Other macros are defined either by the compiler or in header files,
    but these are the main ones for user code conditional compilation.
    See the relevant documentation (compiler manual, ISO/ANSI or POSIX
    standards, GS/OS reference manual) for more details.

Q#10.6:    When I'm using the new header files (post-v2.0.4), sometimes ORCA/C
    can't find my header files.  Why?

A#10.6:    There are a few potential causes for this problem, some of which
    are not completely understood.  You should try the following
    steps:

    1.  Ensure that the correct "#pragma path" values are in your
        13/orcacdefs/defaults.h file (see Q#6.5).

    2.  Ensure that all of your header files are of type SRC and
        auxiliary type CC.  This includes headers in the directories
        specified via "#pragma path" in 13/orcacdefs/defaults.h
        (see Q#6.5), any directories specified by the occ(1) "-I"
        flag, and your current directory.

    3.  Remove any *.sym files you have and try compiling with the
        occ "-i" flag.  This has been reported to eliminate the
        problem; presumbably there is an out-of-date cache being
        used in the precompiled header file.

        If you are using dmake, you can add "-i" to your default
        CFLAGS environment variable in /usr/local/lib/startup.mk.

        If you use neither dmake nor occ, you can add "#pragma ignore"
        to your 13/orcacdefs/defaults.h file.

    4.  If your problem is intermittent, try calling the purge(1)
        command when the problem occurs.

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

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

A#11.1:    You should only be seeing this if you are trying to use the
    ORCA/C v2.1.x libraries with GNO v2.0.4.  (See Q#6.1 and Q#6.8).

    The GNO v2.0.4 libraries were compiled with a version of ORCA/C
    that still used a function version of va_end(3).  ORCA/C now
    correctly defines va_end(3) as a macro.

    If you attempt to use a variadic function from the GNO v2.0.4
    libraries (such as open(2)), then you will get an unresolved
    va_end reference.  To solve this problem, download and install
    the archive "vaendPatch.shk", available from ground or caltech.

Q#11.2:    Why do I keep getting "getc" and "putc" as unresolved symbols
    when linking?

A#11.2:    This is an indication that the files 13/OrcaLib, 13/SysFloat,
    and 13/SysLib are not properly matched.  You cannot mix these
    files from different versions of ORCA/C.  The OrcaLib shipped
    with GNO can only be used with particular versions of the other
    two libraries.  You should (re)read the section in this FAQ on
    "Installing GNO with ORCA".

Q#11.3:    How can I tell what order my libraries are in?

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

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

A#11.4:    This isn't really a GNO question, but it's included here because
    of its relevance to Q#11.3 and the section on "Installing GNO with
    ORCA".

    For ProDOS Partitions:
        There are various ways to do this.  One of the easiest is to
        use ProSEL or another utility which sorts directory entries
        (such as the ORCA/Shell compress command -- *don't* confuse
        this with the GNO compress(1) command).

        If you do not have a utility that does this, you can do it
        manually by moving all the files into another (scratch)
        directory, then moving them back one at a time in the order
        in which you wish them to appear.

    For HFS Partitions:
        The files in a given directory on HFS partitions are always
        sorted by name, case insensitive.  You can change the sequence
        in the directory only be changing the names of the files
        involved.

        Specific to GNO installations, if your /lib directory resides
        on an HFS volume, you should rename /lib/libc to /lib/nlibc.

Q#11.5:    How can I tell what is in library XXXX?

A#11.5:    The only way to tell for sure what is in a library is to
    look at the symbol table.  The most common way to do this
    is to get a listing by using Byte Works' makelib(1) utility,
    which comes with their various language packages (see the -D
    and -F flags).

    There is also a program available, listlib(1), which is a
    front end to makelib.  It provides the same information as
    makelib, but in an alternate format more suited to cross
    referencing symbols to the files containing them.

    Of course, knowing what symbols are _in_ a library doesn't help
    unless one knows _what_ the symbols are for.  Every library should
    have at least one header (*.h) file.  This tells the compiler
    the type, size, and other important information for each symbol.

    Header files, however, are intended for the compiler.  A good
    library should come with documentation, preferably manual pages
    (see Q#3.4, Q#3.5, and Q#3.6).

    If documentation isn't available and the symbols appear to be
    common UNIX symbols, then try reading a manual page from any
    available UNIX box.  It might not be right, but it may give you
    a start.  Next try posting a question to comp.sys.apple2.gno.
    Perhaps you will be able to contact the author (not likely if there
    wasn't any documentation).  When all else fails, there's always
    disassembly of the object files ...

Q#11.6:    Why isn't the common function XXXX in the libraries?

A#11.6:    The GNO libraries are still undergoing active development.  If you
    find that a standard or common routine is missing, then contact
    Devin Reade <[e-mail]> who is currently the primary
    maintainer of the GNO libc.

    If the function is not yet in libc you are requested to contribute
    an implementation and a man page, preferably in nroff(1) source
    (see Q#3.5).  Distributing the work results in faster updates.

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

A#11.7:    Just because a function is declared, that doesn't necessarily mean
    that it's been implemented.  However, it is useful to keep those
    declarations in the system header files.  Not only does it minimize
    namespace conflicts with user code (application programmers are
    less likely to use function names that conflict with system header
    files), but it ensures that the interface is defined for anyone
    who wishes to contribute an implementation.  Declaring those
    functions early also minimizes updates to the system header files
    as the function implementations are added.

    See also Q#11.6.

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

A#11.8:    Here's a checklist:

    - Any symbols which should not be available to the user should
      have their private flag set.  In C, this corresponds to using
      the "static" storage class specifier whenever possible.

    - Ensure your library is compatible with ORCA/C's large memory
      model.

    - Write documentation, preferably one or more manual pages, for
      any exported symbols.  If your library uses configuration files,
      write manual pages for those too (they belong in chapter 5).

    - Specify in the manual pages any dependency on non-standard
      libraries.  Specify dependencies for all header files, whether
      standard or not.

    - Consider including your source code with your library.  This
      allows your contribution to survive even if your hard drive
      crashes, your backups are destroyed, or you leave the GNO
      community.

Q#11.9:    How do I get the file descriptor from a stdio FILE pointer?

A#11.9:    Use the fileno() macro.

    This is defined in <stdio.h> as of GNO v2.0.6.  For earlier
    versions you will have to add it in yourself.  The proper
    macro definition for the ORCA/C headers is:

        #define fileno(p) ((p)->_file)

Q#11.10:    My (ported) source requires <sys/file.h>.  Why isn't it there?

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

Q#11.11:    Why, when I '#include <types.h>' (or some other file), does the
    compiler take it out of my current directory instead of out of
    the system header directories?

A#11.11:    This is an unfortunate side-effect of using the ORCA/C "path"
    pragma to avoid duplication of system header files between your
    GNO and ORCA installations.  (See Q#5.1, Q#6.1, Q#6.4, and
    Q#6.5.)

    The reason for the problem is that when the file is included
    with the angle bracket syntax (vice double quotes), ORCA/C
    will still search the current directory before those specified
    by the "path" pragma.

    At this time, the only known work-around is to avoid, in your
    own sources, using file names used by the system header files.

Q#11.12:    When using the December 1997 libraries (or later version), why are
    my programs larger than they used to be?

A#11.12:    There are a few reasons for this.

    The first one is that when the libraries (which are mostly written
    in C) are compiled, aggressive optimizations are not currently used.
    This is because certain optimizations in ORCA/C are known to be
    broken.  This, combined with the fact that we are missing a lot
    of automated test suites for the GNO (non-ORCA/C) additions to the
    libraries, indicated that it would be best to ship the libraries
    without much in the way of optimizations.

    The second reason is probably more significant.  When Jawaid provided
    a libc and ORCALib for GNO v2.0.4, he made significant changes to
    the stdio portion of ORCALib so that it would work with pipes and
    sockets.  Unfortunately, for whatever reason, the two versions of
    ORCALib (the original version from Byte Works, and the modified
    version from Procyon) were never merged.  Therefore, when ORCALib
    was updated for ORCA/C v2.1.x, the GNO-specific changes were
    effectively lost.

    When Devin took over maintenance of the GNO libraries in the spring
    of 1997, he was (in order to get a stdio package that worked with
    pipes) faced with the choice of either reimplementing Jawaid's
    changes to stdio, or to use another implementation of stdio that
    was written with pipes in mind.

    The tradeoff is one of development time versus code size (and probably
    speed).  The ORCA stdio implementation is in assembly, so it is
    small and fast.  On the other hand, GNO v2.0.6 had been in the
    "it's not ready yet" stage for quite a while.  The choice was made
    to use the 4.4BSD stdio implementation.  This is the primary reason
    why programs which use stdio are now larger than they were.

    If your program does not use stdio, but is still significantly
    larger, then it may be due to dependancies in libc; there are
    some routines which currently depend on stdio but which need not.
    These dependancies will be removed as time is available to do so.

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

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

A#12.1:    No.

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

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

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

Q#13.1:    What debuggers are available for GNO?

A#13.1:    There are no GNO-specific debuggers, however there are at least two
    popular ones that are compatible with GNO.

    If you are programming in C, it is highly recommended that you
    purchase "Splat!", written by Michael Hackett of Some Assembly
    Required.  This is also available from Procyon.  See also Q#13.2.

    If you are programming in assembly, it is recommended that you
    install GSBug.  This comes bundled with ORCA/M and is also available
    for download from the Apple Inc dts ftp site.  GSBug has many
    add-on packages used to increase its functionality.  Two of these
    are Niftylist and Nexus.

Q#13.2:    Why is the Splat! debugger crashing when my code calls fork(2)?

A#13.2:    Splat was not originally designed for GNO.  When GNO does a fork(2)
    or fork2(2) call, some very non-standard things are happening in
    the IIgs execution environment.  Splat cannot currently handle
    these operations.

    A request has been submitted to the author of Splat! for an upgrade
    to handle this behavior but he has not yet had time to do it; he
    is also busy working on other IIgs projects.

Q#13.3:    Part way through my debugging session, Splat! no longer shows my
    source file.  Why?

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

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

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

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

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

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

Q#14.1:    Some programs I run have two cursors and sometimes characters I
        type don't get sent to the program. When I quit the program, the
        characters show up on the command line! What's wrong?

A#14.1:    You need to set the auxiliary file type of the program in question
    to $DC00.  Use the chtyp command:

            chtyp -a \$DC00 ProgramName

    Note the '\' character; it must be there to escape the '$' character
    from the shell, otherwise the $DC00 would be treated as a shell
    variable.

    Also note that this fix will not work if the program's file type
    is S16 and the file resides on an HFS volume.  (An EXE file on
    an HFS volume should be fine.)

Q#14.2:    Whenever I try to launch the Finder from GNO, I am told that the
        Finder needs more memory. I know there is enough memory available.
        What's the deal?

A#14.2:    This was a bug in the GNO 1.0 kernel. Unfortunately, there is no
    workaround.  The only option is to upgrade to a current version
    of GNO.

Q#14.3:    My program is crashing when calling open(2).  Why?

A#14.3:    It may be due to a prototype/library mismatch.  The GNO implementation
    of open(2) is a variadic function.  The third "mode" parameter must
    be provided if and only if the second "oflag" parameter has the
    O_CREAT flag set.

    If calls to open result in a crash or stack error, you may have
    either the wrong definition of open in <fcntl.h>, or you are not
    getting open from 13/libc.  See also Q#9.2, Q#11.2, Q#11.3, and Q#6.6.

Q#14.4:    What are the known bugs?

A#14.4:    First off, this answer only refers to GNO-specific bugs.  You
    should also consult the ORCA/C bug list (see Q#9.2).

    As of mid-March 1998, there is an online bug tracking system
    for GNO.  You can get to it off of the GNO Documentation Page.
    Its direct URL is:

        http://www.gno.org/~gno/bugs.html

    If you know of specific problems with GNO that are not listed
    in the database, please enter them.  The web interface is the
    preferred method of submitting reports, but if that is not
    feasible you can also send bug reports to the following address:

        [e-mail]

    If you do not have a web browser, you can view current reports
    by obtaining them through anonymous ftp at the following URL:

        ftp://ftp.gno.org/pub/gno-bugs

    You shouldn't archive these reports since they are continually
    being updated; view them and throw them away.

    *** The anon ftp directory has not yet been set up.
--
Tomorrow I will seven eagles see, a great comet will appear, and voices will
speak from whirlwinds foretelling monstrous and fearful things -- This
Universe never did make sense; I suspect that it was built on government
contract.                        - Robert Heinlein