Skip to content

    FindFirst

    Start a file search and return a findhandle.

    Declaration

    Source position: filutilh.inc line 233

    function FindFirst(const Path: UnicodeString; Attr: LongInt; 
                  out Rslt: TUnicodeSearchRec) : LongInt;

    function FindFirst(const Path: RawByteString; Attr: LongInt; 
                  out Rslt: TRawbyteSearchRec) : 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:

    faAnyFile
    Find any file (this is a combination of the other flags except faSymlink).
    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, and on Windows-like systems, this works only for plan FAT (not Fat32 of VFAT) file systems.
    faDirectory
    File is a directory.
    faArchive
    file needs to be archived. Not possible on Unix
    faSymlink
    Report symlinks instead of following them

    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.

    Since faSymlink is not included in faAnyFile, to find all possible files and symlinks you need to call FindFirst so: 

    if FindFirst('*', faAnyFile or faSymLink, info)=0 then
  // do your thing

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

    Remark:

    A successful FindFirst call must always be followed by a FindClose call with the same Rslt record. Failure to do so will result in memory leaks. If the findfirst call failed (i.e. returned a nonzero handle) there is no need to call FindClose.

    Errors

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

    See also

    Name Description
    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,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;
    FindClose(Info);
    end;
  Writeln ('Finished search. Found ',Count,' matches');
End.