# MX\_FINDFIRST

> [HTML Version](mx_findfirst.htm)

_Reviewed May 2024_

**xcall MIAMEX, MX\_FINDFIRST, directory, status, filename, size, attrib \{,cdate, ctime, udate, utime \{, adate, atime\}\}**

MX\_FINDFIRST (MIAMEX 20), combined with its sister function, MX\_FINDNEXT, is used to scan directories for subdirectories or files.

**Parameters**

_directory _ ([String](string.htm.md))  \[in\]

This must be set to the directory which is to be scanned for files. This directory specification must be in host operating system format, and include the terminating directory separator. See [MX\_FSPEC](mx_fspec.htm.md) (Perform FSPEC on AMOS string) for information on converting an AMOS-style directory to the equivalent host directory.

_status  _([Num](num.htm.md))  \[out\]

On return, _status_ is set to zero to indicate success. A non-zero status indicates an error, most likely that no files or directories match the specification you gave in _directory_.

_filename_  ([String](string.htm.md))  \[out\*\]

The first entry in the specified directory will be returned in _filename_. Typically this is a regular file (in _name.ext_ format) but may be a special file, such as another directory or the "." and ".." entries which typically appear at the start of each directory, which you can determine by the _attrib_ flags (below). The returned name will be truncated to fit, but you should specify a reasonably large variable, since Unix and Windows filenames can be quite long.

_size_**  **(F6)  \[out\]

returns the size of the found file, in bytes.

_attrib  _([Num](num.htm.md))  \[out\]

is a bit-mapped numeric field into which are placed the various attributes of the file or sub-directory represented by _filename_, according to the following table:

| **Symbol** | **Value** | **Meaning** |
|------|------|------|
| FATR\_NORMAL | 1 | Normal file |
| FATR\_SUBDIR | 2 | Subdirectory |
| FATR\_READONLY | 4 | You (current user) have read-only permission for this file or directory |
| **Definition file: [ashell.def](ashell_def.htm.md)** | | 



_cdate_, _udate_, _adate_  ([String](string.htm.md), 10+ bytes)  \[out\]

are the create/status change date, update/modify date, and access date of the file or directory, using the format dd-mon-yr (e.g. "01-Jan-08"). Note that under Unix systems, the CDATE will be changed when the privileges or ownership of the file is changed.   

_ctime_, _utime_, _atime_ ([String](string.htm.md), 5+ bytes)  \[out\]

are the create/status change time, update/modify time, and last access time for the file or directory, using the format (hh:mm).

**Comments**

\* Under Windows, you can actually set _directory _to a literal or wildcard filename to skip directly to the first matching file. However, this is not recommended, since under Unix you must specify a directory (not a file path) with a trailing directory separator.

**History**

2026 April, A-Shell 7.0.1785:  Logging refinement: MX\_FILESTATS and MX\_FINDFIRST no longer output messages to ashlog for file-not-found errors. Any other errors will continue to be logged. Setting the FOPENS TRACE flag will restore the logging of file-not-found errors.

2021 October, A-Shell 6.5.1708:  Extend the maximum number of nesting levels from 3 to 20. This was done years ago for the Windows version but somehow overlooked for the Unix version.

2020 October, A-Shell 6.5.1690:  Expand the limit on the maximum length of a filename from 123 to 255 characters.