ExNext

Examine the next entry in a directory

This function is passed a directory Lock and a FileInfoBlock 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 FileInfoBlock.
   
   
3. Do something with the information returned in the FileInfoBlock.
   
   Note that the fib_DirEntryType field indicates the kind of directory entry, e.g. a file has a value < 0 and a directory has a value > 0.
   
   

   Caution:

   This is a rough categorization and omits more detailed aspects of the type of directory entry found!
   
   For example, you may encounter both hard and soft links which are identified by their specific directory entry type values such as ST_SOFTLINK, ST_LINKDIR and ST_LINKFILE. The complete list of defined directory entry types can be found in the <dos/dosextens.h> header file.
   
   

4. Keep calling ExNext() until it returns FALSE. Check IoErr() to ensure that the reason for failure was ERROR_NO_MORE_ENTRIES.
   
   

Note:

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.

Examine() and ExNext() only work with a Lock on a directory. It is NOT legal to use Examine() with a Lock on a file and then to call ExNext() from that FileInfoBlock.

You may make a local copy of the FileInfoBlock, as long as it is never passed back to the operating system.

Unlike its companion function Examine(), ExNext() will provide information about soft link directory entries, correctly identifying their type.

lock

BCPL pointer to a Lock originally used for the Examine() call. This Lock shall be non-zero. Unlike Examine(), ExNext() does not support the NULL Lock.

infoBlock

pointer to a FileInfoBlock used on the previous Examine() or ExNext() call.

success

boolean; FALSE indicates that no further entries can be read. Call IoErr() to find out whether this is due to an error, or if the end of the directory has been reached. IoErr() will return ERROR_NO_MORE_ENTRIES if no error has occurred.

The emphasis on insuring that the FileInfoBlock pointer must be longword aligned is profound. Do not take this lightly. It is easy to overlook this requirement and then face the consequences of memory corruption and worse.

One way of insuring that the FileInfoBlock pointer you provide is properly aligned is to use AllocDosObject(DOS_FIB, NULL) which is available in V36.

Prior to that, in Kickstart 1.2/1.3 (V33/V34) you may want to fall back onto AllocMem(sizeof(struct FileInfoBlock), MEMF_ANY|MEMF_PUBLIC) to allocate memory for the infoBlock pointer which will be longword aligned. Use FreeMem(infoBlock, sizeof(struct FileInfoBlock)) when you no longer need it.

If you combine directory scanning with deleting or adding new directory entries to the very directory you are scanning, you will find that the file system may have difficulties in consistently returning the next directory entry. It may have to restart scanning if a change is made, or it may lose track of where it used to be, returning entries again which it already provided to you. Worst case, it may continue scanning from a directory entry which was already deleted. The Kickstart 1.x AmigaDOS ROM file system and ram-handler were very vulnerable in this regard.

You are well advised to delay making changes to the directory you are scanning until after you have retrieved either the next entry or arrived at the end of the directory. Hence, remember the information which ExNext() returned, call ExNext() again, modify or delete the entry remembered, etc. and keep doing so until you have processed all the directory entries.

The contents of the directory you are scanning may change while you are reading it with ExNext(), because a different program may be running at the same time, making changes. Entries may get removed, renamed, changed or added. By the time you learn the name and the properties of a directory entry, this information may already be stale. When you reach the last entry, it may not be the last entry any more. Be prepared for such changes.

The original Amiga ROM file system in Kickstart 1.0-1.3 would fill in the FileInfoBlock.fib_NumBlocks field by visiting and counting all the data blocks of a file. This would both verify that the file was sound and also significantly increase the time needed to scan a directory. This feature/bug did not carry over to the V34 FastFileSystem and is not present in the Amiga ROM file system versions 36 and beyond (Kickstart 2.0).

The original Workbench 1.x era CLI commands "Copy", "Delete", "Dir", "List", "Protect" and "Search" make use of a much shorter form of the 'struct FileInfoBlock' which only covers the first 228 bytes. The full 'struct FileInfoBlock' as defined in <dos/dos.h> is 260 bytes in size. If you implement a file system which is used by one of these old Workbench 1.x era commands, you must limit yourself to fill in only the parts of the 'struct FileInfoBlock' which are covered by the first 228 bytes. If your file system modifies any data beyond this point, you are likely to corrupt the stack of these commands, causing them to crash.

Examine(), Lock(), UnLock(), IoErr(), ExamineFH(), AllocDosObject(), ExAll(), <dos/dosextens.h>, exec.library/AllocMem