[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
On Wednesday 21 September 2005 23:34, Evert Glebbeek wrote:
> As briefly discussed here,
> http://www.allegro.cc/forums/view_thread.php?_id=530017, the attached
> patch adds an FA_ALL flag to pass in case one wants to match all flags
> (ie, find all files).
> It also addss an FA_NONE flag, which only matches files that have no
flags
> set. I don't think this is very useful in practice, but it is nice for
the
> symmetry and it makes it possible to #define FA_ALL ~FA_NONE, which is
> somewhat more readable than ~0.
Commited. Attached is the proposed documentation update, which is really an
attempt to make some sense out of the confusing FA_* documentation.
Evert
Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.367
diff -u -r1.367 allegro._tx
--- docs/src/allegro._tx 25 Sep 2005 22:01:35 -0000 1.367
+++ docs/src/allegro._tx 28 Sep 2005 20:55:41 -0000
@@ -9843,25 +9843,36 @@
always begin with the 32-bit value F_PACK_MAGIC, and autodetect files with
the value F_NOPACK_MAGIC.
-The 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 from
-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). 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-like systems or starting with '.' on Unix (dotted files -
-excluding '.' and '..'). FA_DIREC represents directories. Flags can be
-combined using '|' (binary OR operator).
+The following FA_* flags are guaranteed to work:
+<textblock>
+ FA_NONE - Exclude files that have any attribute set
+ FA_RDONLY - Directory entries that are unwritable for current user
+ FA_HIDDEN - Hidden flag
+ FA_DIREC - Directories
+ FA_SYSTEM - Files with system flag set (DOS/Windows only)
+ FA_LABEL - Files with volume label flag set (DOS/Windows only)
+ FA_ARCH - Files with archive flag set (DOS/Windows only)
+ FA_ALL - Match all attributes<endblock>
+Do not use any other flags from DOS/Windows or your code will not compile on
+another platform.
+FA_RDONLY is for directory entries with read-only flag on DOS-like systems or
+unwritable by current user on Unix-like systems. Hidden files are directory
+entries that have the hidden flag set (DOS/Windows) or have names starting with
+'.' (UNIX, excluding '.' and '..').
+Flags can be combined using '|' (binary OR operator).
When passed to the functions as the 'attrib' parameter, these flags
represent an upper set in which the actual flag set of a matching file must
be included. That is, in order for a file to be matching, its attributes
may contain any of the specified flags but must not contain any of the
-unspecified flags. Thus, if you pass 'FA_DIREC | FA_RDONLY', normal files
+unspecified flags. In other words, you explictly <i>exclude</i> the flags that you
+do <i>not</i> specify. Thus if you pass 'FA_DIREC | FA_RDONLY', normal files
and directories will be included as well as read-only files and
directories, but not hidden files and directories. Similarly, if you pass
-'FA_ARCH' then both archived and non-archived files will be included.
+'FA_ARCH' then both archived and non-archived files will be included. If
+FA_NONE is passed all attributes are excluded and only files with no attributes
+are returned. Conversely, if you pass FA_ALL, no attributes are excluded so all
+files are returned (which is what you would usually want).
Functions which accept wildcards as file names support the meta characters
`*' (which means, zero or any quantity of characters) and `?' (which means
@@ -10168,7 +10179,7 @@
<codeblock>
struct al_ffblk info;
- if (al_findfirst("*.pcx", &info, 0) != 0) {
+ if (al_findfirst("*.pcx", &info, FA_ALL) != 0) {
/* Tell user there are no PCX files. */
return;
}<endblock>