# Function Reference

# FileFindFirstFile

Creates a search handle, defined by a path and file mask.

FileFindFirstFile ( "filename" )

## Parameters

filename | The path and file name. (* and ? wildcards accepted - See Remarks)

## Return Value

Success: | a search "handle" for use with subsequent FileFindNextFile functions.
Failure: | -1 if nothing is found. The value of the @error flag is set to 1 only if the Folder is empty.

## Remarks

The search string is not case sensitive.
Wildcards: In general, * denotes zero or more characters, and ? denotes zero or one character. If your file search string contains only wildcards (or is "*.*"), then see the example below for the return value!
You can use only one wildcard in the filename part or in the extension part i.e. a*.b?.
When using a 3-char extension any extension starting with those 3 chars will match, .e.g. "*.log" will match "test.log_1". (not described either in Microsoft documentation).
When you have finished searching with the FileFind... functions you must call FileClose() to release the search handle.
Directory name are returned according to the wildcards if any.
Due to the underlying Windows API used (FindFirstFile), this function actually searches both the long and short filenames when looking for matches.
If you get unexepected results then verify that it's not the short filename that is being matched.

## Related

FileClose, FileFindNextFile

## Example

    #include <MsgBoxConstants.au3>

    Example()

    Func Example()
        ; Assign a Local variable the search handle of all files in the current directory.
        Local $hSearch = FileFindFirstFile("*.*")

        ; Check if the search was successful, if not display a message and return False.
        If $hSearch = -1 Then
            MsgBox($MB_SYSTEMMODAL, "", "Error: No files/directories matched the search pattern.")
            Return False
        EndIf

        ; Assign a Local variable the empty string which will contain the files names found.
        Local $sFileName = "", $iResult = 0

        While 1
            $sFileName = FileFindNextFile($hSearch)
            ; If there is no more file matching the search.
            If @error Then ExitLoop

            ; Display the file name.
            $iResult = MsgBox(($MB_OKCANCEL + $MB_SYSTEMMODAL), "", "File: " & $sFileName)
            If $iResult <> $IDOK Then ExitLoop ; If the user clicks on the cancel/close button.
        WEnd

        ; Close the search handle.
        FileClose($hSearch)
    EndFunc   ;==>Example