<sect>Binary format<p>
The standard binary file format generated by the linker for the
-Apple ][ target is a binary program with a 4 byte DOS 3.3 header
-containing the load address and load length. The default load address is
-$803.
+Apple ][ target is an <url name="AppleSingle"
+url="http://kaiser-edv.de/documents/AppleSingle_AppleDouble.pdf"> file.
+The default load address is $803.
-<bf/AppleCommander 1.3.5/ or later (available at <url
-url="http://applecommander.sourceforge.net/">) includes the option <tt/-cc65/
-that allows to put binary files with a DOS 3.3 header onto disk images
-containing DOS 3.3 as well as ProDOS 8.
-
-For ProDOS 8 system programs the load address is fixed to $2000 so there
-is no need for a header. Thus the linker configuration
-<ref id="apple-sys-cfg" name="apple2-system.cfg"> for those programs
-omits the DOS 3.3 header. The right AppleCommander option to put system files
-without a header on a ProDOS 8 disk image is <tt/-p/.
+<bf/AppleCommander 1.4.0/ or later (available at <url
+url="https://applecommander.github.io/">) includes the option <tt/-as/ that
+allows to put AppleSingle files onto disk images containing DOS 3.3 as well
+as ProDOS 8.
<sect>Memory layout<p>
<tag><tt/STARTADDRESS:/ Program start address</tag>
Default: $803. Use <tt/-S <addr>/ to set a different start address.
- <tag><tt/__EXEHDR__:/ Executable file header</tag>
- Default: DOS 3.3 header (address and length). Use <tt/-D __EXEHDR__=0/ to omit
- the header.
+ <tag><tt/__EXEHDR__:/ AppleSingle executable file header</tag>
+ Default: Yes. Use <tt/-D __EXEHDR__=0/ to omit the AppleSingle header.
<tag><tt/__STACKSIZE__:/ C runtime stack size</tag>
Default: $800. Use <tt/-D __STACKSIZE__=<size>/ to set a different
<descrip>
+ <tag><tt/__EXEHDR__:/ AppleSingle executable file header</tag>
+ Default: Yes. Use <tt/-D __EXEHDR__=0/ to omit the AppleSingle header.
+
<tag><tt/__STACKSIZE__:/ C runtime stack size</tag>
Default: $800. Use <tt/-D __STACKSIZE__=<size>/ to set a different
stack size.
</descrip><p>
+<sect1><tt/apple2-hgr.cfg/<p>
+
+Configuration for a program including a hires page. See <tt>testcode/lib/apple/hgrtest.c</tt>
+for an example of such a program.
+
+Parameters:
+
+<descrip>
+
+ <tag><tt/STARTADDRESS:/ Program start address</tag>
+ Default: $803. Use <tt/-S <addr>/ to set a different start address.
+
+ <tag><tt/__EXEHDR__:/ AppleSingle executable file header</tag>
+ Default: Yes. Use <tt/-D __EXEHDR__=0/ to omit the AppleSingle header.
+
+ <tag><tt/__STACKSIZE__:/ C runtime stack size</tag>
+ Default: $800. Use <tt/-D __STACKSIZE__=<size>/ to set a different
+ stack size.
+
+ <tag><tt/__HIMEM__:/ Highest usable memory address presumed at link time</tag>
+ Default: $9600. Use <tt/-D __HIMEM__=<addr>/ to set a different
+ highest usable address.
+
+ <tag><tt/__LCADDR__:/ Address of code in the Language Card</tag>
+ Default: $D400. Use <tt/-D __LCADDR__=<addr>/ to set a different
+ code address.
+
+ <tag><tt/__LCSIZE__:/ Size of code in the Language Card</tag>
+ Default: $C00. Use <tt/-D __LCSIZE__=<size>/ to set a different
+ code size.
+
+</descrip><p>
+
+
<sect1><tt/apple2-overlay.cfg/<p>
-Configuration for overlay programs with the up to nine overlays. The overlay files
-don't include the DOS 3.3 header. See <tt>samples/overlaydemo.c</tt> for more
+Configuration for an overlay program with up to nine overlays. The overlay files
+don't include the AppleSingle header. See <tt>samples/overlaydemo.c</tt> for more
information on overlays.
Parameters:
<tag><tt/STARTADDRESS:/ Program start address</tag>
Default: $803. Use <tt/-S <addr>/ to set a different start address.
- <tag><tt/__EXEHDR__:/ Executable file header</tag>
- Default: DOS 3.3 header (address and length). Use <tt/-D __EXEHDR__=0/ to omit
- the header.
+ <tag><tt/__EXEHDR__:/ AppleSingle executable file header</tag>
+ Default: Yes. Use <tt/-D __EXEHDR__=0/ to omit the AppleSingle header.
<tag><tt/__STACKSIZE__:/ C runtime stack size</tag>
Default: $800. Use <tt/-D __STACKSIZE__=<size>/ to set a different
<sect1><tt/apple2-asm.cfg/<p>
-Configuration for a assembler programs which don't need a special setup.
+Configuration for an assembler program that doesn't need a special setup.
Parameters:
<tag><tt/STARTADDRESS:/ Program start address</tag>
Default: $803. Use <tt/-S <addr>/ to set a different start address.
- <tag><tt/__EXEHDR__:/ Executable file header</tag>
- Default: No header. Use <tt/-u __EXEHDR__ apple2.lib/ to add a DOS 3.3 header
- (address and length).
+ <tag><tt/__EXEHDR__:/ AppleSingle executable file header</tag>
+ Default: No. Use <tt/-u __EXEHDR__ apple2.lib/ to add the AppleSingle header.
</descrip><p>
Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the
program to load under name <program>.SYSTEM as a system program. For
-example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/.
+example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/. The right
+AppleCommander option to put LOADER.SYSTEM on a ProDOS 8 disk image is <tt/-p/.
<sect1>Heap<p>
<tag/Interrupts/
There's no <tt/interruptor/ support. Any attempt to use it yields the message
'FAILED TO ALLOC INTERRUPT' on program startup. This implicitly means that
- joystick, mouse and RS232 device drivers are not functional as they depend on
- interrupts.
+ mouse and RS232 device drivers are not functional as they depend on interrupts.
</descrip><p>
</descrip><p>
+<sect1>Specifying file types for fopen<p>
+
+<descrip>
+
+ <tag>Explanation of File Types</tag>
+
+ ProDOS associates a file type and an auxiliary type with each file.
+ These type specifications are separate from the file's name, unlike
+ Windows which uses the file name's suffix (a.k.a.
+ extension) to specify the file type. For example, <tt/.exe/,
+ <tt/.doc/, or <tt/.bat/.
+ The ProDOS low-level
+ Machine-Language Interface (MLI) functions for creating and opening
+ files require these types to be specified. And if they don't match
+ with the file being opened, the operation may fail.
+
+ In contrast, the ISO C function <tt/fopen()/ and the POSIX function
+ <tt/open()/ have no parameter to specify either a file type or an
+ auxiliary type. Therefore, some additional mechanism for specifying
+ the file types is needed.
+
+ <tag>Specifying the File Type and Auxiliary Type</tag>
+
+ There are two global variables provided that allow the file type
+ and auxiliary type to be specified before a call to <tt/fopen()/
+ or <tt/open()/. They are defined in <tt/apple2_filetype.h/:
+
+ <tscreen>
+ <verb>
+ extern unsigned char _filetype; /* Default: PRODOS_T_BIN */
+ extern unsigned int _auxtype; /* Default: 0 */
+ </verb>
+ </tscreen>
+
+ The header file <tt/apple2_filetype.h/ also defines many values
+ that can be used to set these variables. It is included in
+ <tt/apple2.h/, which is in turn included in <tt/apple2enh.h/.
+ So it isn't necessary to include it directly. Just
+ include one of <tt/apple2.h/ or <tt/apple2enh.h/.
+
+ <tag>Example</tag>
+
+ A text file cannot be created with just the
+ standard C functions because they default to the binary type
+ <tt/PRODOS_T_BIN/. The <tt/_filetype/ variable must be set to
+ <tt/PRODOS_T_TXT/ to create a text file.
+
+ For a text file,
+ <tt/_auxtype/ specifies the record length. A zero record
+ length text file is referred to as a sequential text file.
+ This is equivalent to text files on
+ other operating systems, except that the line terminator is a
+ carriage return instead of a line-feed (Linux/BSD/MacOS) or
+ carriage return, line-feed pair (Windows).
+
+ The "sequential" text file terminology is in contrast to a
+ "random-access" text file which would
+ have a fixed-length, non-zero record length, so that the
+ file position of any individual record can be calculated.
+
+ For this example, the
+ <tt/_auxtype/ does not need to be set because it defaults to
+ the desired value, which is zero. To be more explicit,
+ <tt/_auxtype/ can also be set to <tt/PRODOS_AUX_T_TXT_SEQ/
+ which is defined as zero.
+
+ <tscreen>
+ <verb>
+ #include <stdio.h>
+ #include <string.h>
+ #include <errno.h>
+ #include <apple2.h>
+
+ void main(void)
+ {
+ FILE *out;
+ char *name = "MY.FAVS";
+
+ /*-----------------------------*/
+
+ _filetype = PRODOS_T_TXT;
+ _auxtype = PRODOS_AUX_T_TXT_SEQ;
+
+ /*-----------------------------*/
+
+ if ((out = fopen(name, "w")) != NULL) {
+ fputs("Jorah Mormont\r", out);
+ fputs("Brienne of Tarth\r", out);
+ fputs("Daenerys Targaryen\r", out);
+ fputs("Sandor Clegane\r", out);
+ if (fclose(out) == EOF) {
+ fprintf(stderr, "fclose failed for %s: %s", name, strerror(errno));
+ }
+ }
+ else {
+ fprintf(stderr, "fopen failed for %s: %s", name, strerror(errno));
+ }
+ }
+ </verb>
+ </tscreen>
+
+</descrip><p>
+
<sect>License<p>
projects / cc65 / blobdiff