home *** CD-ROM | disk | FTP | other *** search
/ ftp.pasteur.org/FAQ/ / ftp-pasteur-org-FAQ.zip / FAQ / apple2 / GNO-faq
Internet Message Format  |  1999-11-07  |  106KB
  1. 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
  2. From: gdr@eddore.myrias.com (Devin Reade)
  3. Newsgroups: comp.sys.apple2.gno,comp.answers,news.answers
  4. Subject: comp.sys.apple2.gno FAQ (v1.18)
  5. Supersedes: <apple2-gno-faq-1-939252001@eddore.myrias.com>
  6. Followup-To: comp.sys.apple2.gno
  7. Organization: Myrias Computer Technologies Corp
  8. Lines: 2693
  9. Sender: gdr@eddore.gno.org
  10. Approved: news-answers-request@MIT.EDU
  11. Distribution: world
  12. Expires: 12/11/99 17:20:02
  13. Message-ID: <apple2-gno-faq-1-941934002@eddore.myrias.com>
  14. Reply-To: gdr@eddore.myrias.com (Devin Reade)
  15. Summary: Contains information on the UNIX-like OS for the Apple IIgs.
  16. Keywords: FAQ, GNO, Apple-II, UNIX, ORCA
  17. X-Content-Currency: This FAQ changes regularly.  When a saved or printed copy
  18.    is over 6 months old, please obtain a new one.  Instructions in the
  19.    preamble indicate where to find them via NetNews, FTP, and the WWW.
  20. Date: Sun, 07 Nov 1999 00:20:12 GMT
  21. NNTP-Posting-Host: 24.64.124.43
  22. X-Complaints-To: abuse@home.net
  23. X-Trace: news1.rdc1.ab.home.com 941934012 24.64.124.43 (Sat, 06 Nov 1999 16:20:12 PST)
  24. NNTP-Posting-Date: Sat, 06 Nov 1999 16:20:12 PST
  25. Xref: senator-bedfellow.mit.edu comp.sys.apple2.gno:7160 comp.answers:38387 news.answers:170492
  26.  
  27. Archive-name: apple2/GNO-faq
  28. Last-modified: 06 May 1998 05:12:23
  29. Version: 1.18
  30. URL: http://www.gno.org/~gno/FAQ.html
  31. Posting-Frequency: monthly
  32.  
  33. This is the Frequently Asked Questions (FAQ) posting of the
  34. comp.sys.apple2.gno newsgroup.  This document can be freely copied so
  35. long as
  36.     1. it is not sold (although it may be included in commercial
  37.        distributions of Apple II archives such as the Golden Orchard
  38.        CD series); and
  39.     2. any sections reposted elsewhere from it are credited back to
  40.        this FAQ with the FAQ's copyright info and official FTP and
  41.        WWW location left in place.
  42. Explicit permission is granted to carry this FAQ on electronic forums
  43. dealing with Apple II computers such as BBSs and service providers
  44. such as Genie and Delphi.
  45.  
  46. This FAQ is available via ftp and on the WWW at
  47.  
  48.     ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/faq/CURRENT
  49.     http://www.gno.org/~gno/FAQ.html
  50.  
  51. A summary of recent updates may be found at
  52.  
  53.     ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/faq/LOG
  54.     http://www.gno.org/~gno/FAQ-log.html
  55.  
  56. This FAQ may also be found in archives of comp.answers and news.answers,
  57. such as those at rtfm.mit.edu.
  58.  
  59. The question numbers in this FAQ are auto-generated.  Therefore, when
  60. referring to questions in this FAQ, please either give the version number
  61. of the FAQ or (preferably) give some context that identifies to which
  62. question you refer.
  63.  
  64. The FAQ was originally maintained by C. Matthew Curtin,
  65. <cmcurtin@interhack.net>.  It contains contributions (intentional
  66. or otherwise) from many users of GNO.
  67.  
  68. The FAQ is currently maintained by Devin Reade, <gdr@eddore.myrias.com>.
  69. Questions, comments, suggestions, and submissions to this FAQ are welcome
  70. and should be emailed to Devin Reade or posted to comp.sys.apple2.gno.
  71.  
  72. This FAQ is undergoing active development. Consequently, some questions
  73. may have annotations starting with three asterisks ("***").  These are 
  74. questions that are in the process of having their answers written or
  75. modified.
  76.  
  77. In the event that this FAQ appears to be abandoned, someone else is 
  78. welcome to take it over as the official maintainer or to use this FAQ
  79. as the basis for a new one, provided that you credit the previous
  80. maintainers.  The criteria for abandonment are:
  81.     1.  The FAQ has not been updated nor posted to comp.sys.apple2.gno
  82.         for a period of at least six months;
  83.     2.  Attempts to contact the current maintainer (Devin Reade)
  84.         have failed.  You must try for a period not less than 30
  85.         days, and you must try contacting the maintainer through
  86.         email, and postings to comp.sys.apple2.gno and the Delphi
  87.         (delphi.com) Apple II Programmers' Forum.
  88. In addition, please ensure that there is a general consensus on
  89. comp.sys.apple2.gno that the FAQ is indeed abandoned before you attempt
  90. to take it over.  I have not included this as a criterion since a
  91. "general consensus" is difficult to quantify in any practical sense.
  92.  
  93. Table of Contents
  94. =================
  95.  
  96.     General
  97.     ^^^^^^^
  98.     Q#1.1:    What is GNO?
  99.     Q#1.2:    What is the status of GNO?
  100.     Q#1.3:    What is the current version of GNO?
  101.     Q#1.4:    What are GNO's minimum system requirements?
  102.     Q#1.5:    Where can I get GNO?
  103.     Q#1.6:    What support is available for GNO?
  104.     Q#1.7:    Where can I get the files/archives recommended in this FAQ?
  105.     Q#1.8:    Why is this FAQ written in such a drab format?
  106.  
  107.     Compatibility
  108.     ^^^^^^^^^^^^^
  109.     Q#2.1:    With what standard version of UNIX is GNO compatible?
  110.     Q#2.2:    Can I run ORCA/Shell from GNO (or vice-versa)?
  111.     Q#2.3:    Is GNO compatible with the SecondSight VGA card?
  112.     Q#2.4:    Are desktop applications compatible with GNO?
  113.     Q#2.5:    Can I use prizm (the ORCA desktop environment) with GNO?
  114.     Q#2.6:    What new features are expected to be in the next version
  115.         (2.0.6)?
  116.  
  117.     Documentation
  118.     ^^^^^^^^^^^^^
  119.     Q#3.1:    What documentation comes with GNO?
  120.     Q#3.2:    What additional documentation is recommended for GNO?
  121.     Q#3.3:    What are all the numbers in parenthesis following program
  122.         names?
  123.     Q#3.4:    I've just finished writing a new program (or library or
  124.         whatever). What documentation should I include?
  125.     Q#3.5:    I'm writing a manual page. What format should I use?
  126.     Q#3.6:    What should be in a manual page?
  127.     Q#3.7:    Man(3) is too slow when formatting pages. Can I speed it up?
  128.     Q#3.8:    What are the standard manual page chapters?
  129.  
  130.     Programs
  131.     ^^^^^^^^
  132.     Q#4.1:    What other programs come with GNO?
  133.     Q#4.2:    Are there any ftp sites for GNO utilities?
  134.     Q#4.3:    I cannot ftp to caltech or ground. How can I get the GNO
  135.         utilities?
  136.     Q#4.4:    What is the most recent version of program XXXXXX?
  137.     Q#4.5:    Which editor should I use?
  138.     Q#4.6:    What command line flags does gsh(1) accept?
  139.  
  140.     System Installation
  141.     ^^^^^^^^^^^^^^^^^^^
  142.     Q#5.1:    For what are the various directories used?
  143.     Q#5.2:    What should be in my gshrc file?
  144.     Q#5.3:    Where should I install custom additions to GNO?
  145.  
  146.     Installing GNO with ORCA
  147.     ^^^^^^^^^^^^^^^^^^^^^^^^
  148.     Q#6.1:    Do I need separate installations of ORCA/C for use with GNO
  149.         and ORCA/Shell?
  150.     Q#6.2:    How do I set up ORCA/C so that I can use it with GNO?
  151.     Q#6.3:    GNO with ORCA: What should I use for compilation directories
  152.         and prefixes?
  153.     Q#6.4:    GNO with ORCA: Where should my C header files go?
  154.     Q#6.5:    GNO with ORCA: What goes in the 13/orcacdefs/defaults.h
  155.         file?
  156.     Q#6.6:    GNO with ORCA: What header file modifications are necessary?
  157.     Q#6.7:    GNO with ORCA: What libraries are used for the combination
  158.         of GNO v2.0.4 and ORCA/C v2.0.x?
  159.     Q#6.8:    GNO with ORCA: What libraries are used for the combination
  160.         of GNO v2.0.4 and ORCA/C v2.1.x?
  161.     Q#6.9:    GNO with ORCA: What libraries are used for the combination
  162.         of GNO v2.0.6 and ORCA/C v2.0.x?
  163.     Q#6.10:    GNO with ORCA: What libraries are used for the combination
  164.         of GNO v2.0.6 and ORCA/C v2.1.x?
  165.  
  166.     System Configuration
  167.     ^^^^^^^^^^^^^^^^^^^^
  168.     Q#7.1:    What patches should I have applied for GNO?
  169.     Q#7.2:    How do I change the information that's printed before the
  170.         login prompt?
  171.     Q#7.3:    How do I map /usr, /local, /var, and other partitions to
  172.         GS/OS volume or directory names?
  173.     Q#7.4:    How do I set up cron?
  174.     Q#7.5:    Why won't my entry in the inittab file work correctly?
  175.  
  176.     Networking
  177.     ^^^^^^^^^^
  178.     Q#8.1:    Does GNO provide TCP/IP and/or SLIP support?
  179.     Q#8.2:    Is GS/TCP available? Where can I get it?
  180.     Q#8.3:    Does Marinetti work with GNO?
  181.     Q#8.4:    What TCP/IP network utilities are available?
  182.     Q#8.5:    Is there a WWW browser for GNO and GS/TCP?
  183.     Q#8.6:    Can I use a serial card or internal modem with GNO?
  184.     Q#8.7:    What should I use for my modem port control panel settings.
  185.     Q#8.8:    How can I initialize my serial ports at GNO "boot" time?
  186.     Q#8.9:    How do I hook up a terminal to the IIgs' printer/modem port?
  187.     Q#8.10:    How do I enable GNO to activate dialup access.
  188.     Q#8.11:    What do I use for a ProTERM termcap entry?
  189.     Q#8.12:    Is there a mail/news package available for GNO?
  190.     Q#8.13:    How do I use copycat?
  191.     Q#8.14:    How do I use rz/sz?
  192.     Q#8.15:    Why do I get errors when trying to access the (modem/serial)
  193.         port?
  194.  
  195.     Porting UNIX Programs to the GNO Environment
  196.     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  197.     Q#9.1:    What programs/utilities should I have to port UNIX source
  198.         code to GNO?
  199.     Q#9.2:    What are the common problems encountered when porting UNIX
  200.         source to GNO?
  201.     Q#9.3:    Are there any other recommendations for porting programs?
  202.  
  203.     Compiling
  204.     ^^^^^^^^^
  205.     Q#10.1:    Which language should I use?
  206.     Q#10.2:    Should I purchase the ORCA Subroutine Library Source?
  207.     Q#10.3:    What is occ?
  208.     Q#10.4:    What is dmake?
  209.     Q#10.5:    What macros should I be using for conditional compilation?
  210.     Q#10.6:    When I'm using the new header files (post-v2.0.4), sometimes
  211.         ORCA/C can't find my header files. Why?
  212.  
  213.     Libraries and Header Files
  214.     ^^^^^^^^^^^^^^^^^^^^^^^^^^
  215.     Q#11.1:    I keep getting "va_end" as an unresolved symbol when
  216.         linking. Why?
  217.     Q#11.2:    Why do I keep getting "getc" and "putc" as unresolved
  218.         symbols when linking?
  219.     Q#11.3:    How can I tell what order my libraries are in?
  220.     Q#11.4:    How can I sort my libraries (or other files)?
  221.     Q#11.5:    How can I tell what is in library XXXX?
  222.     Q#11.6:    Why isn't the common function XXXX in the libraries?
  223.     Q#11.7:    Function XXXX is declared in the GNO header files, but it's
  224.         not in the libraries. Why?
  225.     Q#11.8:    I want to release my library to the GNO community. Is there
  226.         anything in particular that I should do?
  227.     Q#11.9:    How do I get the file descriptor from a stdio FILE pointer?
  228.     Q#11.10:  My (ported) source requires <sys/file.h>. Why isn't it
  229.         there?
  230.     Q#11.11:  Why, when I '#include <types.h>' (or some other file), does
  231.         the compiler take it out of my current directory instead of
  232.         out of the system header directories?
  233.     Q#11.12:  When using the December 1997 libraries (or later version),
  234.         why are my programs larger than they used to be?
  235.  
  236.     Kernel Internals
  237.     ^^^^^^^^^^^^^^^^
  238.     Q#12.1:    Can task-switching occur during an interrupt?
  239.     Q#12.2:    Can I tell GNO/ME to not task switch during a short (like a
  240.         couple of ASM instructions) sequence?
  241.  
  242.     Debugging (During Program Development)
  243.     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  244.     Q#13.1:    What debuggers are available for GNO?
  245.     Q#13.2:    Why is the Splat! debugger crashing when my code calls
  246.         fork(2)?
  247.     Q#13.3:    Part way through my debugging session, Splat! no longer
  248.         shows my source file. Why?
  249.  
  250.     General Problems
  251.     ^^^^^^^^^^^^^^^^
  252.     Q#14.1:    Some programs I run have two cursors and sometimes
  253.         characters I type don't get sent to the program. When I quit
  254.         the program, the characters show up on the command line!
  255.         What's wrong?
  256.     Q#14.2:    Whenever I try to launch the Finder from GNO, I am told that
  257.         the Finder needs more memory. I know there is enough memory
  258.         available. What's the deal?
  259.     Q#14.3:    My program is crashing when calling open(2). Why?
  260.     Q#14.4:    What are the known bugs?
  261.  
  262. General
  263. -------
  264.  
  265. Q#1.1:    What is GNO?
  266.  
  267. A#1.1:    GNO is a UNIX-like multitasking environment for the Apple IIGS.
  268.     GNO provides:
  269.  
  270.     1. Pre-emptive multitasking.
  271.     2. A shell that takes full advantage of the multitasking provided
  272.        (i.e., job control), and 'regular expressions', and a simple
  273.        programming language.
  274.     3. A powerful programming environment. All the calls needed to
  275.        control processes, support Inter-Process Communication (IPC),
  276.        and other tools necessary to support multitasking are
  277.        available to the programmer.
  278.     4. The first completely consistent method for accessing serial
  279.        and console I/O on the Apple II.  This makes such things as
  280.        attaching terminals to your GS, multiline BBSes, remote
  281.        dial-ups, UUCP or SLIP that doesn't take over your computer,
  282.        as well as countless other applications a possibility.
  283.  
  284. Q#1.2:    What is the status of GNO?
  285.  
  286. A#1.2:    GNO was developed by Procyon Enterprises (Jawaid Bazyar, prop.).
  287.     Until August 1997, GNO was a commercial product.  In August 1997,
  288.     Jawaid changed GNO's status to that of freeware.  Procyon still
  289.     retains the copyright on the kernel, gsh, and other components
  290.     which were written by or for Procyon.
  291.  
  292.     GNO IS NOT PUBLIC DOMAIN.
  293.  
  294. Q#1.3:    What is the current version of GNO?
  295.  
  296. A#1.3:    The currently released version is v2.0.4.  The version currently
  297.     under development is v2.0.6.  v2.0.5 never had a general release,
  298.     and is not available.
  299.  
  300.     For those programmers using ORCA/C v2.1.x, there was a update made
  301.     available (for both GNO v2.0.4 and GNO v2.0.6 users) on 22 Dec 97.
  302.     It consists of updated headers, libraries, and manual pages.  It
  303.     is available at the following site:
  304.  
  305.         ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base206
  306.  
  307. Q#1.4:    What are GNO's minimum system requirements?
  308.  
  309. A#1.4:    The GNO documentation specifies that the minimum requirement
  310.     is an Apple IIGS with 1.25 MB of memory and a 3.5" disk drive.
  311.     Realistically (especially with all the third-party add-ons),
  312.     a hard drive (or other large mass storage device) should be
  313.     considered a necessity.  An accelerator and additional memory
  314.     is recommended.
  315.  
  316.     There is not an official "minimum disk space" requirement
  317.     as yet.  When this information becomes available, it will
  318.     be added to this FAQ.
  319.  
  320. Q#1.5:    Where can I get GNO?
  321.  
  322. A#1.5:    The base GNO distribution may be obtained via anonymous ftp
  323.     from the following sites.  See also Q#1.7:
  324.  
  325.         ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base204
  326.         ftp://ftp.hypermall.com/pub/gno
  327.  
  328.     The documentation for GNO v2.0.4 is now available via ftp and
  329.     http at the following sites.  MS-Word versions are also available
  330.     via ftp:
  331.  
  332.         http://www.gno.org/~gno
  333.         ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc
  334.         ftp://ftp.hypermall.com/pub/gno/docs
  335.  
  336.     For those who aren't able to make decent printed copies of the
  337.     documentation on their own, Procyon still offers the printed
  338.     documentation for sale.  (Do *NOT* ask Devin Reade for the
  339.     printed documentation.  He does not work for Procyon and does
  340.     not sell it.)  At last check, this is the Kernel Reference Manual,
  341.     the GSH Reference Manual, selected manual pages, and the release
  342.     and installation notes.  This contents list is unofficial and
  343.     subject to correction by Procyon.
  344.  
  345.     Procyon Enterprises Inc maintains a web page at:
  346.  
  347.         http://www.hypermall.com/companies/procyon
  348.  
  349.     or you can contact them by snail-mail at:
  350.  
  351.         Procyon, Inc.
  352.         P.O. Box 620334
  353.         Littleton, CO 80162-0334
  354.         303/933-4649
  355.  
  356. Q#1.6:    What support is available for GNO?
  357.  
  358. A#1.6:    For the most part, the only support available is that given
  359.     by GNO developers in the Apple II community.  In other words,
  360.     what you get is what you get.  Often a polite question posted
  361.     to comp.sys.apple2.gno will result in a helpful response.
  362.  
  363.     Procyon still offers limited support for people who purchased
  364.     GNO prior to August 1997.  No support is available from Procyon
  365.     for those who obtained GNO after it changed to freeware status.
  366.  
  367.     There is a group of programmers (known as the gno-devel list)
  368.     working toward getting v2.0.6 out the door.  Information regarding
  369.     this work will be posted to comp.sys.apple2.gno as it becomes
  370.     available.  Have patience; we all have day jobs and this is
  371.     a hobby.
  372.  
  373. Q#1.7:    Where can I get the files/archives recommended in this FAQ?
  374.  
  375. A#1.7:    The "core" files of the GNO distribution (such as the GNO
  376.     kernel and gsh(1)) are available through anonymous ftp as
  377.     described in Q#1.5.
  378.  
  379.     Non-commercial files, unless otherwise specified, should be
  380.     available from major Apple ftp sites.  There is often a GNO-
  381.     specific directory, but compatible programs, patches, etc,
  382.     may appear anywhere under the Apple II hierarchy.  The GNO
  383.     distribution also contains many files in this category; 
  384.     ensure you have newest versions by checking the ftp sites.
  385.  
  386.     The three main Apple II sites are
  387.         ftp://apple2.caltech.edu/Zocalo/pub/apple2
  388.         ftp://ground.isca.uiowa.edu/apple2
  389.         ftp://ftp.gno.org/pub/apple2
  390.     The latter (also known as trenco.gno.org) is the master site for
  391.     GNO development, as of August 1997.  GNO-specific files can be
  392.     found in the /pub/apple2/gs.specific/gno directory on ftp.gno.org.
  393.  
  394.     Other sites are listed in the comp.sys.apple2 FAQ, which is
  395.     available from the above two sites and
  396.         http://www.visi.com/~nathan/a2/faq/csa2.html
  397.  
  398. Q#1.8:    Why is this FAQ written in such a drab format?
  399.  
  400. A#1.8:    Because it was considered critical that there is a easily
  401.     readable text-only version available.  Combined with the fact
  402.     that the maintainer didn't want to spend a lot of time with
  403.     source translators, this placed a restriction on the type
  404.     of formatting available.
  405.  
  406. Compatibility
  407. -------------
  408.  
  409. Q#2.1:    With what standard version of UNIX is GNO compatible?
  410.  
  411. A#2.1:    GNO contains components that originate with a variety of 
  412.     flavors of UNIX.  These include 4.3BSD, XINU, and SYSV.
  413.     It is mostly BSD.  As of GNO v2.0.6, GNO has become closer
  414.     to 4.4BSD.  Work is in progress to make it as compliant as
  415.     possible to POSIX 1003.1 and POSIX 1003.2.
  416.  
  417. Q#2.2:    Can I run ORCA/Shell from GNO (or vice-versa)?
  418.  
  419. A#2.2:    No.  GNO with a shell (such as gsh) is intended to be a replacement
  420.     for ORCA/Shell.  Similarly, one cannot run GNO from ORCA/Shell.
  421.     However, you can still use the various ORCA languages and (the 
  422.     majority of) utilities from GNO.  See the sections on "Programs"
  423.     and "Compiling", below.
  424.  
  425. Q#2.3:    Is GNO compatible with the SecondSight VGA card?
  426.  
  427. A#2.3:    Yes. GNO is completely compatible with the SecondSight card.
  428.     However, GNO's console driver currently does not support the
  429.     SecondSight card's VGA specific text modes.  A SecondSight aware
  430.     console driver is planned as a future enhancement.
  431.  
  432. Q#2.4:    Are desktop applications compatible with GNO?
  433.  
  434. A#2.4:    In most cases, yes. However, GNO doesn't currently allow more than
  435.     one desktop program to run concurrently.  It does allow you to
  436.     run multiple text applications with or without a desktop application,
  437.     to the limits of your available memory.
  438.  
  439.     There is a program (also available from Procyon), called Switch-It!,
  440.     that allows one two switch between running desktop programs.
  441.     It is not multitasking (in that only the currently displayed
  442.     desktop program is actually running), nor does it _require_
  443.     GNO.  It is, however, complementary to and compatible with GNO.
  444.     Other (text based) processes running in the background continue to
  445.     do so when Switch-It! is active.
  446.  
  447. Q#2.5:    Can I use prizm (the ORCA desktop environment) with GNO?
  448.  
  449. A#2.5:    In a nutshell, no.  The exact reasons are not generally known,
  450.     but the author (Mike Westerfield) does not ever expect to have
  451.     a compatible version available.
  452.  
  453. Q#2.6:    What new features are expected to be in the next version (2.0.6)?
  454.  
  455. A#2.6:    This list is unofficial and subject to change.  With that in mind:
  456.  
  457.     - Complete kernel support for TCP/IP.
  458.     - Lots of little bug fixes that should improve stability.
  459.     - An updated and expanded libc.
  460.     - An OrcaLib compatible with the ORCA/C v2.1 OrcaLib.
  461.     - Updates to various shell programs.
  462.  
  463. Documentation
  464. -------------
  465.  
  466. Q#3.1:    What documentation comes with GNO?
  467.  
  468. A#3.1:    GNO/ME Overview
  469.     Kernel Reference Manual
  470.     Shell (gsh) User's Manual
  471.     Manual Pages (some printed, all online)
  472.  
  473.     Online versions of these documents are also available.  See Q#1.5.
  474.  
  475. Q#3.2:    What additional documentation is recommended for GNO?
  476.  
  477. A#3.2:    The GNO Overview has quite a complete reading list for users and
  478.     programmers, and it is too long to go into detail here.  However,
  479.     in general, the references are broken down into the following
  480.     categories:
  481.         - UNIX reference books.
  482.         - C reference books.
  483.         - Editor reference books.
  484.         - Apple IIgs Programming References
  485.  
  486.     The following list, should also be considered "must have" for
  487.     any serious programming:
  488.  
  489.         - The ORCA/C and/or ORCA/M manuals, as appropriate.
  490.         - Toolbox volumes 1, 2, 3
  491.         - Programmers' Reference for System 6.0/6.0.1
  492.         - GS/OS Reference
  493.         - Firmware Reference
  494.         - Apple Technical Notes
  495.         - Apple File Type Notes
  496.         - A manual on 65816 assembly programming, if you are
  497.           using assembly.  One very good manual is:
  498.             Lichty, Ron and Eyes, David.  _Programming_the_IIgs_
  499.             _in_Assembly_Language_, Brady, 1989.
  500.             ISBN 0-13-729559-6
  501.           You will likely have to get it second hand, as it is no
  502.           longer in print.
  503.  
  504.     The following books are recommended:
  505.  
  506.         - Hardware Reference
  507.         - Apple Numerics Manual
  508.         - Device Driver Reference
  509.         - IEEE Std 1003.1-1988 (or later) -- The POSIX standard
  510.           for computer environments.
  511.         - ANSI/ISO 9899 Standard (defines ANSI/C).
  512.           This is an expensive document, but you get a cheap copy
  513.           by purchasing Schildt, Herbert _The_Annotated_ANSI_
  514.           _C_Standard_, McGraw-Hill, ISBN 0-07-881952-0.  The book
  515.           is set up so that the standard is printed on the "left"
  516.           pages and the annotations are on the "right" pages.
  517.           MAKE SURE YOU USE ONLY THE LEFT PAGES; the annotations
  518.           have just enough errors in them to be dangerous.  Some
  519.           of the "left" pages (from the Standard) are also missing.
  520.  
  521. Q#3.3:    What are all the numbers in parenthesis following program names?
  522.  
  523. A#3.3:    When you see something like "ls(1)" in the documentation, it
  524.     refers to something called "ls" which is documented in Chapter 1
  525.     of the manual pages.  Similarly, "select(2)" is refering to 
  526.     something called "select" which is documented in Chapter 2.  To
  527.     find out what the various chapters are for, type in the command
  528.         man 4 intro
  529.     substituting "4" for whichever chapter you wish to learn about.
  530.  
  531. Q#3.4:    I've just finished writing a new program (or library or whatever).
  532.     What documentation should I include?
  533.  
  534. A#3.4:    Including the following documentation components will not only
  535.     help anyone who is maintaining a GNO site, but they will also
  536.     make your contribution look more professional.  Remember, if
  537.     someone can't tell what your program is supposed to do, they
  538.     are less likely to try it out.
  539.  
  540.     You should have:
  541.  
  542.     - A manual page (see also Q#3.5).  Unless your program requires
  543.       a large reference manual ( > 5-10 pages of written text), the
  544.       manual page should be the primary document.
  545.  
  546.       Ensure the man page is assigned to the correct section.  One
  547.       common mistake is to mix up Section 1 (User Commands) with
  548.       Section 8 (System Administration).
  549.       
  550.     - A describe(1) database entry.  Try to use the ".desc" suffix
  551.       on the file name.  (For example, if you wrote the "foo" program,
  552.       you should have a text file "foo.desc" containing the database
  553.       entry.)  If you have WWW access, please update the online
  554.       describe database maintained by Soenke Behrens -- see Q#4.4.
  555.  
  556.       The describe entry is very suitable as a brief README file
  557.       when uploading your program to ftp sites, or when posting to
  558.       comp.binaries.apple2.
  559.  
  560.       Describe entries should only be written for programs, not 
  561.       libraries or individual routines.
  562.  
  563.     - An rVersion resource fork.  If you don't want to write a rez
  564.       source file, then use setvers(1).
  565.  
  566.       There is a new format out which includes rVersion as a subset.
  567.       It is called rProgramInfo (or rProgInfo), and was formalized
  568.       by Eric Shepherd.  Information on this is available at the
  569.       usual ftp sites in the archive rProgInfo.shk.  See also the
  570.       templates file listed later in this answer.
  571.  
  572.     - "Standard" help and version flags.  If possible, invoking your
  573.       program with the "-V" (capital vee) flag should print the
  574.       version number and exit.  Invoking it with the "-h" flag should
  575.       print a usage (help) message and exit.  Use of the "-?" flag
  576.       is discouraged because it is a meta-character in many shells.
  577.  
  578.       It may not be practical to support these two flags, such as
  579.       if you are porting a program that already uses them for other
  580.       purposes, or if you are writing a daemon.
  581.  
  582.     To make things easier, templates for manual pages, rVersion
  583.     source files, and describe database entries are available at
  584.     the usual sites.  Look for an archive with a name similar
  585.     to
  586.         templates[version_number].shk
  587.  
  588. Q#3.5:    I'm writing a manual page.  What format should I use?
  589.  
  590. A#3.5:    While man can handle both manually-edited preformatted pages and
  591.     pages that are aroff source (created by AppleWorks-GS or a
  592.     compatible editor), the recommended format is to use nroff source
  593.     with tmac "an" extensions.
  594.  
  595.     The reason for this is that only nroff source can be reformatted
  596.     "on the fly" to suit different terminal characteristics.  See also
  597.     Q#3.7.
  598.  
  599. Q#3.6:    What should be in a manual page?
  600.  
  601. A#3.6:    Whatever is necessary.  However, there are some standard sections
  602.     for manual pages, based on which section (chapter) the manual
  603.     page is in.  Templates with the suggested manual page formats
  604.     are available in the file
  605.         templates[version_number].shk
  606.     at the usual ftp sites.
  607.  
  608.     For programs in particular (typically Chapters 1, 6, and 8), here
  609.     are some sections that should be in the man page.  The order of
  610.     the first three are mandatory due to how some automated tools
  611.     work.  The sequence on the remainder are suggested:
  612.         NAME        - name and one line description
  613.         SYNOPSIS    - list of options and arguments
  614.         DESCRIPTION    - a detailed description
  615.         OPTIONS        - explanation of the flags
  616.         ENVIRONMENT    - relevant environment variables and their
  617.                   semantics, if appropriate
  618.         FILES        - related files, if appropriate
  619.         BUGS        - known bugs, if appropriate
  620.         AUTHOR        - your name and contact info, typically
  621.                   an email address.  Include your smail
  622.                   address at your own risk.
  623.         LEGALITIES    - Commercial, freeware, shareware, public
  624.                   domain, copyleft, ... ?
  625.         ATTRIBUTIONS    - Give credit when due.  For example, if
  626.                   your binary was linked with the ORCA
  627.                   libraries, you should be including the
  628.                   Run-Time Licence from Appendix C of the
  629.                   ORCA/C manual.
  630.         SEE ALSO    - related manual pages or other documents
  631.  
  632. Q#3.7:    Man(3) is too slow when formatting pages.  Can I speed it up?
  633.  
  634. A#3.7:    Actually, it's not man(3), but nroff(3) which is slow.  Nroff
  635.     is in desperate need of an update, not only for speed but for
  636.     functionality.
  637.  
  638.     In the interim, however, you can get a faster response from man
  639.     at the cost of using more disk space by preformatting your man
  640.     pages.  See catman(8).
  641.  
  642. Q#3.8:    What are the standard manual page chapters?
  643.  
  644. A#3.8:    Chapter 1:    Commands and Applications
  645.     Chapter 2:    System Calls
  646.     Chapter 3:    Library Routines
  647.     Chapter 4:    Devices
  648.     Chapter 5:    File Formats
  649.     Chapter 6:    Games
  650.     Chapter 7:    Miscellaneous
  651.     Chapter 8:    System Administration
  652.  
  653.     For GNO, there should be no need to use Chapter n [New Commands],
  654.     or Chapter l (ell) [Local Commands], unless (in the latter case)
  655.     the manual page is for something that is not to be released to
  656.     the GNO community.
  657.  
  658.     Chapter 3F is reserved for Fortran Routines, of which there 
  659.     are none at this time (due to the lack of a publicly available
  660.     Fortran compiler).
  661.  
  662. Programs
  663. --------
  664.  
  665. Q#4.1:    What other programs come with GNO?
  666.  
  667. A#4.1:    Lots of free utilities that bring some of the power of UNIX systems
  668.     to the IIGS.  In addition to getting the utility executable files,
  669.     you get the source for many of these.  These programs have been 
  670.     provided by various authors.
  671.  
  672. Q#4.2:    Are there any ftp sites for GNO utilities?
  673.  
  674. A#4.2:    Yes.  Many Apple II ftp sites have GNO-specific directories, although
  675.     GNO stuff can also be found in other directories on these sites.
  676.  
  677.     The three primary general-purpose sites are:
  678.         ftp://apple2.caltech.edu/Zocalo/pub/apple2/shellprogs
  679.         ftp://ground.isca.uiowa.edu/apple2/apple16/gno
  680.         ftp://ftp.gno.org/pub/apple2
  681.  
  682.     Trenco (trenco.gno.org or ftp.gno.org) is the master site for GNO
  683.     development as of August 1997.  See Q#1.7.
  684.  
  685.     See the comp.sys.apple2 FAQ for other Apple II ftp sites.
  686.  
  687. Q#4.3:    I cannot ftp to caltech or ground.  How can I get the GNO utilities?
  688.  
  689. A#4.3:    Perhaps you could use the FTP-by-mail service. Send mail to
  690.     ftpmail@decwrl.dec.com with the subject line of "help" and no body
  691.     for information.
  692.  
  693.     Another alternative is to use the WWW to access those sites.
  694.     WWW access information is available in the comp.sys.apple2 FAQ
  695.     (see Q#1.7).
  696.  
  697. Q#4.4:    What is the most recent version of program XXXXXX?
  698.  
  699. A#4.4:    The best way to find out what programs are available for GNO,
  700.     including version numbers, authors, and other information is
  701.     to use the describe(1) database.  The program, database, and
  702.     maintenance utilities are available at the usual ftp sites.
  703.  
  704.     Soenke Behrens <sbehrens@bigfoot.com> also maintains an online
  705.     describe database.  This tends to be the most up-to-date version,
  706.     and is available at
  707.  
  708.         http://www.arrowweb.com/sbehrens/describe.htm
  709.  
  710. Q#4.5:    Which editor should I use?
  711.  
  712. A#4.5:    Whichever one you want.  Many editors work under GNO.  Some
  713.     of the more popular ones are emacs (MicroEMACS), vi (Stevie),
  714.     ORCA/Editor, Edit-16, and Rose.
  715.  
  716.     Many of these editors cannot be suspended from the shell.  Some
  717.     have the "eating keystrokes" problem (see Q#14.1).
  718.  
  719. Q#4.6:    What command line flags does gsh(1) accept?
  720.  
  721. A#4.6:    There are two.  The first is "-c arg", which is supposed to allow
  722.     one to specify a script on the command line.  This seems to be
  723.     broken, though.
  724.  
  725.     The second one is "-f", which tells gsh not to parse its gshrc
  726.     file, nor do other initialization tasks.  Think of it as "fast
  727.     startup".  Unfortunately, empirical tests seem to indicate that
  728.     gsh is no faster with this flag than without.
  729.  
  730. System Installation
  731. -------------------
  732.  
  733. Q#5.1:    For what are the various directories used?
  734.  
  735. A#5.1:    The following is the suggested layout and use of various directories.
  736.     Any given site will likely have more, but these are the "standard"
  737.     ones.  Note that these don't necessarily have to be on different
  738.     physical partitions due to the GNO namespace facility (see Q#7.3).
  739.     This FAQ assumes the following directory structure:
  740.  
  741.     /HFSinclude        GNO standard C header files (required if and
  742.                 only if /usr/include is not on an HFS
  743.                 partition)
  744.     /bin            basic standard programs
  745.     /dev            device drivers
  746.     /etc            configuration files
  747.     /lang            languages
  748.     /lang/orca        ORCA languages
  749.     /lang/orca/languages        compilers
  750.     /lang/orca/libraries        standard ORCA libraries (not used
  751.                     for GNO; see /lib instead)
  752.     /lang/orca/libraries/orcacdefs    standard ORCA/C header files
  753.     /lang/orca/release.notes    READMEs, release notes, etc
  754.     /lang/orca/shell        ORCA editor and ORCA/Shell config files
  755.     /lang/orca/utilities        ORCA/Shell compatible programs
  756.     /lang/orca/utilities/help    These are the ORCA utility help files,
  757.                     which show brief usage information.
  758.                     The preformatted manual pages that
  759.                     come with some utils should _not_ go
  760.                     here.
  761.     /lang/orca/man/man1    manual pages for ORCA/Shell compatible 
  762.                 programs (nroff, troff, or aroff source)
  763.     /lang/orca/man/cat1    manual pages for ORCA/Shell compatible
  764.                 programs (preformatted).  These should not
  765.                 be confused with the "help" files in
  766.                 /lang/orca/utilities/help.
  767.     /lib            standard GNO libraries
  768.     /lib/RInclude        resource compiler include files
  769.     /lib/orcacdefs        holds defaults.h; otherwise empty
  770.     /tmp            scratch directory (for temporary files)
  771.     /usr            UNIX system resources
  772.     /usr/X            X (graphical interface) -related files
  773.     /usr/X/bin        X programs
  774.     /usr/X/lib        X libraries and configuration files
  775.     /usr/X/man        X manual pages
  776.     /usr/bin        additional standard programs
  777.     /usr/games        games
  778.     /usr/games/lib        game configuration files
  779.     /usr/include        GNO standard C header files
  780.     /usr/lib        optional libraries
  781.     /usr/lib/sendmail.d    sendmail configuration files
  782.     /usr/lib/tmac        nroff/troff macro files
  783.     /usr/local        custom and local files
  784.     /usr/local/bin        custom programs
  785.     /usr/local/etc        custom configuration files
  786.     /usr/local/include    custom C header files
  787.     /usr/local/lib        custom libraries and configuration files
  788.     /usr/local/man        manual pages for custom files
  789.     /usr/man        standard manual pages
  790.     /usr/man/cat[1-8]    standard manual pages (preformatted)
  791.     /usr/man/man[1-8]    standard manual pages (nroff, troff, aroff)
  792.     /usr/sbin        system maintenance programs
  793.     /var            heavy write-use (variable) filesystem
  794.     /var/adm        system administratin and log files
  795.     /var/mail        user mailboxes
  796.     /var/spool        spool directories for various daemons
  797.     /var/spool/lpq        line printer spool directory
  798.     /var/spool/news        news daemon spool directory
  799.  
  800. Q#5.2:    What should be in my gshrc file?
  801.  
  802. A#5.2:    Whatever you find necessary, keeping in mind that the gshrc file
  803.     is parsed whenever an instantiation of gsh is started.  This implies
  804.     that a long gshrc file can slow down your system.
  805.  
  806.     Here is one example of a minimal gshrc file. For formatting reasons
  807.     in the FAQ, long lines have been split with a trailing '\' on
  808.     the line to be continued.  Gsh doesn't understand this syntax, so
  809.     be sure to enter them as a single line.
  810.  
  811.         # set prefixes for ORCA languages (see also Q#6.3)
  812.         prefix    13    /lib
  813.         prefix    14    /tmp
  814.         prefix    15    /lang/orca/shell
  815.         prefix    16    /lang/orca/languages
  816.         prefix    17    /lang/orca/utilities
  817.  
  818.         # match lower prefixes. gsh _should_ update these
  819.         # automatically, but doesn't.
  820.         prefix    2    13
  821.         prefix    3    14
  822.         prefix    4    15
  823.         prefix    5    16
  824.         prefix    6    17
  825.  
  826.         # set search path -- gsh parses it backwards!
  827.         set path="/usr/games /lang/orca/utilities /usr/X/bin /usr/bin\
  828.             /bin /usr/local/bin"
  829.         export path
  830.         rehash
  831.  
  832.         # search path for man pages
  833.         setenv MANPATH /man:/usr/man:/usr/local/man:/local/man:\
  834.             /usr/X/man:/lang/orca/man
  835.  
  836.         # settings for occ(1):
  837.         #    create *.o files instead of *.a files
  838.         setenv CCEMULATE 1
  839.         #    set the if and only if you are using ORCA/C 2.0.x.
  840.         setenv CCOLD 1
  841.  
  842. Q#5.3:    Where should I install custom additions to GNO?
  843.  
  844. A#5.3:    Anything you add to your GNO installation beyond what is in the
  845.     base installation should go into the /usr/local hierarchy.
  846.     This will facilitate future updates, in that you will only have
  847.     to replace those directories used by the GNO base distribution,
  848.     and your customized files will not be overwritten.
  849.  
  850.     There are some exceptions to this.  For example, /etc/passwd,
  851.     /etc/namespace, and a few other files that have to be customized
  852.     do not and will not reside in the /usr/local hierarchy.  However,
  853.     these will be kept to a minimum and will be explicitly mentioned
  854.     in future release notes.
  855.  
  856.     If your installed man(1) cannot cannot handle manual pages in
  857.     more than one directory hierarchy, then you need to upgrade your
  858.     man to version 3.0 or later.
  859.  
  860.     GNO v2.0.4 CAVEAT
  861.     ^^^^^^^^^^^^^^^^^
  862.  
  863.     When GNO v2.0.4 (and earlier versions) was released, there
  864.     was no attempt made to have users put add-ons in the /usr/local
  865.     hierarchy.  Therefore, if you're currently running GNO v2.0.4
  866.     it is likely that you have a lot of custom items in /bin,
  867.     /usr/bin, /usr/man, and related directories.  This is complicated
  868.     by the fact that various packages that are considered "standard"
  869.     (such as the Multiuser Update) were not part of the base GNO
  870.     v2.0.4 distribution.
  871.  
  872.     If you are in this situation, then I suggest that you not 
  873.     worry at this time about moving existing programs to the
  874.     /usr/local hierarchy.  Instead, defer this to when GNO v2.0.6
  875.     is released.  In the interim, there is nothing stopping you
  876.     from using the /usr/local hierarchy for anything new that you
  877.     download ...
  878.  
  879. Installing GNO with ORCA
  880. ------------------------
  881.  
  882. Q#6.1:    Do I need separate installations of ORCA/C for use with GNO and 
  883.     ORCA/Shell?
  884.  
  885. A#6.1:    At least partly, yes, although it is possible to reduce duplication
  886.     to a minimum.
  887.  
  888.     GNO requires modifications to some header files and libraries,
  889.     as well as the additions of others that don't come with ORCA/C.
  890.  
  891.     The remaining questions in this section of the FAQ explain how
  892.     to set up such a split installation.  This will allow you run
  893.     both GNO and ORCA/Shell (but not concurrently).  The latter is
  894.     necessary when submitting bug reports to the Byte Works.  Mike
  895.     Westerfield (quite rightly) does not generally accept bug reports
  896.     about programs that fail under GNO but run correctly under
  897.     ORCA/Shell.
  898.  
  899.     CAVEAT:    For the methods explained in this section to work, you must
  900.         be using occ v1.14 when doing compilations with ORCA/C
  901.         v2.0.x.  This is because occ v1.14 will allow older versions
  902.         of ORCA/C to #include the 13/orcacdefs/defaults.h file which
  903.         is automatically included by ORCA/C v2.1.x.
  904.  
  905.         If you are using ORCA/C v2.0.x but not occ, you will have
  906.         to use the #pragma path directive in all of your sources.
  907.         Failure to do so may result in compilation errors or
  908.         unexplained crashes.
  909.  
  910.         Any version of occ may be used when compiling with ORCA/C
  911.         v2.1.x.
  912.  
  913.         These methods are not quite error-free.  See Q#11.11 for
  914.         details.
  915.  
  916.     The information in this section has been used to set up combinations
  917.     of GNO v2.0.4 and GNO v2.0.6 with ORCA/C v2.0.3 and ORCA/C v2.1.x.
  918.  
  919. Q#6.2:    How do I set up ORCA/C so that I can use it with GNO?
  920.  
  921. A#6.2:    === See the CAVEAT in Q#6.1 ===
  922.  
  923.     There are a few aspects to this, so it has been split into various
  924.     questions in this section of the FAQ.  You should read each of
  925.     those questions when so directed, below.  The following instructions
  926.     assume that you have already installed your ORCA languages; various
  927.     files and directories will be moved from their original locations.
  928.  
  929.     If you haven't already done so, change the auxtype of 
  930.     (original_orca_directory)/shell/Editor to hex DC00 (see Q#14.1).
  931.  
  932.     Next, create the directory /lang/orca.  This will be the new
  933.     location of your ORCA distribution.  You should move all the
  934.     files and directories from you original ORCA location to /lang/orca.
  935.     You will therefore have directories like /lang/orca/shell, 
  936.     /lang/orca/languages, and so forth.
  937.  
  938.     The next step is to set up the appropriate GS/OS prefix numbers.
  939.     This procedure is documented in Q#6.3 (don't forget to update
  940.     both your 15/login and ~/gshrc files).
  941.  
  942.     Next, set up your defaults.h file as described in Q#6.5.  As per
  943.     the caveat in Q#6.1, this file will be parsed regardless of which
  944.     version of ORCA/C you're using.
  945.  
  946.     Now, if you're running GNO v2.0.4, you have to modify some header
  947.     files.  See Q#6.6.
  948.  
  949.     Next you have to set up your libraries.  This information is specific
  950.     to your GNO-ORCA/C version combination.  See questions Q#6.7, Q#6.8,
  951.     Q#6.9, or Q#6.10 as appropriate.  Note that the library /lib/libgno
  952.     is obsolete in both GNO v2.0.4 and v2.0.6.  If your /lib directory
  953.     resides on an HFS partition, you will need to rename some of your
  954.     libraries (see also Q#11.4).
  955.  
  956.     If you're using an older version of ORCA/C, you should prototype
  957.     your headers (this is already done for newer versions of ORCA/C).
  958.     Using prototyped headers and #pragma lint -1 can catch a lot of
  959.     bugs, both in user code and in the compiler.  Be very careful that
  960.     you use the correct prototypes.
  961.  
  962.     For programs in your 17 directory that don't work with GNO (such
  963.     as prizm), I recommend putting something like the following in
  964.     your ~/gshrc:
  965.  
  966.         alias prizm echo "prizm not available under GNO"
  967.  
  968.     Remember to put 17 in your PATH environment variable.  See the
  969.     Gsh Reference Manual if you don't know how to do this.
  970.  
  971.     Finally, if you're using ORCA/C v2.0.x, ensure you have occ v1.14
  972.     installed (other versions -- earlier or later -- will not suffice).
  973.     Also edit both 15/login and ~/gshrc to define the CCOLD environment
  974.     variable.  Do NOT define the CCOLD environment variable if you are
  975.     using ORCA/C v2.1.x; you will slow down your compilations.
  976.  
  977. Q#6.3:    GNO with ORCA: What should I use for compilation directories and
  978.     prefixes?
  979.  
  980. A#6.3:    === See the CAVEAT in Q#6.1 ===
  981.  
  982.     In order to minimize file duplication for running GNO and ORCA/Shell
  983.     (but not concurrently -- see Q#2.2), you should set your prefixes up
  984.     as follows.  For GNO, these "volumes" may be defined in /etc/namespace
  985.     (see Q#7.3).  For ORCA/Shell, these pathnames may be relative to
  986.     one or more volumes.
  987.  
  988.         SHARED (used by both GNO and ORCA/Shell)
  989.         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  990.     15    /lang/orca/shell        configuration files
  991.     16    /lang/orca/languages        compilers
  992.     -    /lang/orca/include        ORCA headers
  993.     17    /lang/orca/utilities        ORCA-compatible utilities
  994.     -    /lang/orca/utilities/help    ORCA-compatible utility
  995.                         descriptions
  996.     14    /tmp                scratch (work) directory
  997.  
  998.         GNO (not used by ORCA/Shell)
  999.         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  1000.     13    /lib                main GNO libraries
  1001.     -    /usr/lib            secondary GNO libraries
  1002.     -    /usr/local/lib            secondary GNO libraries
  1003.  
  1004.         ORCA (not used by GNO)
  1005.         ^^^^^^^^^^^^^^^^^^^^^^
  1006.     13    /lang/orca/libraries        ORCA libraries
  1007.  
  1008.  
  1009.     The prefixes shown should be set up in your ~/gshrc file (for GNO),
  1010.     or your 15/login file (for ORCA/Shell).
  1011.  
  1012. Q#6.4:    GNO with ORCA: Where should my C header files go?
  1013.  
  1014. A#6.4:    === See the CAVEAT in Q#6.1 ===
  1015.  
  1016.     While it is possible to have all of your header files in one
  1017.     directory hierarchy (this is how it was done in the stock v2.0.4
  1018.     distribution), it is STRONGLY advised that you keep separate
  1019.     directory hierarchies.  They are:
  1020.  
  1021.         /usr/include
  1022.         /HFSinclude
  1023.         /lang/orca/libraries/orcacdefs
  1024.         /lib/orcacdefs
  1025.         /usr/local/include
  1026.  
  1027.     The /usr/include directory should contain all the header files
  1028.     that ship with GNO.  This will include some subdirectories like
  1029.     sys, machine, and net.
  1030.  
  1031.     In GNO v2.0.6 there are a few files that don't conform to ProDOS
  1032.     naming conventions.  These files should be placed in the /HFSinclude
  1033.     hierarchy.
  1034.  
  1035.     ORCA/C comes with its own set of header files.  Some of these 
  1036.     are used by GNO while others are ignored (because header files
  1037.     of the same names exist in one of the other directory hierarchies).
  1038.     All of these header files should be left in the 
  1039.     /lang/orca/libraries/orcacdefs directory (see Q#6.2).
  1040.  
  1041.     /lib/orcacdefs corresponds to 13/orcacdefs under GNO.  It should
  1042.     contain only one file, defaults.h.  See Q#6.5.
  1043.  
  1044.     /usr/local/include, like everything else in the /usr/local hierarchy,
  1045.     is not used by the GNO base install.  This hierarchy is reserved
  1046.     for site-specific packages that you decide to add.  In particular,
  1047.     /usr/local/include should be used for any header files that you
  1048.     decide to add to your system, and which are not part of the 
  1049.     base installation.
  1050.  
  1051. Q#6.5:    GNO with ORCA: What goes in the 13/orcacdefs/defaults.h file?
  1052.  
  1053. A#6.5:    === See the CAVEAT in Q#6.1 ===
  1054.  
  1055.     There are two versions of this file, one for GNO and one for
  1056.     ORCA/Shell.  For GNO, the /lib/orcacdefs/defaults.h file should
  1057.     contain:
  1058.  
  1059.         #define __appleiigs__
  1060.         #define __GNO__
  1061.         #pragma path "/usr/include"
  1062.         #pragma path "/HFSinclude"    /* needed for GNO v2.0.6 */
  1063.         #pragma path "/lang/orca/libraries/orcacdefs"
  1064.  
  1065.     (See Q#11.11 regarding a problem with using the "path" pragma.)
  1066.  
  1067.     For ORCA/Shell, the /lang/orca/libraries/orcacdefs/defaults.h
  1068.     file should contain:
  1069.  
  1070.         #define __appleiigs__
  1071.  
  1072. Q#6.6:    GNO with ORCA: What header file modifications are necessary?
  1073.  
  1074. A#6.6:    === See the CAVEAT in Q#6.1 ===
  1075.  
  1076.     If you're using GNO v2.0.6, no modifications should be necessary
  1077.     provided you've placed all the GNO header files into /usr/include
  1078.     and /HFSinclude as appropriate.  This applies to both ORCA/C v2.0.3
  1079.     and ORCA/C v2.1.x.
  1080.  
  1081.     There are various header files included with the GNO v2.0.1
  1082.     distribution.  These should all be copied into the /usr/include
  1083.     directory hierarchy as discussed in Q#6.4. (Versions 2.0.2,
  1084.     2.0.3, and 2.0.4 were incremental changes, not complete
  1085.     distributions, and therefore did not include header files.)
  1086.  
  1087.     If you are using the Multiuser package, then you should also 
  1088.     copy over the <time.h> and <utmp.h> files from that package.
  1089.  
  1090.     The files in the following lists are used instead of their ORCA/C
  1091.     counterparts, except where noted by "+++"; those so marked need
  1092.     to be modified as described.
  1093.  
  1094.     Note the last section in this question is a list of suggested
  1095.     changes to the GNO v2.0.4 header files.  These changes you should
  1096.     make yourself.
  1097.  
  1098.     GNO v2.0.4 with ORCA/C v2.0.3
  1099.     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  1100.  
  1101.         errno.h        This one has many GNO error codes added.
  1102.         fcntl.h        Differs in the prototypes of open(2), read(2),
  1103.                 write(2), and definition of OPEN_MAX.
  1104.         signal.h    Completely different for GNO.
  1105.         stdio.h        Differs in the prototypes of fread(3) and
  1106.                 fwrite(3).  The FILE structure uses an
  1107.                 older name for one of its members, but it
  1108.                 doesn't matter.  A prototype for fdopen(3)
  1109.                 and the fileno() macro was added.
  1110.     +++    stdlib.h    You should delete this one and copy the
  1111.                 ORCA/C v2.0.3 stdlib.h from 
  1112.                 /lang/orca/libraries/orcacdefs to
  1113.                 /usr/include.  See the "common" changes
  1114.                 below for more information on this file.
  1115.         string.h    Many new functions were added in the GNO one.
  1116.     +++    types.h        You should delete this one and copy the
  1117.                 ORCA/C v2.0.3 types.h from 
  1118.                 /lang/orca/libraries/orcacdefs to
  1119.                 /usr/include.  See the "common" changes
  1120.                 below for more information on this file.
  1121.  
  1122.     GNO v2.0.4 with ORCA/C v2.1.x
  1123.     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  1124.  
  1125.         errno.h        This one has many GNO error codes added.
  1126.         fcntl.h        Differs in the prototypes of open(2), read(2),
  1127.                 write(2), and definition of OPEN_MAX.
  1128.         signal.h    Completely different for GNO.
  1129.     +++    stdio.h        You should delete this file, then copy the
  1130.                 one from your ORCA/C distribution into
  1131.                 the /usr/include directory.  See the "common"
  1132.                 changes below for more information on this
  1133.                 file.  Note that there was a critical change
  1134.                 to the FILE structure as of ORCA/C v2.1.1b2;
  1135.                 ensure your header file matches your OrcaLib.
  1136.     +++    stdlib.h    You should delete this one and copy the
  1137.                 ORCA/C v2.1.x stdlib.h from 
  1138.                 /lang/orca/libraries/orcacdefs to
  1139.                 /usr/include.  See the "common" changes
  1140.                 below for more information on this file.
  1141.     +++    string.h    You should rename this file to something
  1142.                 else (like "string.old"), then copy the
  1143.                 one from your ORCA/C distribution into
  1144.                 the /usr/include directory.  Finally, you
  1145.                 should copy the prototypes for the following
  1146.                 functions from the old GNO file into the new
  1147.                 one copied from the ORCA/C distribution:
  1148.                     bcopy        bzero
  1149.                     index        rindex
  1150.                     strdup        strupr
  1151.                     strlwr        strset
  1152.                     strnset        strrev
  1153.                     strpblnks    strrpblnks
  1154.                     strpad        strrpad
  1155.                     stricmp        strncmp
  1156.     +++    types.h        You should delete this one and copy the
  1157.                 ORCA/C v2.1.x types.h from 
  1158.                 /lang/orca/libraries/orcacdefs to 
  1159.                 /usr/include.  See the "common" changes
  1160.                 below for more information on this file.
  1161.  
  1162.     GNO v2.0.4 common changes
  1163.     ^^^^^^^^^^^^^^^^^^^^^^^^^
  1164.  
  1165.     The following is a list of suggested changes to the GNO v2.0.4
  1166.     header files.  You have to make these changes yourself; they are
  1167.     not part of the distributed header files.
  1168.  
  1169.     For any files below that don't appear in /usr/include, you should
  1170.     copy the file from /lang/orca/libraries/orcacdefs into /usr/include,
  1171.     then edit the copy in /usr/include.  Do not modify files in 
  1172.     /lang/orca/libraries/orcacdefs.
  1173.  
  1174.     dirent.h (possibly sys/dirent.h):
  1175.         Ensure that in struct dirent, the d_namelen field
  1176.         appears before the d_name field, as described in the
  1177.         GNO v2.0.4 release notes.
  1178.  
  1179.     gno/gno.h:
  1180.         Rename send(2) to procsend(2) and receive(2) to    procreceive(2).
  1181.  
  1182.     stdio.h:
  1183.         Add the following:
  1184.  
  1185.             #define    fileno(f)    ((f)->_file)
  1186.             #define    P_tmpdir    "/tmp"
  1187.             FILE *    fdopen(int, const char *);
  1188.             char *    tempnam(char *, char *);
  1189.             char *    mktemp(char *);
  1190.             int    mkstemp(char *);
  1191.             FILE *    popen(const char *, const char *);
  1192.             int    pclose(FILE *);
  1193.  
  1194.         Add the following if you're using ORCA/C v2.1.x:
  1195.  
  1196.             #define setbuffer(stream,buf,size) ((buf==NULL) ? \
  1197.                 (void)__setvbuf(stream,NULL,_IONBF,0L) : \
  1198.                 (void)__setvbuf(stream,buf,_IOFBF,\
  1199.                     (size_t)size))
  1200.             #define    setlinebuf(stream) (__setvbuf(stream,NULL,\
  1201.                 _IOLBF,0L))
  1202.             int    __fseek(FILE *, long, int);
  1203.             int    __setvbuf(FILE *, char *, int, size_t);
  1204.  
  1205.     stdlib.h:
  1206.         Add the following declarations:
  1207.  
  1208.             int    initenv(void);
  1209.             void    popenv(void);
  1210.             int    pushenv(void);
  1211.             int    putenv(const char *);
  1212.             int    setenv(const char *, const char *, int);
  1213.             void    unsetenv(const char *);
  1214.  
  1215.     sys/ports.h:
  1216.         Change the prototypes of pdelete(2) and preset(2) to:
  1217.  
  1218.             int    pdelete(int, int (*)(void));
  1219.             int    preset(int, int (*)(void));
  1220.  
  1221.     sys/stat.h:
  1222.         Add the following prototype:
  1223.  
  1224.             int    umask(int);
  1225.  
  1226.         This header file contains the following guard macro:
  1227.  
  1228.             #ifndef __BSD_TYPES__
  1229.             #include <sys/types.h>
  1230.             #endif
  1231.  
  1232.         it should be changed to:
  1233.  
  1234.             #ifndef __SYS_TYPES__
  1235.             #include <sys/types.h>
  1236.             #endif
  1237.  
  1238.     sys/times.h:
  1239.         The last line should be modified so that the text following
  1240.         the #endif is in a comment, otherwise it is not legal C
  1241.         source code:
  1242.             #endif    /* _SYS_TIMES_H_ */
  1243.  
  1244.     sys/types.h:
  1245.         Change the typedef of sig_t to:
  1246.             typedef void (*sig_t)(void);
  1247.  
  1248.         The typedef for use_t has an extraneous '_' character.  Of
  1249.         course, if you hit this and aren't compiling the kernel
  1250.         you're doing something wrong since the _IN_KERNEL macro
  1251.         should not normally be defined:
  1252.             typedef unsigned char    use_t;
  1253.  
  1254.     sys/wait.h:
  1255.         Add the following declaration:
  1256.             int    wait(union wait *);
  1257.  
  1258.     time.h:
  1259.         Add the following declarations:
  1260.  
  1261.             void        tzset(void);
  1262.             #ifndef _SVR4
  1263.             struct tz *    timezone(void);
  1264.             #endif
  1265.  
  1266.     types.h:
  1267.         Before the definition of TRUE, add in the following:
  1268.  
  1269.             #undef    TRUE
  1270.             #undef    true
  1271.             #undef    FALSE
  1272.             #undef    false
  1273.  
  1274.     unistd.h:
  1275.         As explained in the lenviron documentation, rename the
  1276.         execve() system call to _execve() (if you have installed
  1277.         /usr/lib/lenviron as described in Q#6.7 or Q#6.8). Insert
  1278.         or uncomment prototypes for execl(), execlp(), execv(),
  1279.         execve(), and execvp().  The execve() prototype should be:
  1280.  
  1281.             int execve(const char *,char * const *,char * const *);
  1282.  
  1283.         Insert the following prototypes.  They are not yet defined
  1284.         in any standard, however they are common routines and are
  1285.         provided in libc for GNO v2.0.6:
  1286.  
  1287.             char *    dirname (const char *);
  1288.             char *    basename (const char *);
  1289.  
  1290. Q#6.7:    GNO with ORCA: What libraries are used for the combination of
  1291.     GNO v2.0.4 and ORCA/C v2.0.x?
  1292.  
  1293. A#6.7:    You must have the following libraries in the sequence given:
  1294.  
  1295.         /lib/lcrypt    (GNO v2.0.1)
  1296.         /lib/lregexp    (GNO v2.0.1)
  1297.         /lib/lstring    (GNO v2.0.1)
  1298.         /lib/ltermcap    (GNO v2.0.1)
  1299.         /lib/libc    (GNO v2.0.4)    [rename to "nlibc" for HFS]
  1300.         /lib/OrcaLib    (GNO v2.0.1)
  1301.         /lib/PasLib    (ORCA/Pascal v2.0.x, required if and only if
  1302.                  you use ORCA Pascal)
  1303.         /lib/SysFloat    (ORCA/C v2.0.x)
  1304.         /lib/SysLib    (ORCA/C v2.0.x)
  1305.  
  1306.     The following libraries are recommended.  The sequence here is not
  1307.     important as they will be read in the order specified on the occ(1)
  1308.     command line:
  1309.  
  1310.         /usr/lib/lflex
  1311.             This provides a main() routine suitable for a
  1312.             flex(1) generated parser.
  1313.         /usr/lib/lgnoasm
  1314.             Provides asm replacements for some libgno symbols.
  1315.             These include "CommandLine", "timezone", "tmpnam".
  1316.         /usr/lib/lenviron
  1317.             [This library is obsoleted as of GNO v2.0.6 --
  1318.             these routines have been incorporated into libc.]
  1319.  
  1320.             This has a replacement for getenv/setenv, exec*,
  1321.             and other routines that ease the porting of UNIX
  1322.             programs.  Note that the prototype and implementation
  1323.             of execve(2) changes from that defined in the GNO
  1324.             docs.
  1325.         /usr/lib/lgetline
  1326.             GNU line input editing.
  1327.         /usr/lib/lgetopt
  1328.             A GNU replacement for the getopt(3) package.
  1329.         /usr/lib/lttylock
  1330.             Provides locktty(3) and unlocktty(3) routines.
  1331.         /usr/lib/lstack
  1332.             [This library is obsoleted as of GNO v2.0.6 --
  1333.             these routines have been incorporated into libc.]
  1334.  
  1335.             Stack checking routines.  These are useful for
  1336.             verifying how much stack space your final program
  1337.             uses so that it may be reduced to a minimum.  The
  1338.             currently available archive contains an object file
  1339.             which may be converted to a library file by
  1340.             makelib(1).
  1341.         /usr/lib/gnulib
  1342.             A GNU replacement for the alloca(3) routine and
  1343.             the getopt(3) package.  This partially overlaps
  1344.             the lgetopt library.
  1345.  
  1346. Q#6.8:    GNO with ORCA: What libraries are used for the combination of
  1347.     GNO v2.0.4 and ORCA/C v2.1.x?
  1348.  
  1349. A#6.8:    You must have the following libraries in the sequence given:
  1350.  
  1351.         /lib/lcrypt    (GNO v2.0.1)
  1352.         /lib/lregexp    (GNO v2.0.1)
  1353.         /lib/lstring    (GNO v2.0.1)
  1354.         /lib/ltermcap    (GNO v2.0.1)
  1355.         /lib/libc    (GNO v2.0.4)    [rename to "nlibc" for HFS]
  1356.         /lib/OrcaLib    (ORCA/C v2.1.x)
  1357.         /lib/PasLib    (ORCA/Pascal v2.1.x, required if and only if
  1358.                  you use ORCA Pascal)
  1359.         /lib/SysFloat    (ORCA/C v2.1.x)
  1360.         /lib/SysLib    (ORCA/C v2.1.x)
  1361.  
  1362.     Note the OrcaLib should be the one shipped with ORCA/C v2.1.x.
  1363.     You can use it provided that you apply the va_end fix described
  1364.     in Q#11.1.
  1365.  
  1366.     You should also install the list of recommended libraries listed
  1367.     in the latter part of Q#6.7.
  1368.  
  1369.     Some people believe the ORCA/C v2.1.x library won't work properly
  1370.     with pipes.  This has neither been demonstrated nor disproved.
  1371.     If you find hard evidence either way, please contact Devin Reade
  1372.     at the address at the top of this FAQ.
  1373.  
  1374.     If you need pipes, you can try the libraries that shipped with GNO
  1375.     v2.0.1, but you will not get any of the Byte Works bug fixes.  Also,
  1376.     it has been reported that the GNO modifications introduced stdio
  1377.     bugs that weren't in the original version (no details available).
  1378.  
  1379.     Note that you _must_ keep the versions of OrcaLib, SysFloat, and
  1380.     SysLib consistent; you cannot use some from OrcaC v2.0.x and others
  1381.     from OrcaC v2.1.x.  You may run into problems from unexpected
  1382.     behavior to memory trashing.
  1383.  
  1384. Q#6.9:    GNO with ORCA: What libraries are used for the combination of
  1385.     GNO v2.0.6 and ORCA/C v2.0.x?
  1386.  
  1387. A#6.9:    This combination is no longer supported.  You will have to
  1388.     upgrade to ORCA/C v2.1.x.
  1389.  
  1390. Q#6.10:    GNO with ORCA: What libraries are used for the combination of
  1391.     GNO v2.0.6 and ORCA/C v2.1.x?
  1392.  
  1393. A#6.10:    You must have the following libraries in the sequence given.  You
  1394.     should not add any other libraries to this directory as it will
  1395.     slow down linking for all programs.
  1396.  
  1397.         /lib/libc    (GNO v2.0.6)   [rename to "nlibc" for HFS]
  1398.         /lib/lsaneglue    (GNO v2.0.6)   [renaem to "nlsaneglue" for HFS]
  1399.         /lib/OrcaLib    (GNO v2.0.6)
  1400.         /lib/PasLib    (ORCA/Pascal v2.1.x, required if and only if
  1401.                  you use ORCA Pascal)
  1402.         /lib/SysFloat    (GNO v2.0.6)
  1403.         /lib/SysLib    (ORCA/C v2.1.x)
  1404.  
  1405.     The following libraries are recommended.  The sequence here is not
  1406.     important as they will be read in the order specified on the occ(1)
  1407.     command line:
  1408.  
  1409.         /usr/lib/lflex
  1410.             This provides a main() routine suitable for a
  1411.             flex(1) generated parser.
  1412.         /usr/lib/lgetline
  1413.             GNU line input editing.
  1414.         /usr/lib/lgetopt
  1415.             A GNU replacement for the getopt(3) package.
  1416.         /lib/lstring
  1417.             Non standard string routines. (*** Obsolete?)
  1418.         /lib/ltermcap
  1419.             Terminal capabilities library.  Moved from /lib.
  1420.         /usr/lib/lttylock
  1421.             Provides locktty(3) and unlocktty(3) routines.
  1422.         /usr/lib/gnulib
  1423.             A GNU replacement for the alloca(3) routine and
  1424.             the getopt(3) package.  This partially overlaps
  1425.             the lgetopt library.
  1426.  
  1427.     The following libraries either are obsolete or have been merged with 
  1428.     libc and should NOT be used:
  1429.  
  1430.         /lib/lcrypt
  1431.         /usr/lib/lgnoasm
  1432.         /usr/lib/lenviron
  1433.         /usr/lib/lregexp
  1434.         /usr/lib/lstack
  1435.  
  1436. System Configuration
  1437. --------------------
  1438.  
  1439. Q#7.1:    What patches should I have applied for GNO?
  1440.  
  1441. A#7.1:    GUPP (Grand Unified Patch Program by Nathan Mates) is recommended
  1442.     for fixing memory-trashing bugs present in GNO kernel versions
  1443.     v2.0.4 and v2.0.6-beta.  GUPP also does other patches that may be
  1444.     applicable to programs running under GNO.  GUPP will not touch
  1445.     kernels earlier than v2.0.4 even though those bugs probably exist
  1446.     in earlier versions of the kernel.
  1447.  
  1448.     GUPP is available from the ground and caltech sites, and also
  1449.     at ftp://ftp.visi.com/users/nathan/a2software/gupp.shk. See also
  1450.     Q#14.4.
  1451.  
  1452. Q#7.2:    How do I change the information that's printed before the login
  1453.     prompt?
  1454.  
  1455. A#7.2:    Check in the /etc/gettytab file. There's a line near the top that
  1456.     contains the login string.  It is preceded by an "im:", which is
  1457.     an acronym for "initial message".
  1458.  
  1459. Q#7.3:    How do I map /usr, /local, /var, and other partitions to GS/OS
  1460.     volume or directory names?
  1461.  
  1462. A#7.3:    The kernel provides this functionality through the namespace
  1463.     facility, which is configured in /etc/namespace.  See the Kernel
  1464.     Reference Manual for details.  See also the Kernel Bugs section
  1465.     of question #704 regarding the format of the file.
  1466.  
  1467. Q#7.4:    How do I set up cron?
  1468.  
  1469. A#7.4:    There are man pages for this that were distributed with the v2.0.4
  1470.     GNO update, but they don't quite match the implementation provided
  1471.     with the Multi-user 2.0 package.
  1472.  
  1473.     To activate cron, you must uncomment its entry in the /etc/inittab
  1474.     file.  See the init(8) man page for the format of this file.
  1475.  
  1476.     Cron is controlled through the /etc/crontab file.  Unlike its UNIX
  1477.     counterparts, the GNO cron does *not* support setting of environment
  1478.     variables in the crontab file.  These would be lines of the form:
  1479.         SHELL=/bin/sh
  1480.         MAILTO=gdr
  1481.  
  1482.     Any line which begins with a hash (#) character is considered
  1483.     to be a comment and is ignored.
  1484.  
  1485.     All other lines in this file are expected to have five space-
  1486.     delimited date/time fields, followed by a user name field, followed
  1487.     by a command.  The first five fields are:  
  1488.         minute        (0-59)
  1489.         hour        (0-23)
  1490.         day of month    (1-31)
  1491.         month        (0-11)
  1492.         day of week    (0-6)        (appears to be ignored)
  1493.     Multiple values may be specified either separated by commas,
  1494.     or as a range separated with a hyphen.
  1495.  
  1496.     Following the five date/time fields is a username field.
  1497.     Although it has to be present, it does not appear to be used
  1498.     by the current cron implementation.
  1499.  
  1500.     The last field is the command to be executed at the specified
  1501.     time.  Unlike UNIX cron implementations, these commands _are_not_
  1502.     executed from a subshell, so meta characters and file redirection
  1503.     cannot be used.  
  1504.  
  1505.     You cannot split cron commands into separate lines of the crontab
  1506.     file.  Any '%'s in the command are replaced by newlines.  Unlike
  1507.     UNIX crons, the text appearing after a '%' character _is_not_
  1508.     piped to the input of the command.
  1509.  
  1510.     BUG WARNING:    Do not use more than 10 multiple values in each
  1511.             of the date-time fields; if there are more than
  1512.             10, cron's memory structures are reported to get
  1513.             corrupted.
  1514.  
  1515. Q#7.5:    Why won't my entry in the inittab file work correctly?
  1516.  
  1517. A#7.5:    There are two common sources of problems.  The first is due
  1518.     to improper syntax in the inittab file.  See the inittab(5) and
  1519.     initd(8) manual pages for the correct syntax.
  1520.  
  1521.     The second common problem is not due to the inittab file, but
  1522.     rather because the command you are trying to invoke is being
  1523.     invoked incorrectly.  The way to check if this is the case is
  1524.     to run the command interactively and see what diagnostic messages
  1525.     appear.  You should also check the system log files for messages
  1526.     (see syslogd(8)).
  1527.  
  1528. Networking
  1529. ----------
  1530.  
  1531. Q#8.1:    Does GNO provide TCP/IP and/or SLIP support?
  1532.  
  1533. A#8.1:    Most of the required kernel support is available in GNO v2.0.4,
  1534.     but it is not complete and there is nothing to take advantage
  1535.     of it.  However, the remaining kernel support has been added
  1536.     to the upcoming version.  This, however, does not include the
  1537.     TCP stack, which is considered to be a separate product from
  1538.     GNO.
  1539.  
  1540.     At this time, the kernel has only been modified to recognize
  1541.     GS/TCP.
  1542.  
  1543. Q#8.2:    Is GS/TCP available?  Where can I get it?
  1544.  
  1545. A#8.2:    GS/TCP is not yet available to the general public.  Information
  1546.     on it's status and an overview of the project is available from
  1547.     the GS/TCP web page:
  1548.  
  1549.         http://www.geeks.org/~taubert/gstcp/index.html
  1550.  
  1551. Q#8.3:    Does Marinetti work with GNO?
  1552.  
  1553. A#8.3:    Recently, Richard Bennett has released Marinetti, a beta-level
  1554.     TCP/IP stack for the IIgs that does not require GNO.
  1555.  
  1556.     Experimentation with the Marinetti/GNO combination has been
  1557.     sketchy so far.  However, here are some initial observations,
  1558.     in no particular order:
  1559.  
  1560.     - Running individual programs that rely on Marinetti seem 
  1561.       to work the same way under GNO as they do without GNO.
  1562.       (However, see the following observations.)
  1563.  
  1564.     - Processes are unable to block while waiting for input.
  1565.       Therefore, they must do a "busy wait".  While this does
  1566.       not normally matter on the GS, it is considered to be
  1567.       Rude Behavior under GNO since it steals clock cycles that
  1568.       could be used by other processes.
  1569.  
  1570.     - It would be inadvisable to have Marinetti block a process
  1571.       that is waiting on input, since GNO is in a mutex state when
  1572.       accessing the ToolBox.  Therefore, if Marinetti were to block
  1573.       a process, then all of GNO would be blocked.
  1574.  
  1575.     - Development on the Marinetti/GNO combination is still in the
  1576.       planning stage.
  1577.  
  1578.     - The optimal method for programs running under the GNO/Marinetti
  1579.       combination seems to be the the same way that GNO interacts
  1580.       with GS/TCP; through the kernel.  If programs limit themselves
  1581.       to using the kernel interface (which uses BSD sockets) then
  1582.       the kernel could potentially use either GS/TCP or Marinetti,
  1583.       whichever is active.  The kernel could worry about blocking
  1584.       processes, ensuring an appropriate use of resources.  The 
  1585.       kernel interfaces (user libraries) could perhaps be written
  1586.       to use Marinetti directly in the case where GNO is not running.
  1587.       This would allow a GNO-aware program to work either with
  1588.       or without GNO.
  1589.  
  1590.       Programs that use the Marinetti IPC mechanism directly will
  1591.       probably still work under GNO, but can be expected to have
  1592.       problems multitasking.
  1593.       
  1594.       By the way, the above paragraph is pure rambling and supposition
  1595.       by the FAQ maintainer.  The GNO kernel currently knows nothing
  1596.       about Marinetti.
  1597.  
  1598.     - Richard has expressed a willingness to work with the GNO
  1599.       development team to ensure that the two products can coexist.
  1600.  
  1601.     For the latest status on Marinetti, see the Marinetti home page:
  1602.  
  1603.         http://www.zip.com.au/~kashum/marinetti
  1604.  
  1605.     If you have additional information regarding the Marinetti/GNO
  1606.     combination, please email the maintainer of this FAQ.
  1607.  
  1608. Q#8.4:    What TCP/IP network utilities are available?
  1609.  
  1610. A#8.4:    Several utilities have been written and should be made available
  1611.     with the release of GS/TCP.  They include:
  1612.         ftp, telnet, irc, ping, finger, rcp
  1613.  
  1614. Q#8.5:    Is there a WWW browser for GNO and GS/TCP?
  1615.  
  1616. A#8.5:    A text oriented browser has been ported by Derek Taubert and
  1617.     requires the GS/TCP package. Derek has also done some work on
  1618.     a Graphics based WWW browser.  Neither package has as yet been
  1619.     released.
  1620.  
  1621.     There are no known WWW browsers available yet that are based
  1622.     on Marinetti.  This is subject to change, and you should see
  1623.     the Marinetti web page for the latest details.  See Q#8.3.
  1624.  
  1625. Q#8.6:    Can I use a serial card or internal modem with GNO?
  1626.  
  1627. A#8.6:    Currently the GNO serial drivers only support the two built-in
  1628.     serial ports.  This does not imply that you cannot use a 
  1629.     serial card in a remote machine (such as a IIe) that is connecting
  1630.     to your IIgs running GNO.
  1631.  
  1632. Q#8.7:    What should I use for my modem port control panel settings.
  1633.  
  1634. A#8.7:    These settings will usually work.  See the Notes, below.
  1635.  
  1636.     Device Connected:        Modem
  1637.     Line Length:            Unlimited
  1638.     Delete first LF after CR:    No
  1639.     Add LF after CR:        No
  1640.     Echo:                No
  1641.     Buffering:            Yes
  1642.     Baud:                19200    (1)
  1643.     Data/Stop Bits:            8/1    (2)
  1644.     Parity:                None    (2)
  1645.     DCD Handshake:            Yes
  1646.     DSR/DTR Handshake:        Yes
  1647.     XON/XOFF Handshake:        No
  1648.  
  1649.     Notes:    1. The baud should be set to whatever is appropriate
  1650.            to your system.  Unless you are using a modem or 
  1651.            serial line that is slower than 14400 bps, this will
  1652.            almost always be "19200".
  1653.  
  1654.         2. Set data/stop bits and parity as appropriate for your
  1655.            site.  8N1 is the most common setting.
  1656.  
  1657. Q#8.8:    How can I initialize my serial ports at GNO "boot" time?
  1658.  
  1659. A#8.8:    The easiest way to do this is through initd(8).  Add the following
  1660.     lines to your /etc/initab file:
  1661.  
  1662.         # this will initialize the modem port on startup
  1663.         md:b:once:i:/usr/sbin/runover .ttya /bin/stty 38400
  1664.  
  1665.     You should of course change "38400" to whatever speed is appropriate
  1666.     for your site.
  1667.  
  1668. Q#8.9:    How do I hook up a terminal to the IIgs' printer/modem port?
  1669.  
  1670. A#8.9:    This answer describes hooking up a terminal to the printer port.
  1671.     Hooking one up to the modem port will be similar except that
  1672.     .ttya should be used instead of .ttyb.
  1673.  
  1674.     On the hardware side, you will need a mini DIN 8 to DB25 printer
  1675.     cable.  This should be connected from the IIgs' printer port
  1676.     to the port on the terminal that would normally be hooked to
  1677.     a modem.
  1678.  
  1679.     Next, you have to run a getty(8) over the printer port.  Add
  1680.     this line to your /etc/inittab file:
  1681.  
  1682.         pp:23478:rest::/usr/sbin/getty 8bit.xxxx .ttyb
  1683.  
  1684.     where xxxx is the speed. Remove '78' from '23478' if you want
  1685.     to run it only in multiuser mode.  See also Q#8.8 regarding 
  1686.     initialization of the serial port.
  1687.  
  1688.     In order for the change to take effect, you either have to quit
  1689.     and restart GNO, or type '/bin/init q' (without the quotes).
  1690.  
  1691. Q#8.10:    How do I enable GNO to activate dialup access.
  1692.  
  1693. A#8.10:    This question is not about using your IIgs to dial _out_ to another
  1694.     machine.  It means that you're allowing _other_ machines to 
  1695.     dial _in_ to your IIgs running GNO.
  1696.  
  1697.     The first thing you should consider is whether you _really_ want
  1698.     to do this.  GNO doesn't have any user/group file permissions,
  1699.     so as soon as someone is logged into your IIgs, they will have
  1700.     read/write access to _all_ of your files.  Because of this, the
  1701.     only layer of protection you have is dialup/getty and the security
  1702.     of the password file (including how well _all_ passwords are
  1703.     chosen).  There has been no known investigation into the security
  1704.     of the GNO dialup/getty.
  1705.  
  1706.     That said, the way to enable dialup access is through the dialup(8)
  1707.     program.  It is invoked as
  1708.         dialup tty [speed [init_string]]
  1709.  
  1710.     Normally this would be done at GNO "boot" time through the initd(8)
  1711.     facility.  Add the following to your /etc/inittab file:
  1712.  
  1713.         # This enables the modem for remote dialup (_into_ the IIgs)
  1714.         # when in multiuser mode (run level 2 or 3).
  1715.         t2:23:rest::/usr/sbin/dialup .ttya 38400 ate1qs0=1s11=50\\r
  1716.  
  1717.     Ensure you substitute the "38400" with a speed appropriate to your
  1718.     hardware.  Note that "14400" is not considered to be a valid speed.
  1719.     If you are using a 14400 kb/s modem, you should use "19200" as the
  1720.     speed setting.
  1721.  
  1722.     See also Q#8.8 regarding initialization of the serial port.
  1723.  
  1724.     You should also replace the initialization string with one suitable
  1725.     for your modem (consult your modem manual).  The one shown above
  1726.     contains the following HAYES commands:
  1727.         at    (start command)
  1728.         e1    local echo on
  1729.         s0=1    auto answer on
  1730.         s11=50    set touch tone duration to 50ms
  1731.         \\r    escaped carriage return (ends command)
  1732.  
  1733. Q#8.11:    What do I use for a ProTERM termcap entry?
  1734.  
  1735. A#8.11:    This termcap entry is suitable for use with any UNIX machine
  1736.     (that uses termcap rather than terminfo) being accessed from
  1737.     ProTERM:
  1738.  
  1739. #
  1740. # ProTerm Special
  1741. #
  1742. pt|pse|proterm-special|Proterm Special Emulation:\
  1743.         :ae=^N:am:al=^V:bl=^T^A^E@:bs:bw:cl=^L:cm=^^%r%+ %+ :co#80:ce=^Y:\
  1744.         :cd=^W:dc=^D:dl=^Z:do=^J:eo:eA=^P:ho=^X:ic=^F:il=^N:i3=^L:\
  1745.         :is=^L^N:kd=^J:kl=^H:kr=^U:ku=^K:le=^H:li#24:ll=^^ 8:mb=^O:md=^O:\
  1746.         :me=^N:mh=^O:mr=^O:nd=^U:nl=\n+^A:pt:rs=^N:se=^N:so=^O:ta=^I:\
  1747.         :ue=^N:up=^K:us=^O:xn:ns:as=^P:bc=^H:r1=^N:r2=^N:r3=^N:\
  1748.         :ms:mi:sf=^J:sr=^K:as=^P:i1=^N:i3=^N:NP:dn=^J:
  1749.  
  1750. Q#8.12:    Is there a mail/news package available for GNO?
  1751.  
  1752. A#8.12:    There is a rudimentary one called MuGS by Brian Tao.  It requires
  1753.     a shell account (presumably on a UNIX box) for part of the
  1754.     software.  The base MuGS package handles news articles that
  1755.     are spooled on the UNIX machine's local disk.  There is an NNTP
  1756.     (Net News Transfer Protocol) patch by Devin Reade that allows
  1757.     MuGS to work with an NNTP server.  MuGS is available as described
  1758.     in its describe(1) entry (see Q#4.4).
  1759.  
  1760.     Because of a lack of TCP/IP there is no software for GNO v2.0.4
  1761.     that allows a IIgs to connect to the 'net via NNTP or SMTP.
  1762.  
  1763.     Jeff Markham provided the following suggestion:
  1764.  
  1765.         I've been using the gmail system, and I've come up with
  1766.         something that seems to work ok with gmail and sendmail.
  1767.  
  1768.         Create the following two files.  The first is /bin/send:
  1769.         [gdr:  The second and third lines should be a single line
  1770.                without the escaped newline.  It has been printed
  1771.                here as is for clarity:
  1772.  
  1773.             #!/bin/gsh
  1774.             /bin/foreach x /var/spool/sendmail/out/* \
  1775.                 < /bin/send.dat > .null
  1776.  
  1777.         The second is /bin/send.dat:
  1778.  
  1779.             tail +2 $x | /usr/sbin/sendmail 
  1780.             rm $x
  1781.  
  1782.         That combo works well enough to send the mail on it's way.
  1783.         The way I use to get around gmail's need for all config
  1784.         files to be in the same folder as the exe is by using the
  1785.         following /bin/mail file:
  1786.  
  1787.             #! /bin/gsh
  1788.             rm /bin/signature /bin/gmail.cf > .null
  1789.             cp $HOME/gmail/* /bin
  1790.             gmail
  1791.             mv /bin/gmail.o $HOME/gmail
  1792.             send
  1793.  
  1794.         It copies all the set-up files, calls gmail, returns the
  1795.         only needed file to the users account and sends any mail.
  1796.  
  1797.         Comments on my process are welcome.
  1798.  
  1799. Q#8.13:    How do I use copycat?
  1800.  
  1801. A#8.13:    There seem to be two versions of copycat available.  One version
  1802.     takes two tty names on the command line, the other takes only one.
  1803.     It is unclear which version numbers correspond to which behavior;
  1804.     the version that takes only one argument lists itself as v1.5.0,
  1805.     however the documentation for v1.5.0 definitely lists a requirement
  1806.     for two arguments.
  1807.  
  1808.     That said, there are a few ways to use copycat.  This answer will
  1809.     assume that you wish to communicate from the GNO console with a
  1810.     terminal hooked to your modem port.  If you are using the TMTerm
  1811.     NDA, then substitute ".ttyco" in this example with ".ttyq0".
  1812.  
  1813.     The first thing you must do to use copycat is ensure that your 
  1814.     serial port is properly initialized.  Use the stty(1) command
  1815.     like this:
  1816.         stty 38400 < .ttya
  1817.     You should substitute "38400" with whatever speed was used for
  1818.     setting up your link.  ".ttya" is the modem port device.  (For
  1819.     the printer port, use ".ttyb".)
  1820.  
  1821.     Now all you have to do is issue the following command.  The second
  1822.     argument may not be required or accepted in your version of copycat:
  1823.         copycat .ttya .ttyco
  1824.  
  1825.     You will see the prompt:
  1826.         Break character is '^\'
  1827.  
  1828.     You are now connected with whatever is hooked up to your modem 
  1829.     port.  To get the copycat command prompt, type the control
  1830.     character (CONTROL-\).
  1831.  
  1832.     See the copycat documentation and man page for more details.
  1833.     It explains how to do interesting things like allowing a terminal
  1834.     on your printer port to use your modem without interfering with
  1835.     the GNO console.
  1836.  
  1837. Q#8.14:    How do I use rz/sz?
  1838.  
  1839. A#8.14:    rz/sz are usually used in conjunction with copycat.  The important
  1840.     part to remember is that while copycat is used to control the 
  1841.     remote end of the file transfer, it must not be running _during_
  1842.     the transfer.
  1843.  
  1844.     The following example assumes you are sending a file from the 
  1845.     remote machine to the IIgs.  Steps taken to go the other direction
  1846.     will be similar.
  1847.  
  1848.     The first step is to initialize your modem port and start copycat
  1849.     as explained in Q#8.13.  In this example, "unix% " is used as the
  1850.     prompt on the remote machine, and "gno% " as the prompt on the
  1851.     IIgs.  Extraneous blank lines have been deleted.
  1852.  
  1853.         gno% stty 38400 < .ttya
  1854.         gno% copycat .ttya
  1855.             Break character is '^\'
  1856.         unix% 
  1857.  
  1858.     Next, start the file transfer on the UNIX end.  There are problems
  1859.     with some versions of UNIX sz if the "-l1024" flag is not given
  1860.     (others don't recognize this flag).  See the rz/sz README.GNO
  1861.     file and the UNIX sz man page for details.  Remember to use the
  1862.     "-a" flag if you want a text file transfer:
  1863.  
  1864.         unix% sz -a testfile.bsq
  1865.         **B00000000000 14
  1866.  
  1867.     Now type the copycat break character, CONTROL-\, quit from copycat,
  1868.     and start rz on the GNO side:
  1869.  
  1870.         copycat> quit
  1871.         gno% rz < .ttya > .ttya &
  1872.     
  1873.     When the file transfer is finished, don't forget to log off the
  1874.     remote machine.  To get there, you have to restart copycat:
  1875.  
  1876.         gno% copycat .ttya
  1877.             Break character is '^\'
  1878.         unix% logout
  1879.         ^\
  1880.         copycat> quit
  1881.         gno%
  1882.  
  1883. Q#8.15:    Why do I get errors when trying to access the (modem/serial) port?
  1884.  
  1885. A#8.15:    This is usually caused by serial port configuration problems.
  1886.     Common symptoms may be:
  1887.         % copycat .ttyco .ttya
  1888.         Error opening tty .ttya, aborting.
  1889.     or
  1890.         % /usr/sbin/getty 8bit.38400 .ttya
  1891.         getty: .ttya: I/O error
  1892.  
  1893.     The first thing to check is that the following GNO serial port
  1894.     drivers exist:
  1895.         /dev/modem
  1896.         /dev/printer
  1897.  
  1898.     Next, ensure the following two lines are in your /etc/tty.config
  1899.     file, and that they are uncommented:
  1900.         modem        2    .ttya
  1901.         printer        1    .ttyb
  1902.  
  1903.     Finally, ensure that SIM (the Serial Interrupt Manager) is present
  1904.     and active.  This is an init in your system.setup directory:
  1905.         */system/system.setup/sim
  1906.  
  1907.     Remember to reboot your system if you've made any changes in
  1908.     or to comply with the above requirements.
  1909.         
  1910. Porting UNIX Programs to the GNO Environment
  1911. --------------------------------------------
  1912.  
  1913. Q#9.1:    What programs/utilities should I have to port UNIX source code to GNO?
  1914.  
  1915. A#9.1:    Strictly speaking, all you need is a C compiler (since UNIX source
  1916.     tends to be in C).  However, there are a few programs that 
  1917.     can be considered "essentials" for doing ports.  All of these
  1918.     are mentioned in the section on "Compiling":
  1919.  
  1920.         ORCA/C, occ, dmake
  1921.  
  1922. Q#9.2:    What are the common problems encountered when porting UNIX source
  1923.     to GNO?
  1924.  
  1925. A#9.2:    The first thing to watch for is known compiler and library bugs.
  1926.     Soenke Behrens maintains the current ORCA/C bug report list.
  1927.     You should keep the contents of this list in mind when examining
  1928.     the target source code.  The ORCA/C bug report list may be found at
  1929.  
  1930.         http://www.arrowweb.com/sbehrens/obugs.htm
  1931.  
  1932.     This list has been considerably shorted since the release of
  1933.     ORCA/C v2.1.0.  If you have an earlier version of ORCA/C, you
  1934.     should seriously consider an upgrade.
  1935.  
  1936.     The following items should be watched for, in no particular order.
  1937.     Since UNIX source is usually in C, that language is assumed for
  1938.     the rest of this section, where relevant:
  1939.  
  1940.     sizeof(int)
  1941.         The size of the type "int" is implementation-defined.
  1942.         While most modern C compilers use 32 bits, ORCA/C still
  1943.         uses 16 bits since this is the "natural" integer size of
  1944.         the 65816.  This also results in more effective code
  1945.         generation.
  1946.  
  1947.         While the size of an int shouldn't make a difference to
  1948.         any well-written code, there is some available source code
  1949.         that assumes that ints are 32 bits.  You should watch for
  1950.         this in any code that does bit manipulations.  You should
  1951.         also watch for code that freely converts between integers
  1952.         and pointers.  GNU (Free Software Foundation) software
  1953.         is often bad for this.
  1954.  
  1955.     recursion
  1956.         When possible, recursion should be avoided when programming
  1957.         on the Apple IIgs.  This is because recursion invariably
  1958.         causes stack growth and the stack can only exist in bank
  1959.         zero.  This means that the maximum space available for
  1960.         the stack is 64k.  In practise, it is much smaller.
  1961.  
  1962.         This problem is exacerbated under GNO where all processes
  1963.         must share the available stack space (each process has its
  1964.         own stack, though).
  1965.  
  1966.         Any program that uses recursion can be rewritten to use
  1967.         iteration instead.  You should try to do this when possible.
  1968.         If you _do_ use recursion, don't allocate a huge stack;
  1969.         this will keep other programs from executing.  Also, you
  1970.         should leave in stack checking and stack repair (if
  1971.         programming with ORCA/C) to ensure that your recursion
  1972.         does not crash the machine if it goes too far.
  1973.  
  1974.     reference to absolute file descriptors
  1975.         True UNIX machines invariably use the file descriptors 0, 1,
  1976.         and 2 for standard input, standard output, and standard error,
  1977.         respectively.  Under GNO, the file descriptors used are 1,
  1978.         2, and 3.
  1979.  
  1980.         This causes a problem when source code is written to use
  1981.         these descriptors directly.  You should search your code
  1982.         for references to these descriptors, typically in calls
  1983.         to open, close, read, write, dup, dup2, and fcntl.
  1984.  
  1985.         Instead of replacing these digits with other digits though,
  1986.         you should use the macros STDIN_FILENO, STDOUT_FILENO, and
  1987.         STDERR_FILENO defined in <unistd.h>.  This will ensure
  1988.         that your source is kept portable.
  1989.  
  1990.     fork
  1991.         Because of problems that are discussed in the fork(2) man
  1992.         page and the kernel reference, the fork system call under
  1993.         GNO is different than other versions of UNIX.  Besides
  1994.         having a different prototype, the parent and child process
  1995.         share the same address space.  In this respect, GNO is less
  1996.         a multitasking environment than it is a multithreading 
  1997.         environment.
  1998.  
  1999.         Search for calls to fork; you will have to rewrite these
  2000.         sections of code.  See also the man page for fork2(2); it
  2001.         may be more suited to your purposes.
  2002.  
  2003.         Also note than when compiling routines that make a call
  2004.         to fork, you should turn off ORCA/C's stack repair code.
  2005.         This means that you should be using an optimization level
  2006.         of at least 8.
  2007.  
  2008.     read/write of newline character
  2009.         Most UNIX systems use LF (ASCII 0x0a) as the line delimiter.
  2010.         Both Apple II and Macintosh computers use CR (ASCII 0x0d)
  2011.         as the line delimiter.  The C newline character is '\n';
  2012.         ASCII 0x0a.
  2013.  
  2014.         While the stdio routines (fprintf(3), fread(3), etc) usually
  2015.         make this difference unnoticable by doing CR-->LF translation
  2016.         on input and LF-->CR translation on output, no such
  2017.         translation is done on files accessed through read(2) and
  2018.         write(2).  Specifically, the GNO open(2) does not recognize
  2019.         the ORCA/C O_BINARY bit in it's second argument.
  2020.  
  2021.         Therefore, if the program you are porting makes calls to
  2022.         read(2) and write(2), watch for the '\n' character in your
  2023.         code.  You may have to change this to '\r'.  Don't do it
  2024.         blindly, because many programs will use both stdio and
  2025.         operations on the bare file descriptors.
  2026.  
  2027.         One suggestion is to modify your programs low-level I/O
  2028.         routines to modify the I/O buffer prior to calling write(2)
  2029.         and after calling read(2).
  2030.  
  2031.     variadic functions
  2032.         Some (poorly written) UNIX programs have variadic functions
  2033.         where the number of provided arguments don't match the 
  2034.         number of arguments expected by the called routine.  Even
  2035.         though this is in some cases legal ANSI/C, versions of
  2036.         ORCA/C prior to v2.1 would puke magnificently when encountering
  2037.         such code.  Some of these cases are now handled in a more
  2038.         robust fashion by ORCA/C v2.1 and later.
  2039.  
  2040.         If you are _defining_ (as opposed to using) variadic functions,
  2041.         you must turn off stack repair code around the definitions
  2042.         of those functions.
  2043.  
  2044.         The ORCA/C manual (and especially the release notes for
  2045.         v2.1) have important and detailed information on this topic.
  2046.         See the sections on the optimize and debug #pragmas.
  2047.  
  2048.     open, chmod, fchmod, creat, st_mode, stat, fstat, lstat
  2049.         In general, the bits in the mode parameter of these
  2050.         functions do not directly map between UNIX and GNO
  2051.         implementations.  If your application is using macros
  2052.         such as S_IREAD or S_IWRITE for the mode parameters, and
  2053.         those macros are taken from the system header file
  2054.         <sys/stat.h>, then you probably don't need to modify your
  2055.         application.
  2056.  
  2057.         If, on the other hand, your application is using its own
  2058.         constants for the mode parameter, you should convert it
  2059.         to use the standard macros.  Failure to do so may result
  2060.         in files with strange GS/OS flags set, or file tests failing
  2061.         in your program.
  2062.  
  2063.     /dev
  2064.         One of the UNIX philosophies is that "everything is a file".
  2065.         The /dev directory on UNIX systems contain device special
  2066.         files.  Accessing these files is the way to access the
  2067.         relevant hardware.
  2068.  
  2069.         For GNO programs, you should not access devices in the
  2070.         /dev directory.  For example, opening "/dev/console" for
  2071.         writing will not have the expected effect.  Instead you
  2072.         should open the corresponding GS/OS device, ".ttyco".
  2073.  
  2074.         The portable (and suggested) method of handling these cases
  2075.         is not to change the value of the string (in this example)
  2076.         from "/dev/console" to ".ttyco".  Instead, use the macros
  2077.         defined in the file <paths.h>.  For this example, one would
  2078.         use the macro _PATH_CONSOLE.
  2079.  
  2080.     standard path assumptions
  2081.         This one is closely tied in with the "/dev" description
  2082.         above.  The <paths.h> file contains macros for various
  2083.         standard paths.  The macros, instead of the actual paths,
  2084.         should be used to maximize portability.
  2085.  
  2086.     signal handlers
  2087.         When a signal handler is called, the data bank register
  2088.         may not have an expected value.  If your program references
  2089.         global scalars, it may crash.  To avoid this, all functions
  2090.         used as signal handlers should have their definition
  2091.         preceded by
  2092.             #pragma databank 1
  2093.         and followed by
  2094.             #pragma databank 0
  2095.  
  2096.     validity of pathnames
  2097.         Most programs make assumptions about what constitutes
  2098.         a valid file name.  For most modern Unices, a valid
  2099.         file name follows the POSIX portable filename character
  2100.         set:  The characters a-z and A-Z, the digits 0-9, and
  2101.         '.', '_', and '-'.  The '-' is not used as the first
  2102.         character of a file name, and '/' is the directory
  2103.         separator character.  The maximum filename length is
  2104.         at least 14 characters, and the maximum pathname length
  2105.         is at least 255 characters.
  2106.  
  2107.         Now this is different from what is available under GNO.
  2108.         The ProDOS FST provides only a subset of the above.  The
  2109.         HFS FST provides a superset, but HFS is too slow, too
  2110.         buggy, and too unmaintainable for many users.
  2111.  
  2112.         The problem is also compounded by the fact that under
  2113.         GS/OS, the ':' is a directory separator.  '/' may be used
  2114.         but it is mapped internally to ':'.
  2115.  
  2116.         Unfortunately, there is no general consensus on how to
  2117.         handle pathnames under GNO.  Here are some opinions, all
  2118.         of which refer to user code; the GNO kernel treats pathnames
  2119.         the same way that GS/OS does:
  2120.  
  2121.         - the ':' character should be mapped to '/'.  This prohibits
  2122.           the use of '/' in _file_ names.  It also provides the
  2123.           highest degree of "UNIX compatibility"; or
  2124.  
  2125.         - the '/' character should be mapped to ':'.  This is more
  2126.           in line with GS/OS, but can require extensive rewrites
  2127.           of ported UNIX programs; or
  2128.  
  2129.         - use dynamic directory delimiters.  The ':' character is
  2130.           always considered to be a directory separator.  The '/'
  2131.           character is considered to be a directory separator unless
  2132.           it was preceded at some point by a ':', in which case it
  2133.           is part of the file name.  Having a '/' appear before ':'
  2134.           in a pathname is illegal.  This is the closest to GS/OS,
  2135.           but also has some problems  with POSIX compliance.  For
  2136.           example, the PATH environment variable is _supposed_ to
  2137.           be a list of pathnames delimited by the ':' character.
  2138.           This implies that one cannot use the ':' as a directory
  2139.           delimiter when defining PATH, and that directories in
  2140.           PATH must not contain '/' as a regular character.
  2141.  
  2142.         Regardless of which method you use to do filename, pathname,
  2143.         and directory separator mapping, you should verify that
  2144.         the pathname is legal for your target filesystem.  GS/OS
  2145.         provides a mechanism to do this through the JudgeName
  2146.         system call.
  2147.  
  2148.         Also watch out for references to the root partition.  For
  2149.         other UNIXs, this is the pathname "/", which is a not legal
  2150.         directory under GS/OS (and therefore GNO).  Hopefully the
  2151.         context of your program will give you an idea how to handle
  2152.         such a directory reference in a sensible manner.
  2153.  
  2154.     unlink
  2155.         Many UNIX programs unlink (delete) files while they still
  2156.         have them open.  Under true UNIX systems, this means that
  2157.         the file will be deleted as soon as it is closed.  This is
  2158.         is not done under GNO, and attempting to unlink an open file
  2159.         will fail, and the file will remain on the file system after
  2160.         it is closed.  If your program relies on this behavior, you
  2161.         will have to find a work-around.  One partial solution is
  2162.         to register a clean-up function via atexit(3) that deletes
  2163.         your files for you.  [This method is not suitable for 
  2164.         daemons or other long-running programs.]
  2165.  
  2166. Q#9.3:    Are there any other recommendations for porting programs?
  2167.  
  2168. A#9.3:    There probably are as many opinions as there are programmers.
  2169.     However, here is a list that seems to work well.  Using C as
  2170.     the source language is assumed:
  2171.  
  2172.     - Use the occ(1) "-w" flag (#pragma lint -1) whenever possible.
  2173.       You will have to modify your code if it doesn't use prototypes,
  2174.       but this is more likely to catch errors and incorrect assumptions.
  2175.       If you really need to be compatible with K&R compilers, you
  2176.       can use the following paradigm in your code:
  2177.  
  2178.         #include <sys/cdefs.h>
  2179.         int main __P((int argc, char **argv));
  2180.  
  2181.         int main
  2182.         #ifdef __STDC__
  2183.         (int argc, char **argv)
  2184.         #else
  2185.         (argc, argv)
  2186.         #endif
  2187.             int argc;
  2188.             char **argv;
  2189.         {
  2190.             ...
  2191.  
  2192.       You may have to prototype some of your system header files.
  2193.       This should not be necessary with the ORCA/C v2.1 header files
  2194.       (they're already prototyped), but is likely necessary with
  2195.       earlier versions and some of the GNO v2.0.4 (and earlier) system
  2196.       header files.  See also Q#6.2 and Q#6.6.
  2197.  
  2198.     - Whenever possible, compile with the occ(1) "-G25" during
  2199.       development.  This will ensure that, in the event of stack
  2200.       trashing and similar problems, that you get a meaningful
  2201.       traceback and that your machine (usually) doesn't crash.
  2202.  
  2203.       If you are using the Splat! debugger, you should use "-g" instead
  2204.       of "-G25".  See also the notes on fork(2) in question Q#9.2.
  2205.  
  2206.       Make sure you read the both the ORCA/C manual and release notes;
  2207.       there are times (such as within variadic functions) that you
  2208.       cannot use stack checking or repair code.
  2209.  
  2210.       When you're finished development, you can replace the debugging
  2211.       flag with "-O" for optimization.  Don't forget to test your
  2212.       optimized program before you release it!
  2213.     
  2214. Compiling
  2215. ---------
  2216.  
  2217. Q#10.1:    Which language should I use?
  2218.  
  2219. A#10.1:    Since GNO is not language-specific, it doesn't really matter.
  2220.  
  2221.     From a practical stand point though, either assembly or C tend
  2222.     to be the languages of choice.  Both have their strengths and
  2223.     weaknesses.  Assembly can be more efficient but in general requires
  2224.     more time to program and more attention to detail.  Much of the
  2225.     available UNIX source code is in C. Using C can result in a quicker
  2226.     development cycle and more portable code, but it often results in
  2227.     a slower program.
  2228.  
  2229.     A big part of the decision is dependent on which language you
  2230.     already know.  If you are comfortable in one, stick with it
  2231.     until you need to try something else.  If you know neither,
  2232.     then the decision becomes religious -- ie: there is no correct
  2233.     answer, and the response you get will depend on whom you ask.
  2234.  
  2235.     Some people have also successfully used Pascal for GNO
  2236.     programming, although it is not as suited to GNO as is C or
  2237.     assembly.
  2238.  
  2239.     If you program in C, the only realistic choice for a compiler
  2240.     is Byte Works' ORCA/C.  As of v2.1.0, it is relatively bug free
  2241.     and close to ANSI-compliant.
  2242.  
  2243.     If you program in assembler, Byte Works' ORCA/M is recommended.
  2244.     Merlin-8/16 (by Roger Wagner) is also reputed to be suitable
  2245.     (although not as common).
  2246.  
  2247. Q#10.2:    Should I purchase the ORCA Subroutine Library Source?
  2248.  
  2249. A#10.2:    The sources are not required, but they are recommended.  Some
  2250.     reasons are:
  2251.         - they allow you to see how a function is implemented
  2252.         - they allow you to investigate possible library bugs
  2253.         - they are good examples of assembly programming
  2254.         - they are inexpensive
  2255.  
  2256. Q#10.3:    What is occ?
  2257.  
  2258. A#10.3:    occ is a front end to ORCA/C written by Soenke Behrens.  It makes
  2259.     ORCA/C's invocation more "UNIX-ish" and is the recommended
  2260.     interface between dmake(1) and ORCA/C.
  2261.  
  2262. Q#10.4:    What is dmake?
  2263.  
  2264. A#10.4:    dmake is a variation of the UNIX "make" facility.  It is used
  2265.     on large software projects for defining when and how files should
  2266.     be updated (typically compiled or linked), based on dependency
  2267.     lists.  It's behavior is controlled through the use of a 
  2268.     "makefile" (sometimes "makefile.mk"), which is a text file
  2269.     defining dependency graphs, rules, and actions.
  2270.  
  2271.     After definition of the makefile, a project can often be built
  2272.     (perhaps tested and installed as well) just by typing "dmake",
  2273.     assuming there are no compilation or other errors.  Only the
  2274.     work that is required will be done.
  2275.  
  2276.     For more details, see the dmake(1) man page.
  2277.  
  2278. Q#10.5:    What macros should I be using for conditional compilation?
  2279.  
  2280. A#10.5:    There are four general areas where certain "standard" macros
  2281.     are used ("standard" is quoted because only those explicitly
  2282.     annotated correspond to ISO/ANSI or other standards).  Where
  2283.     the macros aren't predefined by current compilers, they should
  2284.     be defined in source, header, or makefiles when necessary:
  2285.  
  2286.     - Architecture:
  2287.         These macros tend to be lower case with double leading-
  2288.         or trailing-underscores, such as "__sun4__" or "__parisc__".
  2289.  
  2290.         No IIgs compilers currently predefine an architecture,
  2291.         but "__appleiigs__" is recommended for Apple IIgs
  2292.         specific code.
  2293.  
  2294.     - Operating System:
  2295.         These macros tend to be upper case and may or may not
  2296.         use underscores.  Examples are "_AIX" and "SunOS".
  2297.  
  2298.         No IIgs compilers currently predefine an os macro,
  2299.         but "__GNO__" is recommended for GNO-specific code.
  2300.  
  2301.     - Compiler:
  2302.         These macros tend to be upper case and may or may not
  2303.         use underscores.  Examples are "__LCC__" and "__GNUC__".
  2304.  
  2305.         ORCA/C predefines "__ORCAC__".  APW/C predefines "APW".
  2306.  
  2307.     - Language and other standards:
  2308.         The "__STDC__" macro may be used for determining ISO/ANSI C
  2309.         compliance.  It is the responsibility of the compiler to
  2310.         define (or not define) this macro appropriately.
  2311.  
  2312.         If "_POSIX_SOURCE" source is defined, the source may
  2313.         be written with the assumption that all symbols defined
  2314.         by POSIX Standard 1003.1 are available in the environment.
  2315.         This symbol is expected to be defined by the user as
  2316.         necessary.  GNO isn't yet POSIX compliant, but it's getting
  2317.         there.
  2318.  
  2319.         If "_BSD_SOURCE" is defined, all symbols are expected to
  2320.         be 4.3BSD compliant.  This implies "_POSIX_SOURCE".  Again,
  2321.         GNO isn't there yet but it's progressing.
  2322.  
  2323.         "KERNEL" is defined when building the GNO kernel.  You will
  2324.         see this macro in the GNO header files, but you should not
  2325.         define it.
  2326.  
  2327.         "__cplusplus" is predefined by C++ compilers, of which there
  2328.         are none for the IIgs.  It is the responsibility of the
  2329.         compiler to define (or not define) this macro appropriately.
  2330.         Explanation of this macro was given since you occasionally
  2331.         see it in GNO header files ...
  2332.  
  2333.     Other macros are defined either by the compiler or in header files,
  2334.     but these are the main ones for user code conditional compilation.
  2335.     See the relevant documentation (compiler manual, ISO/ANSI or POSIX
  2336.     standards, GS/OS reference manual) for more details.
  2337.  
  2338. Q#10.6:    When I'm using the new header files (post-v2.0.4), sometimes ORCA/C
  2339.     can't find my header files.  Why?
  2340.  
  2341. A#10.6:    There are a few potential causes for this problem, some of which
  2342.     are not completely understood.  You should try the following
  2343.     steps:
  2344.  
  2345.     1.  Ensure that the correct "#pragma path" values are in your
  2346.         13/orcacdefs/defaults.h file (see Q#6.5).
  2347.  
  2348.     2.  Ensure that all of your header files are of type SRC and
  2349.         auxiliary type CC.  This includes headers in the directories
  2350.         specified via "#pragma path" in 13/orcacdefs/defaults.h
  2351.         (see Q#6.5), any directories specified by the occ(1) "-I"
  2352.         flag, and your current directory.
  2353.  
  2354.     3.  Remove any *.sym files you have and try compiling with the
  2355.         occ "-i" flag.  This has been reported to eliminate the
  2356.         problem; presumbably there is an out-of-date cache being
  2357.         used in the precompiled header file.
  2358.  
  2359.         If you are using dmake, you can add "-i" to your default
  2360.         CFLAGS environment variable in /usr/local/lib/startup.mk.
  2361.  
  2362.         If you use neither dmake nor occ, you can add "#pragma ignore"
  2363.         to your 13/orcacdefs/defaults.h file.
  2364.  
  2365.     4.  If your problem is intermittent, try calling the purge(1)
  2366.         command when the problem occurs.
  2367.  
  2368. Libraries and Header Files
  2369. --------------------------
  2370.  
  2371. Q#11.1:    I keep getting "va_end" as an unresolved symbol when linking.  Why?
  2372.  
  2373. A#11.1:    You should only be seeing this if you are trying to use the
  2374.     ORCA/C v2.1.x libraries with GNO v2.0.4.  (See Q#6.1 and Q#6.8).
  2375.  
  2376.     The GNO v2.0.4 libraries were compiled with a version of ORCA/C 
  2377.     that still used a function version of va_end(3).  ORCA/C now
  2378.     correctly defines va_end(3) as a macro.  
  2379.  
  2380.     If you attempt to use a variadic function from the GNO v2.0.4
  2381.     libraries (such as open(2)), then you will get an unresolved
  2382.     va_end reference.  To solve this problem, download and install
  2383.     the archive "vaendPatch.shk", available from ground or caltech.
  2384.  
  2385. Q#11.2:    Why do I keep getting "getc" and "putc" as unresolved symbols
  2386.     when linking?
  2387.  
  2388. A#11.2:    This is an indication that the files 13/OrcaLib, 13/SysFloat,
  2389.     and 13/SysLib are not properly matched.  You cannot mix these
  2390.     files from different versions of ORCA/C.  The OrcaLib shipped
  2391.     with GNO can only be used with particular versions of the other
  2392.     two libraries.  You should (re)read the section in this FAQ on
  2393.     "Installing GNO with ORCA".
  2394.  
  2395. Q#11.3:    How can I tell what order my libraries are in?
  2396.  
  2397. A#11.3:    Try the command 'ls -1n' or 'ls -ln'.
  2398.  
  2399. Q#11.4:    How can I sort my libraries (or other files)?
  2400.  
  2401. A#11.4:    This isn't really a GNO question, but it's included here because
  2402.     of its relevance to Q#11.3 and the section on "Installing GNO with
  2403.     ORCA".
  2404.  
  2405.     For ProDOS Partitions:
  2406.         There are various ways to do this.  One of the easiest is to
  2407.         use ProSEL or another utility which sorts directory entries
  2408.         (such as the ORCA/Shell compress command -- *don't* confuse
  2409.         this with the GNO compress(1) command).
  2410.  
  2411.         If you do not have a utility that does this, you can do it
  2412.         manually by moving all the files into another (scratch)
  2413.         directory, then moving them back one at a time in the order
  2414.         in which you wish them to appear.
  2415.  
  2416.     For HFS Partitions:
  2417.         The files in a given directory on HFS partitions are always
  2418.         sorted by name, case insensitive.  You can change the sequence
  2419.         in the directory only be changing the names of the files
  2420.         involved.
  2421.  
  2422.         Specific to GNO installations, if your /lib directory resides
  2423.         on an HFS volume, you should rename /lib/libc to /lib/nlibc.
  2424.  
  2425. Q#11.5:    How can I tell what is in library XXXX?
  2426.  
  2427. A#11.5:    The only way to tell for sure what is in a library is to
  2428.     look at the symbol table.  The most common way to do this
  2429.     is to get a listing by using Byte Works' makelib(1) utility,
  2430.     which comes with their various language packages (see the -D
  2431.     and -F flags).
  2432.  
  2433.     There is also a program available, listlib(1), which is a
  2434.     front end to makelib.  It provides the same information as
  2435.     makelib, but in an alternate format more suited to cross
  2436.     referencing symbols to the files containing them.
  2437.  
  2438.     Of course, knowing what symbols are _in_ a library doesn't help
  2439.     unless one knows _what_ the symbols are for.  Every library should
  2440.     have at least one header (*.h) file.  This tells the compiler
  2441.     the type, size, and other important information for each symbol.
  2442.  
  2443.     Header files, however, are intended for the compiler.  A good
  2444.     library should come with documentation, preferably manual pages
  2445.     (see Q#3.4, Q#3.5, and Q#3.6).
  2446.  
  2447.     If documentation isn't available and the symbols appear to be
  2448.     common UNIX symbols, then try reading a manual page from any
  2449.     available UNIX box.  It might not be right, but it may give you
  2450.     a start.  Next try posting a question to comp.sys.apple2.gno.
  2451.     Perhaps you will be able to contact the author (not likely if there
  2452.     wasn't any documentation).  When all else fails, there's always
  2453.     disassembly of the object files ...
  2454.  
  2455. Q#11.6:    Why isn't the common function XXXX in the libraries?
  2456.  
  2457. A#11.6:    The GNO libraries are still undergoing active development.  If you
  2458.     find that a standard or common routine is missing, then contact
  2459.     Devin Reade <gdr@eddore.myrias.com> who is currently the primary
  2460.     maintainer of the GNO libc.
  2461.     
  2462.     If the function is not yet in libc you are requested to contribute
  2463.     an implementation and a man page, preferably in nroff(1) source
  2464.     (see Q#3.5).  Distributing the work results in faster updates.
  2465.  
  2466. Q#11.7:    Function XXXX is declared in the GNO header files, but it's not in
  2467.     the libraries.  Why?
  2468.  
  2469. A#11.7:    Just because a function is declared, that doesn't necessarily mean
  2470.     that it's been implemented.  However, it is useful to keep those
  2471.     declarations in the system header files.  Not only does it minimize
  2472.     namespace conflicts with user code (application programmers are
  2473.     less likely to use function names that conflict with system header
  2474.     files), but it ensures that the interface is defined for anyone
  2475.     who wishes to contribute an implementation.  Declaring those
  2476.     functions early also minimizes updates to the system header files
  2477.     as the function implementations are added.
  2478.  
  2479.     See also Q#11.6.
  2480.  
  2481. Q#11.8:    I want to release my library to the GNO community.  Is there anything
  2482.     in particular that I should do?
  2483.  
  2484. A#11.8:    Here's a checklist:
  2485.  
  2486.     - Any symbols which should not be available to the user should
  2487.       have their private flag set.  In C, this corresponds to using
  2488.       the "static" storage class specifier whenever possible.
  2489.  
  2490.     - Ensure your library is compatible with ORCA/C's large memory
  2491.       model.
  2492.  
  2493.     - Write documentation, preferably one or more manual pages, for
  2494.       any exported symbols.  If your library uses configuration files,
  2495.       write manual pages for those too (they belong in chapter 5).
  2496.  
  2497.     - Specify in the manual pages any dependency on non-standard
  2498.       libraries.  Specify dependencies for all header files, whether
  2499.       standard or not.
  2500.  
  2501.     - Consider including your source code with your library.  This
  2502.       allows your contribution to survive even if your hard drive
  2503.       crashes, your backups are destroyed, or you leave the GNO
  2504.       community.
  2505.  
  2506. Q#11.9:    How do I get the file descriptor from a stdio FILE pointer?
  2507.  
  2508. A#11.9:    Use the fileno() macro.
  2509.  
  2510.     This is defined in <stdio.h> as of GNO v2.0.6.  For earlier
  2511.     versions you will have to add it in yourself.  The proper
  2512.     macro definition for the ORCA/C headers is:
  2513.  
  2514.         #define fileno(p) ((p)->_file)
  2515.  
  2516. Q#11.10:    My (ported) source requires <sys/file.h>.  Why isn't it there?
  2517.  
  2518. A#11.10:    <sys/file.h> has been superceded by <sys/fcntl.h>.  Update your
  2519.     sources.
  2520.  
  2521. Q#11.11:    Why, when I '#include <types.h>' (or some other file), does the
  2522.     compiler take it out of my current directory instead of out of
  2523.     the system header directories?
  2524.  
  2525. A#11.11:    This is an unfortunate side-effect of using the ORCA/C "path"
  2526.     pragma to avoid duplication of system header files between your
  2527.     GNO and ORCA installations.  (See Q#5.1, Q#6.1, Q#6.4, and
  2528.     Q#6.5.)
  2529.  
  2530.     The reason for the problem is that when the file is included
  2531.     with the angle bracket syntax (vice double quotes), ORCA/C 
  2532.     will still search the current directory before those specified
  2533.     by the "path" pragma.
  2534.  
  2535.     At this time, the only known work-around is to avoid, in your
  2536.     own sources, using file names used by the system header files.
  2537.  
  2538. Q#11.12:    When using the December 1997 libraries (or later version), why are
  2539.     my programs larger than they used to be?
  2540.  
  2541. A#11.12:    There are a few reasons for this.
  2542.  
  2543.     The first one is that when the libraries (which are mostly written
  2544.     in C) are compiled, aggressive optimizations are not currently used.
  2545.     This is because certain optimizations in ORCA/C are known to be
  2546.     broken.  This, combined with the fact that we are missing a lot
  2547.     of automated test suites for the GNO (non-ORCA/C) additions to the
  2548.     libraries, indicated that it would be best to ship the libraries
  2549.     without much in the way of optimizations.
  2550.  
  2551.     The second reason is probably more significant.  When Jawaid provided
  2552.     a libc and ORCALib for GNO v2.0.4, he made significant changes to
  2553.     the stdio portion of ORCALib so that it would work with pipes and
  2554.     sockets.  Unfortunately, for whatever reason, the two versions of
  2555.     ORCALib (the original version from Byte Works, and the modified 
  2556.     version from Procyon) were never merged.  Therefore, when ORCALib
  2557.     was updated for ORCA/C v2.1.x, the GNO-specific changes were 
  2558.     effectively lost.
  2559.  
  2560.     When Devin took over maintenance of the GNO libraries in the spring
  2561.     of 1997, he was (in order to get a stdio package that worked with
  2562.     pipes) faced with the choice of either reimplementing Jawaid's
  2563.     changes to stdio, or to use another implementation of stdio that
  2564.     was written with pipes in mind.
  2565.  
  2566.     The tradeoff is one of development time versus code size (and probably
  2567.     speed).  The ORCA stdio implementation is in assembly, so it is
  2568.     small and fast.  On the other hand, GNO v2.0.6 had been in the
  2569.     "it's not ready yet" stage for quite a while.  The choice was made
  2570.     to use the 4.4BSD stdio implementation.  This is the primary reason
  2571.     why programs which use stdio are now larger than they were.
  2572.  
  2573.     If your program does not use stdio, but is still significantly 
  2574.     larger, then it may be due to dependancies in libc; there are
  2575.     some routines which currently depend on stdio but which need not.
  2576.     These dependancies will be removed as time is available to do so.
  2577.  
  2578. Kernel Internals
  2579. ----------------
  2580.  
  2581. Q#12.1:    Can task-switching occur during an interrupt?
  2582.  
  2583. A#12.1:    No.
  2584.  
  2585. Q#12.2:    Can I tell GNO/ME to not task switch during a short (like a couple
  2586.     of ASM instructions) sequence?
  2587.  
  2588. A#12.2:    Turn off interrupts, or increment the busy flag around the code.
  2589.  
  2590. Debugging (During Program Development)
  2591. --------------------------------------
  2592.  
  2593. Q#13.1:    What debuggers are available for GNO?
  2594.  
  2595. A#13.1:    There are no GNO-specific debuggers, however there are at least two 
  2596.     popular ones that are compatible with GNO.
  2597.  
  2598.     If you are programming in C, it is highly recommended that you
  2599.     purchase "Splat!", written by Michael Hackett of Some Assembly
  2600.     Required.  This is also available from Procyon.  See also Q#13.2.
  2601.  
  2602.     If you are programming in assembly, it is recommended that you
  2603.     install GSBug.  This comes bundled with ORCA/M and is also available
  2604.     for download from the Apple Inc dts ftp site.  GSBug has many
  2605.     add-on packages used to increase its functionality.  Two of these
  2606.     are Niftylist and Nexus.
  2607.  
  2608. Q#13.2:    Why is the Splat! debugger crashing when my code calls fork(2)?
  2609.  
  2610. A#13.2:    Splat was not originally designed for GNO.  When GNO does a fork(2)
  2611.     or fork2(2) call, some very non-standard things are happening in
  2612.     the IIgs execution environment.  Splat cannot currently handle
  2613.     these operations.
  2614.  
  2615.     A request has been submitted to the author of Splat! for an upgrade
  2616.     to handle this behavior but he has not yet had time to do it; he
  2617.     is also busy working on other IIgs projects.
  2618.  
  2619. Q#13.3:    Part way through my debugging session, Splat! no longer shows my
  2620.     source file.  Why?
  2621.  
  2622. A#13.3:    Your program is probably changing its current working directory.
  2623.  
  2624.     The C preprocessor inserts tokens that tell the compiler which
  2625.     file (and on which line) it is currently processing.  This
  2626.     information is eventually passed to the debugger.  Some of the
  2627.     pathnames are, in general, relative to the directory from which
  2628.     your program was compiled.
  2629.  
  2630.     Splat! uses these relative pathnames to locate the source files
  2631.     that it is supposed to display.  Unfortunately, the current version
  2632.     of Splat! always searches for these files relative to the current
  2633.     directory, not relative to the directory that was current at the
  2634.     time which Splat! was invoked.  Therefore, if your program changes
  2635.     the current directory, the source files can no longer be found.
  2636.  
  2637.     This problem can be avoided by inserting following preprocessor
  2638.     directive at the top of all your source files:
  2639.         #line 1 "/fully/qualified/path/name.c"
  2640.     Of course, you should use the real path names to your source files,
  2641.     not the one shown above.  Do not use the __FILE__ macro as it
  2642.     will be expanded to only a partial pathname under some circumstances,
  2643.     such as when using occ(1).
  2644.  
  2645.     There is a utility which automates this process, including an
  2646.     option to remove the preprocessor directive.  See the splatprep(1)
  2647.     manual page for details.
  2648.  
  2649. General Problems
  2650. ----------------
  2651.  
  2652. Q#14.1:    Some programs I run have two cursors and sometimes characters I
  2653.         type don't get sent to the program. When I quit the program, the
  2654.         characters show up on the command line! What's wrong?
  2655.  
  2656. A#14.1:    You need to set the auxiliary file type of the program in question
  2657.     to $DC00.  Use the chtyp command:
  2658.  
  2659.             chtyp -a \$DC00 ProgramName
  2660.  
  2661.     Note the '\' character; it must be there to escape the '$' character
  2662.     from the shell, otherwise the $DC00 would be treated as a shell
  2663.     variable.
  2664.  
  2665.     Also note that this fix will not work if the program's file type
  2666.     is S16 and the file resides on an HFS volume.  (An EXE file on
  2667.     an HFS volume should be fine.)
  2668.  
  2669. Q#14.2:    Whenever I try to launch the Finder from GNO, I am told that the 
  2670.         Finder needs more memory. I know there is enough memory available.
  2671.         What's the deal?
  2672.  
  2673. A#14.2:    This was a bug in the GNO 1.0 kernel. Unfortunately, there is no
  2674.     workaround.  The only option is to upgrade to a current version
  2675.     of GNO.
  2676.  
  2677. Q#14.3:    My program is crashing when calling open(2).  Why?
  2678.  
  2679. A#14.3:    It may be due to a prototype/library mismatch.  The GNO implementation
  2680.     of open(2) is a variadic function.  The third "mode" parameter must
  2681.     be provided if and only if the second "oflag" parameter has the
  2682.     O_CREAT flag set.
  2683.  
  2684.     If calls to open result in a crash or stack error, you may have
  2685.     either the wrong definition of open in <fcntl.h>, or you are not
  2686.     getting open from 13/libc.  See also Q#9.2, Q#11.2, Q#11.3, and Q#6.6.
  2687.  
  2688. Q#14.4:    What are the known bugs?
  2689.  
  2690. A#14.4:    First off, this answer only refers to GNO-specific bugs.  You
  2691.     should also consult the ORCA/C bug list (see Q#9.2).
  2692.  
  2693.     As of mid-March 1998, there is an online bug tracking system
  2694.     for GNO.  You can get to it off of the GNO Documentation Page.
  2695.     Its direct URL is:
  2696.  
  2697.         http://www.gno.org/~gno/bugs.html
  2698.  
  2699.     If you know of specific problems with GNO that are not listed
  2700.     in the database, please enter them.  The web interface is the
  2701.     preferred method of submitting reports, but if that is not
  2702.     feasible you can also send bug reports to the following address:
  2703.  
  2704.         gno-bugs@trenco.gno.org
  2705.  
  2706.     If you do not have a web browser, you can view current reports
  2707.     by obtaining them through anonymous ftp at the following URL:
  2708.  
  2709.         ftp://ftp.gno.org/pub/gno-bugs
  2710.  
  2711.     You shouldn't archive these reports since they are continually
  2712.     being updated; view them and throw them away.
  2713.  
  2714.     *** The anon ftp directory has not yet been set up.
  2715. -- 
  2716. Tomorrow I will seven eagles see, a great comet will appear, and voices will
  2717. speak from whirlwinds foretelling monstrous and fearful things -- This 
  2718. Universe never did make sense; I suspect that it was built on government
  2719. contract.                        - Robert Heinlein
  2720.