Version: 1.2 Modified: 1997/02/05 06:09:13 This is the Frequently Asked Questions (FAQ) posting of the comp.sys.apple2.gno newsgroup. This document can be freely copied so long as 1. it is not sold (although it may be included in commercial distributions of Apple II archives such as the Golden Orchard CD series); and 2. any sections reposted elsewhere from it are credited back to this FAQ with the FAQ's copyright info and official WWW location left in place. Explicit permission is granted to carry this FAQ on electronic forums dealing with Apple II computers such as BBSs and service providers such as Genie. This FAQ is available via ftp and on the WWW at ftp://ftp.cs.ualberta.ca/pub/glyn/FAQs/comp.sys.apple2.gno http://web.cs.ualberta.ca/~glyn/FAQ.csa2g The FAQ was originally maintained by C. Matthew Curtin, , . It contains contributions (intentional or otherwise) from many users of GNO. The FAQ is currently maintained by Devin Reade, . Questions, comments, suggestions, and submissions to this FAQ are welcome and should be emailed to Devin Reade or posted to comp.sys.apple2.gno. The question numbers in this FAQ are auto-generated. Therefore, when referring to questions in this FAQ, please either give the version number of the FAQ or (preferably) give some context that identifies to which question you refer. This is an early version of the FAQ. Therefore, some questions have annotations starting with three asterisks ("***"). These are questions that are in the process of having their answers written. Table of Contents ================= General ^^^^^^^ Q#1: What is GNO? Q#2: Where can I get GNO? Q#3: What are GNO's miminum system requirements? Q#4: What is the current version of GNO? Q#5: I have an old of GNO. Can I get a newer version? Q#6: Where can I get the files/archives recommended in this FAQ? Q#7: Why is this FAQ written in such a drab format? Compatibility ^^^^^^^^^^^^^ Q#8: With what standard version of Unix is GNO compatible? Q#9: Is GNO compatible with the SecondSight VGA card? Q#10: Are desktop applications compatible with GNO? Q#11: Can I use prizm (the Orca desktop environment) with GNO? Q#12: What new features are expected to be in the next version (2.0.6)? Documentation ^^^^^^^^^^^^^ Q#13: What documentation comes with GNO? Q#14: What additional documentation is recommended for GNO? Q#15: What are all the numbers in parenthesis following program names? Q#16: I've just finished writing a new program (or library or whatever). What documentation should I include? Q#17: I'm writing a manual page. What format should I use? Q#18: What should be in a manual page? Q#19: Man(3) is too slow when formatting pages. Can I speed it up? Q#20: What are the standard manual page chapters? Programs ^^^^^^^^ Q#21: What other programs come with GNO? Q#22: Are there any ftp sites for GNO utilities? Q#23: I cannot ftp to caltech or ground. How can I get the GNO utilities? Q#24: What is the most recent version of program XXXXXX? Q#25: Which editor should I use? Networking ^^^^^^^^^^ Q#26: Does GNO provide TCP/IP and/or SLIP support? Q#27: What TCP/IP network utilities are available? Q#28: Is there a WWW browser for GNO and GS/TCP? System Configuration ^^^^^^^^^^^^^^^^^^^^ Q#29: What patches should I have applied for GNO? Q#30: How do I change the information that's printed before the login prompt? Q#31: How do I map /usr, /local, /var, and other partitions to GS/OS volume or directory names? Q#32: How do I set up cron? Porting UNIX Programs to the GNO Environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Q#33: What programs/utilities should I have to port UNIX source code to GNO? Q#34: What are the common problems encountered when porting UNIX source to GNO? Q#35: Are there any other recommendations for porting programs? Compiling ^^^^^^^^^ Q#36: Which language should I use? Q#37: How do I set up Orca/C so that I can use it with GNO? Q#38: Do I need separate installations of Orca/C for use with GNO and Orca/Shell? Q#39: Should I purchase the Orca Subroutine Library Source? Q#40: What is occ? Q#41: What is dmake? Q#42: What macros should I be using for conditional compilation? Libraries ^^^^^^^^^ Q#43: Can I use the Orca/C v2.1 libraries with GNO v2.0.4? Q#44: What libraries do I need when using GNO v2.0.4 with Orca/C v2.1? Q#45: What changes do I have to make to my header files? Q#46: How can I tell what order my libraries are in? Q#47: How can I tell what is in library XXXX? Q#48: Why isn't the common function XXXX in the libraries? Q#49: Function XXXX is declared in the GNO header files, but it's not in the libraries. Why? Q#50: I want to release my library to the GNO community. Is there anything in particular that I should do? Kernel Internals ^^^^^^^^^^^^^^^^ Q#51: Can task-switching occur during an interrupt? Q#52: Can I tell GNO/ME to not task switch during a short (like a couple of ASM instructions) sequence? Debugging (During Program Development) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Q#53: What debuggers are available for GNO? Q#54: Why is the Splat! debugger crashing when my code calls fork(2)? Q#55: Part way through my debugging session, Splat! no longer shows my source file. Why? General Problems ^^^^^^^^^^^^^^^^ Q#56: 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#57: 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#58: My program is crashing when calling open(2). Why? Q#59: What are the known bugs? General ------- Q#1: What is GNO? A#1: GNO is a Unix 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. This makes such things as attaching terminals to your GS, multiline BBSes, remote dial-ups, UUCP or SLIP that doesn't take over your computer, as well as countless other applications a possibility. Q#2: Where can I get GNO? A#2: See the Procyon Enterprises Inc web page at: http://www.hypermall.com/companies/procyon or contact them by snail-mail at: Procyon, Inc. P.O. Box 620334 Littleton, CO 80162-0334 303/933-4649 Q#3: What are GNO's miminum system requirements? A#3: GNO requires an Apple IIGS with 1.25 megs of memory and a 3.5" disk drive. Additional memory, an accelerator, and especially a hard drive are all recommended. Q#4: What is the current version of GNO? A#4: The currently released version is v2.0.4. The version currently under development is v2.0.6. v2.0.5 was never had a general release, and is not available. Q#5: I have an old of GNO. Can I get a newer version? A#5: Presumably this question means "do I have to pay full price?" This will depend on what the current version is, which version you own, and whether or not you are the registered owner (if not, then *why* do you have it?) First off, if you're not the registered owner, forget it. Buy a copy. If you bought a second-hand copy, Procyon needs a note from the original owner that the package (complete with the serialized disk) has changed hands. If you are the registered owner, then the cost of an upgrade will depend on how recent your old version is. If only a minor upgrade is required, the fee (if any) tends to be small. If it's a major revision change, then you could be looking at close to the original price. Q#6: Where can I get the files/archives recommended in this FAQ? A#6: GNO distribution files are only available through the purchase of GNO. See Q#2. 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 two main Apple II sites are ftp://apple2.caltech.edu/pub/apple2 ftp://ground.isca.uiowa.edu/apple2 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#7: Why is this FAQ written in such a drab format? A#7: 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#8: With what standard version of Unix is GNO compatible? A#8: 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. Q#9: Is GNO compatible with the SecondSight VGA card? A#9: 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#10: Are desktop applications compatible with GNO? A#10: In most cases, yes. However, GNO doesn't currently allow more than one desktop program to run concurrently, but it does let you run as many text applications as you like (and have memory for) with a desktop program. There is program (also available from Procyon), called Switchit!, 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 compatibile with GNO. Other (text based) processes running in the background continue to do so when Switchit! is active. Q#11: Can I use prizm (the Orca desktop environment) with GNO? A#11: 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#12: What new features are expected to be in the next version (2.0.6)? A#12: 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#13: What documentation comes with GNO? A#13: GNO/ME Overview Kernel Reference Manual Shell (gsh) User's Manual Manual Pages (some printed, all online) Q#14: What additional documentation is recommended for GNO? A#14: 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#15: What are all the numbers in parenthesis following program names? A#15: When you see something like "ls(1)" in the documentation, it refers to something called "ls" which is documented in Chapter 1 of the manual pages. Similarily, "select(2)" is refering to something called "select" which is documented in Chapter 2. To find out what the various chapters are for, type in the command man 4 intro substituting "4" for whichever chapter you wish to learn about. Q#16: I've just finished writing a new program (or library or whatever). What documentation should I include? A#16: 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#17). 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#24. 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#17: I'm writing a manual page. What format should I use? A#17: While man can handle both manually-edited preformatted pages and pages that are aroff source (created by AppleWorks-GS or a compatible editor), the recommended format is to use nroff source with tmac "an" extensions. The reason for this is that only nroff souce can be reformatted "on the fly" to suit different terminal characteristics. See also Q#19. Q#18: What should be in a manual page? A#18: 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 mandetory due to how some automated tools work. The sequence on the remainder are suggested: NAME - name and one line description SYNOPSIS - list of options and arguments DESCRIPTION - a detailed description OPTIONS - explanation of the flags ENVIRONMENT - relevent environment variables and their semantics, if appropriate FILES - related files, if appropriate BUGS - known bugs, if appropriate AUTHOR - your name and contact info, typically an email address. Include your smail address at your own risk. LEGALITIES - Commercial, freeware, shareware, public domain, copyleft, ... ? ATTRIBUTIONS - Give credit when due. For example, if your binary was linked with the Orca libraries, you should be including the Run-Time Licence from Appendix C of the Orca/C manual. SEE ALSO - related manual pages or other documents Q#19: Man(3) is too slow when formatting pages. Can I speed it up? A#19: Actually, it's not man(3), but nroff(3) which is slow. Nroff is in desparate 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#20: What are the standard manual page chapters? A#20: Chapter 1: Commands and Applications Chapter 2: System Calls Chapter 3: Library Routines Chapter 4: Devices Chapter 5: File Formats Chapter 6: Games Chapter 7: Miscellaneous Chapter 8: System Administration For GNO, there should be no need to use Chapter n [New Commands], or Chapter l (ell) [Local Commands], unless (in the latter case) the manual page is for something that is not to be released to the GNO community. Chapter 3F is reserved for Fortran Routines, of which there are none at this time (due to the lack of a publically available Fortran compiler). Programs -------- Q#21: What other programs come with GNO? A#21: 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#22: Are there any ftp sites for GNO utilities? A#22: Yes. Many Apple II ftp sites have GNO-specific directories, although GNO stuff can also be found in other directories on these sites. The two primary sites are: ftp://apple2.caltech.edu/pub/apple2/shellprogs ftp://ground.isca.uiowa.edu/apple2/apple16/gno See the comp.sys.apple2 FAQ for other Apple II ftp sites. Q#23: I cannot ftp to caltech or ground. How can I get the GNO utilities? A#23: 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#6). Q#24: What is the most recent version of program XXXXXX? A#24: 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 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#25: Which editor should I use? A#25: 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#56). Rose has been reported to work over a tty instead of just from the console. Networking ---------- Q#26: Does GNO provide TCP/IP and/or SLIP support? A#26: Most of the required kernel support is available in GNO v2.0.4, but it is not complete and there is nothing to take advantage of it. However, the remaining kernel support has been added to the upcoming version. Furthermore, GS/TCP is being developed by Derek Taubert. Extra information (including current status) on this project is available on the GS/TCP web page: http://www.winternet.com/~taubert/gstcp.html Q#27: What TCP/IP network utilities are available? A#27: 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#28: Is there a WWW browser for GNO and GS/TCP? A#28: 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. System Configuration -------------------- Q#29: What patches should I have applied for GNO? A#29: GUPP (Grand Unified Patch Program by Nathan Mates) is recommended for fixing a memory-trashing bug present in GNO kernel versions v2.0.4 and v2.0.6-beta (and probably earlier versions). GUPP also does other patches that may be applicable to programs running under GNO. Q#30: How do I change the information that's printed before the login prompt? A#30: 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#31: How do I map /usr, /local, /var, and other partitions to GS/OS volume or directory names? A#31: The kernel provides this functionality through the namespace facility, which is configured in /etc/namespace. See the Kernel Reference Manual for details. Q#32: How do I set up cron? A#32: There should be man page for this, but there doesn't seem to be one yet. (There should be a cron(8), crontab(1), and crontab(5).) First of all, I (Devin Reade) have never been able to get the current cron implementation to work reliably; it appears that the children of cron are unable to complete their execve. However, others have reported success, with the following notes: To activate cron, you must uncomment its entry in the /etc/inittab file. The the init(8) man page for the format of this file. Cron is controlled through the /etc/crontab file. Unlike its Unix counterparts, the GNO cron does *not* support setting of environment variables in the crontab file. These would be lines of the form: SHELL=/bin/sh MAILTO=gdr Any line which begins with a hash (#) character is considered to be a comment and is ignored. All other lines in this file are expected to have five space- delimited date/time fields, followed by a command. The first five fields are: minute (0-59) hour (0-23) day of month (0-31) month (0-11) day of week (0-6) Multiple values may be specified either separated by commas, or as a range separated with a hyphen. The last field is the 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. Porting UNIX Programs to the GNO Environment -------------------------------------------- Q#33: What programs/utilities should I have to port UNIX source code to GNO? A#33: 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#34: What are the common problems encountered when porting UNIX source to GNO? A#34: The first thing to watch for is known compiler and library bugs. Soenke Behrens maintains the current Orca/C bug report list. You should keep the contents of this list in mind when examining the target source code. The Orca/C bug report list may be found at http://www.arrowweb.com/sbehrens/obugs.htm This list has been considerably shorted since the release of Orca/C v2.1.0. If you have an earlier version of Orca/C, you should seriously consider an upgrade. The following items should be watched for, in no particular order. Since UNIX source is usually in C, that language is assumed for the rest of this section, where relevent: sizeof(int) The size of the type "int" is implementation-defined. While most modern C compilers use 32 bits, Orca/C still uses 16 bits since this is the "natural" integer size of the 65816. This also results in more effective code generation. While the size of an int shouldn't make a difference to any well-written code, there is some available source code that assumes that ints are 32 bits. You should watch for this in any code that does bit manipulations. You should also watch for code that freely converts between integers and pointers. GNU (Free Software Foundation) software is often bad for this. recursion When possible, recursion should be avoided when programming on the Apple IIgs. This is because recursion invariably causes stack growth and the stack can only exist in bank zero. This means that the maximum space available for the stack is 64k. In practise, it is much smaller. This problem is exacerbated under GNO where all processes must share the available stack space (each process has its own stack, though). Any program that uses recursion can be rewritten to use iteration instead. You should try to do this when possible. If you _do_ use recursion, don't allocate a huge stack; this will keep other programs from executing. Also, you should leave in stack checking and stack repair (if programming with Orca/C) to ensure that your recursion does not crash the machine if it goes too far. reference to absolute file descriptors True Unix machines invariably use the file descriptors 0, 1, and 2 for standard input, standard output, and standard error, respectively. Under GNO, the file descriptors used are 1, 2, and 3. This causes a problem when source code is written to use these descriptors directly. You should search your code for references to these descriptors, typically in calls to open, close, read, write, dup, dup2, and fcntl. Instead of replacing these digits with other digits though, you should use the macros STDIN_FILENO, STDOUT_FILENO, and STDERR_FILENO defined in . 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 address space. In this respect, GNO is less a multitasking environment than it is a multithreading environment. Search for calls to fork; you will have to rewrite these sections of code. See also the man page for fork2(2); it may be more suited to your purposes. Also note than when compiling routines that make a call to fork, you should turn off Orca/C's stack repair code. This means that you should be using an optimization level of at least 8. read/write of newline character Most Unix systems use LF (ASCII 0x0a) as the line delimiter. Both Apple II and Macintosh computers use CR (ASCII 0x0d) as the line delimiter. The C newline character is '\n'; ASCII 0x0a. While the stdio routines (fprintf(3), fread(3), etc) usually make this difference unnoticable by doing CR-->LF translation on input and LF-->CR translation on output, no such translation is done on files accessed through read(2) and write(2). Specifically, the GNO open(2) does not recognise the Orca/C O_BINARY bit in it's second argument. Therefore, if the program you are porting makes calls to read(2) and write(2), watch for the '\n' character in your code. You may have to change this to '\r'. Don't do it blindly, because many programs will use both stdio and operations on the bare file descriptors. One suggestion is to modify your programs low-level I/O routines to modify the I/O buffer prior to calling write(2) and after calling read(3). 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 , then you probably don't need to modify your application. If, on the other hand, your application is using its own constants for the mode parameter, you should convert it to use the standard macros. Failure to do so may result in files with strange GS/OS flags set, or file tests failing in your program. /dev One of the Unix philosophies is that "everything is a file". The /dev directory on Unix systems contain device special files. Accessing these files is the way to access the relevent hardware. For GNO programs, you should not access devices in the /dev directory. For example, opening "/dev/console" for writing will not have the expected effect. Instead you should open the corresponding GS/OS device, ".ttyco". The portable (and suggested) method of handling these cases is not to change the value of the string (in this example) from "/dev/console" to ".ttyco". Instead, use the macros defined in the file . 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 file contains macros for various standard paths. The macros, instead of the actual paths, should be used to maximize portability. signal handlers When a signal handler is called, the data bank register may not have an expected value. If your program references global scalars, it may crash. To avoid this, all functions used as signal handlers should have their definition preceeded by #pragma databank 1 and followed by #pragma databank 0 validity of pathnames Most programs make assumptions about what constitutes a valid file name. For most modern Unices, a valid file name follows the POSIX portable filename character set: The characters a-z and A-Z, the digits 0-9, and '.', '_', and '-'. The '-' is not used as the first character of a file name, and '/' is the directory separator character. The maximum filename length is at least 14 characters, and the maximum pathname length is at least 255 characters. Now this is different from what is available under GNO. The ProDOS FST provides only a subset of the above. The HFS FST provides a superset, but HFS is too slow, too buggy, and too unmaintainable for many users. The problem is also compounded by the fact that under GS/OS, the ':' is a directory separator. '/' may be used but it is mapped internally to ':'. Unfortunately, there is no general concensus on how to handle pathnames under GNO. Here are some opinions, all of which refer to user code; the GNO kernel treats pathnames the same way that GS/OS does: - the ':' character should be mapped to '/'. This prohibits the use of '/' in _file_ names. It also provides the highest degree of "Unix compatibility"; or - the '/' character should be mapped to ':'. This is more in line with GS/OS, but can require extensive rewrites of ported Unix programs; or - use dynamic directory delimiters. The ':' character is always considered to be a directory separator. The '/' character is considered to be a directory separator unless ':' is present, in which case it is part of the file name. This is the closest to GS/OS, but also has some problems with POSIX compliance. For example, the PATH environment variable is _supposed_ to a list of pathnames delimited by the ':' 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. Q#35: Are there any other recommendations for porting programs? A#35: 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 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#45. - 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#34. 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#36: Which language should I use? A#36: Since GNO is not language-specific, it doesn't really matter. From a practical stand point though, either assembly or C tend to be the languages of choice. Both have their strengths and weaknesses. Assembly can be more efficient but in general requires more time to program and more attention to detail. Much of the available Unix source code is in C. Using C can result in a quicker development cycle and more portable code, but it often results in a slower program. A big part of the decision is dependant on which language you already know. If you are comfortable in one, stick with it until you need to try something else. If you know neither, then the decision becomes religious -- ie: there is no correct answer, and the response you get will depend on whom you ask. Some people have also successfully used Pascal for GNO programming, although it is not as suited to GNO as is C or assembly. If you program in C, the only realistic choice for a compiler is Byteworks' Orca/C. As of v2.1.0, it is relatively bug free and close to ANSI-compilant. If you program in assembler, Byteworks' Orca/M is recommended. Merlin-8/16 (by Roger Wagner) is also reputed to be suitable (although not as common). Q#37: How do I set up Orca/C so that I can use it with GNO? A#37: There are a few aspects to this, some of which are dealt with in other questions. First, if you plan to still use Orca/Shell at all (critical if you're going to submit bug reports to ByteWorks), you need to duplicate part of your distribution. See Q#38. After you've duplicated your libraries and header files, you will need to replace or modify some header and libraries. See Q#43, Q#44, Q#45, and Q#46. If you're using an older version of Orca/C, you should prototype your headers. Using prototyped headers and #pragma lint -1 can catch a lot of bugs, both in user code and in the compiler. There are probably some programs you have in your Orca distribution that you would like to run under GNO. I recommend leaving prefix 17 set to your where you keep your Orca binaries (by default, the "Utilities" directory in the Orca distribution), then placing prefix 17 in your PATH environment variable. This way you can keep your Orca binaries separate from the GNO ones (which would be in /bin, /usr/bin, /usr/local/bin, and so forth). gsh doesn't parse the 15/login file, so be sure to set up your prefixes in your ~/gshrc file, as they are expected by the compiler. 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" Q#38: Do I need separate installations of Orca/C for use with GNO and Orca/Shell? A#38: At least partly, yes. GNO requires modifications to some header files and libraries, as well as the additions of others that don't come with Orca/C. The easiest way to do this is to have separate directories for prefix 13/ (which contains both libraries and the header file directory, 13/OrcaCDefs) when running GNO or Orca/Shell. Having a completely separate distribution (duplicating more than just the 13/ directory) can be helpful when reporting bugs in Orca products, but it is not required as long as you can demonstrate that the bug exists in a "bare" installation of Orca. Q#39: Should I purchase the Orca Subroutine Library Source? A#39: 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#40: What is occ? A#40: 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#41: What is dmake? A#41: dmake is a variation of the Unix "make" facility. It is used on large software projects for defining when and how files should be updated (typically compiled or linked), based on dependancy lists. It's behavior is controlled through the use of a "makefile" (sometimes "makefile.mk"), which is a text file defining dependancy graphs, rules, and actions. After definition of the makefile, a project can often be built (perhaps tested and installed as well) just by typing "dmake", assuming there are no compilation or other errors. Only the work that is required will be done. For more details, see the dmake(1) man page. Q#42: What macros should I be using for conditional compilation? A#42: There are four general areas where certain "standard" macros are used ("standard" is quoted because only those explicity annotated correspond to ISO/ANSI or other standards). Where the macros aren't predefined by current compilers, they should be defined in source, header, or makefiles when necessary: - Architecture: These macros tend to be lower case with double leading- or trailing-underscores, such as "__sun4__" or "__parisc__". No IIgs compilers currently predefine an architecture, but "__appleiigs__" is recommended for Apple IIgs specific code. - Operating System: These macros tend to be upper case and may or may not use underscores. Examples are "_AIX" and "SunOS". No IIgs compilers currently predefine an os macro, but "__GNO__" is recommended for GNO-specific code. - Compiler: These macros tend to be upper case and may or may not use underscores. Examples are "__LCC__" and "__GNUC__". Orca/C predefines "__ORCAC__". APW/C predefines "APW". - Language and other standards: The "__STDC__" macro may be used for determining ISO/ANSI C compliance. It is the responsibility of the compiler to define (or not define) this macro appropriately. If "_POSIX_SOURCE" source is defined, the source may be written with the assumption that all symbols defined by POSIX Standard 1003.1 are available in the environment. This symbol is expected to be defined by the user as necessary. GNO isn't yet POSIX compliant, but it's getting there. If "_BSD_SOURCE" is defined, all symbols are expected to be 4.3BSD compliant. This implies "_POSIX_SOURCE". Again, GNO isn't there yet but it's progressing. "KERNEL" is defined when building the GNO kernel. You will see this macro in the GNO header files, but you should not define it. "__cplusplus" is predefined by C++ compilers, of which there are none for the IIgs. It is the responsibility of the compiler to define (or not define) this macro appropriately. Explanation of this macro was given since you occasionally see it in GNO header files ... Other macros are defined either by the compiler or in header files, but these are the main ones for user code conditional compilation. See the relevent documentation (compiler manual, ISO/ANSI or POSIX standards, GS/OS ref manual) for more details. Libraries --------- Q#43: Can I use the Orca/C v2.1 libraries with GNO v2.0.4? A#43: Yes, with two caveats. 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, 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. The second problems is that the Byteworks' version of OrcaLib does not have support for named pipes. See also the note for Q#44. Q#44: What libraries do I need when using GNO v2.0.4 with Orca/C v2.1? A#44: Assuming that you have your 13/ prefix set to /lib, the following files are required, and are the standard distribution. They _must_ appear in the sequence given: /lib/lcrypt (GNO v2.0.1) /lib/libc (GNO v2.0.4) /lib/lregexp (GNO v2.0.1) /lib/lstring (GNO v2.0.1) /lib/ltermcap (GNO v2.0.1) /lib/OrcaLib (see *NOTE) /lib/PasLib (Orca/C v2.1, required iff you use Orca Pascal) /lib/SysFloat (Orca/C v2.1) /lib/SysLib (Orca/C v2.1) *NOTE: The Orca/C v2.1 version of OrcaLib may be used with GNO v2.0.4 provided that 1. You don't use named pipes; and 2. You do the va_end fix described in Q#43 If you require named pipes, you can try the GNO-specific OrcaLib that shipped with GNO v2.0.1, but you will not get any of the Byteworks bug fixes. Also, it has been reported that the GNO modifications introduced stdio bugs that weren't in the original version (no details available). The following libraries are recommended, in which case they should be kept in a separate directory such as /usr/lib. The sequence here is not important as they will be read in the order specified on the command line: /usr/lib/lflex This provides a main() routine suitable for a flex(3) 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#45: What changes do I have to make to my header files? A#45: There are two sets of notes here. One is for GNO v2.0.4 with Orca/C v2.0.x. The other is for GNO v2.0.6 with Orca/C v2.1.x. There are currently no notes on header changes with GNO v2.0.4 and Orca/C v2.1.x; you will have to do a manual merge. I would recommend starting with the Orca/C headers, then replace anything that conflicts with the GNO v2.0.1-2.0.4 headers with the GNO version. Specifically watch for structure changes, return types, and argument types. *** These notes are likely incomplete. If anyone has suggestions, please forward them. CHANGES FOR GNO v2.0.4 with ORCA/C v2.0.x ========================================= There are various header files included with GNO distributions v2.0.1 through v2.0.4. These should all be applied, in sequence. (Versions 2.0.2, 2.0.3, and 2.0.4 were incremental changes, not complete distributions.) After these files have been used to overwrite their (Orca/C v2.0.x) counterparts, the following files should be modified by hand. Note that there was a critical change to struct dirent in as of GNO v2.0.4. See the release notes for details. The prototypes for lseek(2), read(2), and write(2) have changed. They should be: off_t lseek(int, off_t, int); ssize_t read(int, void *, size_t); ssize_t write(int, void *, size_t); Previous notes have specified a return type for the latter two of size_t, however the return type must be able to hold a value of -1. The lseek prototype also appears in . Ensure it matches. CHANGES FOR GNO v2.0.6 ====================== If you're using Orca/C v2.1.0 or later, there are additions which should be added to your 13/orcacdefs/defaults.h file. See the GNO distribution for details. The contents of the shipped defaults.h file should be added to any copy you currently have; it does not replace it. The following Orca header files are modified: setjmp.h (size of jmp_buf changed to 6 from 4) The following Orca header files are completely replaced: time.h (important: time_t has changed) The following files are provided by the GNO distribution: *** to be added NOTE NOTE NOTE: This isn't GNO-specific, but the stdio FILE structure has changed as of Orca/C v2.1.1b2. If you're using that or a later version, be sure to delete relevent object and library files and recompile. Q#46: How can I tell what order my libraries are in? A#46: Try the command 'ls -n'. Q#47: How can I tell what is in library XXXX? A#47: 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 Byteworks' 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#16, Q#17, and Q#18). 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#48: Why isn't the common function XXXX in the libraries? A#48: The GNO libraries are still undergoing active development. If you find that a standard or common routine is missing, then contact Devin Reade 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#17). Distributing the work results in faster updates. Q#49: Function XXXX is declared in the GNO header files, but it's not in the libraries. Why? A#49: 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#48. Q#50: I want to release my library to the GNO community. Is there anything in particular that I should do? A#50: Here's a checklist: - Any symbols which should not be available to the user should have their private flag set. In C, this corresponds to using the "static" storage class specifier whenever possible. - Ensure your library is compatible with Orca/C's large memory model. - Write documentation, preferably one or more manual pages, for any exported symbols. If your library uses configuration files, write manual pages for those too (they belong in chapter 5). - Specify in the manual pages any dependancy on non-standard libraries. Specify dependancies for all header files, whether standard or not. - Consider including your source code with your library. This allows your contribution to survive even if your hard drive crashes, your backups are destroyed, or you leave the GNO community. Kernel Internals ---------------- Q#51: Can task-switching occur during an interrupt? A#51: No. Q#52: Can I tell GNO/ME to not task switch during a short (like a couple of ASM instructions) sequence? A#52: Turn off interrupts, or increment the busy flag around the code. Debugging (During Program Development) -------------------------------------- Q#53: What debuggers are available for GNO? A#53: 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 Micheal Hackett of Some Assembly Required. This is also available from Procyon. See also Q#54. 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#54: Why is the Splat! debugger crashing when my code calls fork(2)? A#54: 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#55: Part way through my debugging session, Splat! no longer shows my source file. Why? A#55: 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. 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#56: 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#56: You need to set the auxilliary file type of the program in question to $DC00. Use the chtyp command: chtyp -a \$DC00 ProgramName Note the '\' character; it must be there to escape the '$' character from the shell, otherwise the $DC00 would be treated as a shell variable. Q#57: 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#57: 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#58: My program is crashing when calling open(2). Why? A#58: 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 , or you are not getting open from 13/libc. See also Q#34, Q#44, Q#45, and Q#46. Q#59: What are the known bugs? First off, this is only a list of GNO-specific bugs. You should also consult the Orca/C bug list (see Q#34). If this answer gets too long, it will be moved off to another document. This list refers to GNO v2.0.4. In some cases, the problems have also been present in earlier versions. This list does not include any information on GNO v2.0.6. KERNEL: There are known kernel bugs that are patched by GUPP. (*** Nathan: Any details?) In the InitWildcardGS shell call, bit 0x2000 (traverse subdirectories) is not honoured. LIBRARIES: The rexit(3) implementation is missing. It's available at the ftp sites. In the libc(3) man page, the documented return value for access(3) is incorrect. The implementation (correctly) returns -1 on failure, 0 on success. The implementation of chdir(2) doesn't check to see if the target directory exists; it just changes the prefix. fdopen(3) is missing as of GNO v2.0.4. (It was present in earlier versions.) The prototype and implementation of mkdir(2) is nonstandard; normally this function should take a second (mode) parameter. For creat(2), the libc man page specifies that the semantics are similar to the Orca/C implementation. However, the Orca/C man page specifies a zero return value on success (I suspect this is incorrect). The GNO implementation definitely returns a non-negative file descriptor on success, and -1 on failure. GSH: There is a bug in the default gshrc file created by the installer. See the GNO release notes for details. gsh's command line parser seems to get confused when handling nested quotes, especially when there are spaces inside the quotes. For example, this command should work but doesn't: awk ' { print "Hello, world" } ' file The arguments awk receives look like this: arg 0 (length 3) = awk arg 1 (length 9) = { print arg 2 (length 6) = Hello, arg 3 (length 6) = world" arg 4 (length 1) = } arg 5 (length 5) = file