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