[AD] [PATCH] FA_* flags documentation

[Stepan Roh <stepan@xxxxxxxxxx>]

Attached is a patch which documents FA_* flags (better than refering to
dir.h).

Have a nice day.

Stepan Roh

--- allegro._tx.old	Sun Feb  4 00:13:47 2001
+++ allegro._tx	Sun Feb  4 00:43:47 2001
@@ -5086,6 +5086,17 @@
 always begin with the 32 bit value F_PACK_MAGIC, and autodetect files with 
 the value F_NOPACK_MAGIC.
 
+Following FA_* flags are guaranteed to work: FA_RDONLY, FA_HIDDEN,
+FA_SYSTEM, FA_LABEL, FA_DIREC, FA_ARCH. Do not use any other flags under
+DOS/Windows or your code will not compile on another platform. Flags
+FA_SYSTEM, FA_LABEL and FA_ARCH are valuable only on DOS/Windows (entries
+with system flag, volume labels and archive flag - see dir.h for further
+information). FA_RDONLY is for directory entries with read-only flag on
+DOS-like systems or unwritable by current user on Unix-like systems.
+FA_HIDDEN is for entries with hidden flag on DOS or starting with '.' on
+Unix (dotted files - excluding '.' and '..'). FA_DIREC represents
+directories. Flags can be combined using '|' (binary OR operator).
+
 @@void @get_executable_name(char *buf, int size);
    Fills buf with the full path to the current executable, writing at most 
    size bytes.  This generally comes from argv[0], but on Unix systems if
@@ -5147,11 +5158,11 @@
 
 @@int @file_exists(const char *filename, int attrib, int *aret);
 @xref exists, file_size, file_time
-   Checks whether a file matching the given name and attributes exists, 
-   returning non-zero if it does. The file attribute may contain any of the 
-   FA_* constants from dir.h. If aret is not NULL, it will be set to the 
-   attributes of the matching file. If an error occurs the system error code 
-   will be stored in errno.
+   Checks whether a file matching the given name and attributes exists,
+   returning non-zero if it does. The file attribute may contain any of the
+   FA_* flags. If aret is not NULL, it will be set to the attributes of the
+   matching file. If an error occurs the system error code will be stored in
+   errno.
 
 @@int @exists(const char *filename);
 @xref file_exists
@@ -5183,19 +5194,17 @@
    this for whatever you like). If an error occurs an error code will be 
    stored in errno, and callback() can cause for_each_file() to abort by 
    setting errno itself. Returns the number of successful calls made to 
-   callback(). The file attribute may contain any of the FA_* flags from 
-   dir.h.
+   callback(). The file attribute may contain any of the FA_* flags.
 
 @@int @findfirst(const char *pattern, struct ffblk *ffblk, int attrib);
 @xref findnext, findclose
    If your platform doesn't have the find* set of functions, Allegro will
-   emulate them. This function finds the first file which matches the
-   given wildcard specification and file attributes. The information will
-   be put in the ffblk struct which you have to provide. The function
-   returns zero if a match is found, nonzero if none found. The file
-   attribute may contain any of the FA_* flags from dir.h. The ffblk
-   structure contains the variables: ff_attrib, ff_time, ff_date, ff_size
-   and ff_name.
+   emulate them. This function finds the first file which matches the given
+   wildcard specification and file attributes. The information will be put
+   in the ffblk struct which you have to provide. The function returns zero
+   if a match is found, nonzero if none found. The file attribute may
+   contain any of the FA_* flags. The ffblk structure contains the
+   variables: ff_attrib, ff_time, ff_date, ff_size and ff_name.
 
 @@int @findnext(struct ffblk *ffblk);
 @xref findfirst, findclose