Documented _filetype and _auxtype

doc/apple2.sgml

@@ -511,6 +511,104 @@ url="ca65.html" name="assembler manual">.
 </descrip><p>
 
 
+<sect1>Specifying ProDOS File Types<p>
+
+<descrip>
+
+  <tag>Problem Explanation</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 and UNIX-like systems which use the file name's suffix (a.k.a.
+  extension) to specify the file type. For example, .exe, .doc, or .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>Solution</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/:
+
+  <quote>
+  <verb>
+  extern unsigned char _filetype;  /* Default: PRODOS_T_BIN */
+  extern unsigned int _auxtype;    /* Default: 0            */
+  </verb>
+  </quote>  
+
+  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
+  not 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 new line (Linux/BSD/MacOS) or 
+  carriage return, new line 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.
+
+  <quote>
+  <verb>
+    #include <stdio.h>
+    #include <string.h>
+    #include <errno.h>
+    #include <apple2.h>
+    void main()
+    {
+        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>
+  </quote>  
+
+</descrip><p>
+
 
 <sect>License<p>