[Overview][Constants][Types][Classes][Procedures and functions][Variables][Index] | Reference for unit 'sysutils' (#rtl)

# FindFirst

Start a file search and return a findhandle

## Declaration

Source position: filutilh.inc line 88

`function FindFirst(`
`const Path: String;`
`Attr: LongInt;`
`out Rslt: TSearchRec`
`):LongInt;`

## Description

FindFirst looks for files that match the name (possibly with wildcards) in Path and extra attributes Attr. It then fills up the Rslt record with data gathered about the file. It returns 0 if a file matching the specified criteria is found, a nonzero value (-1 on Unix-like platforms) otherwise.

Attr is an or-ed combination of the following constants:

faReadOnly
  The file is read-only.
faHidden
  The file is hidden. (On unix, this means that the filename starts with a dot)
faSysFile
  The file is a system file (On unix, this means that the file is a character, block or FIFO file).
faVolumeId
  Drive volume Label. Not possible under unix.
faDirectory
  File is a directory.
faArchive
  file is an archive. Not possible on Unix

It is a common misconception that Attr specifies a set of attributes which must be matched in order for a file to be included in the list. This is not so: The value of Attr specifies additional attributes, this means that the returned files are either normal files or have an attribute which is present in Attr.

Specifically: specifying faDirectory as a value for Attr does not mean that only directories will be returned. Normal files and directories will be returned.

The Rslt record can be fed to subsequent calls to FindNext, in order to find other files matching the specifications.

Remark: | A FindFirst call must always be followed by a FindClose call with the same Rslt record. Failure to do so will result in memory loss.

## Errors

On error the function returns -1 on Unix-like platforms, a nonzero error code on Windows.

## See also

FindClose |  | Close a find handle
FindNext |  | Find the next entry in a findhandle.

## Example

    Program Example43;

    { This program demonstrates the FindFirst function }

    Uses SysUtils;

    Var Info : TSearchRec;
        Count : Longint;

    Begin
      Count:=0;
      If FindFirst ('*',faAnyFile and faDirectory,Info)=0 then
        begin
        Repeat
          Inc(Count);
          With Info do
            begin
            If (Attr and faDirectory) = faDirectory then
              Write('Dir : ');
            Writeln (Name:40,Size:15);
            end;
        Until FindNext(info)<>0;
        end;
      FindClose(Info);
      Writeln ('Finished search. Found ',Count,' matches');

    End.

The latest version of this document can be found at lazarus-ccr.sourceforge.net.