ExNext

Examine the next entry in a directory

Declaration

Source position: amigados.pas line 1677

Arguments

Function result

=0 for fail, <> 0 for success

Description

This routine is passed a directory lock and a TFileInfoBlock that have been initialized by a previous call to Examine(), or updated by a previous call to ExNext(). ExNext() gives a return code of zero on failure. The most common cause of failure is reaching the end of the list of files in the owning directory. In this case, IoErr() will return ERROR_NO_MORE_ENTRIES and a good exit is appropriate.

So, follow these steps to examine a directory:

1. Pass a Lock and a FileInfoBlock to Examine(). The lock must be on the directory you wish to examine.
2. Pass ExNext() the same lock and TFileInfoBlock.
3. Do something with the information returned in the TFileInfoBlock. Note that the fib_DirEntryType field is positive for directories, negative for files.
4. Keep calling ExNext() until it returns False. Check IoErr() to ensure that the reason for failure was ERROR_NO_MORE_ENTRIES.

Attention

If you wish to recursively scan the file tree and you find another directory while ExNext()ing you must Lock that directory and Examine() it using a new FileInfoBlock. Use of the same FileInfoBlock to enter a directory would lose important state information such that it will be impossible to continue scanning the parent directory. While it is permissible to UnLock() and Lock() the parent directory between ExNext() calls, this is not recommended. Important state information is associated with the parent lock, so if it is freed between ExNext() calls this information has to be rebuilt on each new ExNext() call, and will significantly slow down directory scanning.

It is not legal to Examine() a file, and then to ExNext() from that TFileInfoBlock. You may make a local copy of the TFileInfoBlock, as long as it is never passed back to the operating system.

See also

Example

program ExamineTest;
uses
  AmigaDos;
procedure CheckDir(ALock: BPTR);
var
  FIB: PFileInfoBlock;
begin
  FIB := AllocDosObject(DOS_FIB, nil);
  if Assigned(FIB) then
  begin
    if Examine(ALock, FIB) <> 0 then
    begin
      repeat
        writeln(FIB^.fib_FileName);
      until ExNext(ALock, FIB) = 0;
    end;
    if IOErr() = ERROR_NO_MORE_ENTRIES then
      writeln('nothing more found')
    else
      writeln('Something went wrong ', IOErr);
    FreeDosObject(DOS_FIB, FIB);
  end;
end;
var
  RAMLock: BPTR;
begin
  RAMLock := Lock('RAM:', SHARED_LOCK);
  CheckDir(RAMLock);
  unlock(RAMLock);
end.