+/**
+ * Create a file_struct for a named file by reading its stat()
+ * information and performing extensive checks against global
+ * options.
+ *
+ * @return the new file, or NULL if there was an error or this file
+ * should be excluded.
+ *
+ * @todo There is a small optimization opportunity here to avoid
+ * stat()ing the file in some circumstances, which has a certain cost.
+ * We are called immediately after doing readdir(), and so we may
+ * already know the d_type of the file. We could for example avoid
+ * statting directories if we're not recursing, but this is not a very
+ * important case. Some systems may not have d_type.
+ **/