.\" Generated by the Allegro makedoc utility
.TH for_each_file_ex 3alleg4 "version 4.4.3" "Allegro" "Allegro manual"
.SH NAME
for_each_file_ex \- Executes callback() for each file matching a wildcard. Allegro game programming library.\&
.SH SYNOPSIS
.B #include <allegro.h>

.sp
.B int for_each_file_ex(const char *name, int in_attrib, int out_attrib,
.B int (*callback)(const char *filename, int attrib,
.B void *param), void *param);
.SH DESCRIPTION
Finds all the files on disk which match the given wildcard specification
and file attributes, and executes callback() once for each. Basically, this
is a convenient wrapper around al_findfirst(), al_findnext() and
al_findclose(). `in_attrib' is a bitmask specifying the attributes the
files must carry, `out_attrib' is a bitmask specifying the attributes the
files must not carry; attributes which are not specified in either bitmasks
are not taken into account for deciding whether callback() is invoked or
not.

The callback function will be passed three arguments: the first is a string
which contains the completed filename (exactly the same string you passed
to for_each_file_ex() but with meta characters), the second is the actual
attributes of the file, and the third is a void pointer which is simply a
copy of `param' (you can use this for whatever you like). The callback must
return zero to let the enumeration proceed, or any non-zero value to stop
it. If an error occurs, the error code will be stored in `errno' but the
enumeration won't stop. Example:

.nf
   int show_name(const char *filename, int attrib, void *param)
   {
      allegro_message("Caught `%s', attribs %d\\n",
                      filename, attrib);
      return 0;
   }
   ...
      count = for_each_file_ex("data/level*", FA_DIREC,
                               0, show_name, 0);
      allegro_message("%d game directories\\n", count);
.fi
.SH "RETURN VALUE"
Returns the number of successful calls made to callback(), that is, the
number of times callback() was called and returned 0.

.SH SEE ALSO
.BR al_findfirst (3alleg4),
.BR al_findnext (3alleg4),
.BR al_findclose (3alleg4)