ExAll

Examine an entire directory (V36)

Examines an entire directory, returning information on all of its directory entries in a compact manner, possibly more efficiently than the Examine() .. ExNext() loop could.

'lock' must be on a directory. 'size' is the size of the buffer supplied. The 'buffer' will be filled with (partial) ExAllData structures, as specified by the 'type' argument.

'type' is a value from those shown below that determines which information is to be stored in the 'buffer'. Each higher value adds a new thing to the list as described in the table below:

ED_NAME

File name

ED_TYPE

Type of directory entry

ED_SIZE

Size in bytes

ED_PROTECTION

Protection bits

ED_DATE

3 longwords of date (= sizeof(struct DateStamp))

ED_COMMENT

Comment (will be NULL if no comment)

ED_OWNER

owner user-id and group-id (if supported) (V39)

Thus, ED_NAME gives only filenames, and ED_OWNER gives everything.

NOTE:

V37 dos.library, when doing ExAll() emulation, and V37 file systems will return an error if passed type=ED_OWNER. If ExAll() fails and IoErr() returns ERROR_BAD_NUMBER, retry with type=ED_COMMENT to get everything but owner info.

All file systems supporting ExAll() must support type parameters through ED_COMMENT, and must check type and then stop & return ERROR_BAD_NUMBER if they do not support the type.

The ExAllData->ead_Next member gives a pointer to the next entry in the buffer. The final entry will have NULL in ead_Next.

The 'control' argument is required so that the file system can keep track if more than one call to ExAll() is required. This happens when there are more names in a directory than will fit into the buffer.

NOTE:

The control structure (ExAllControl) MUST be allocated by AllocDosObject(DOS_EXALLCONTROL, NULL) !!!

The format of the control structure is as follows:

eac_Entries

This member tells the calling application how many entries are in the buffer after calling ExAll().

Note:

make sure your code handles the 0 entries case, including 0 entries with continue non-zero.

eac_LastKey

This member ABSOLUTELY MUST be initialised to 0 before calling ExAll() for the first time. Any other value will lead to undefined behaviour and will cause nasty things to happen. If ExAll() returns non-zero, then this member should not be touched before making the second and subsequent calls to ExAll(). Whenever ExAll() returns non-zero, there are more calls required before all names have been received.

As soon as a FALSE return is received, then ExAll() has completed. If IoErr() returns ERROR_NO_MORE_ENTRIES, and otherwise, it returns the error that occurred, similar to the ExNext() function.

eac_MatchString

If this member is NULL then all file names will be returned. If this member is non-NULL then it is interpreted as a pointer to a string that is used to pattern-match all file names before accepting them and putting them into the buffer. The default AmigaDOS caseless pattern match function is used. This string MUST have been parsed by ParsePatternNoCase() before you call ExAll() for the first time!

eac_MatchFunc

This member contains a pointer to a Hook for a function to decide if the entry will be included in the returned list of entries. The entry is filled out first, and then passed to the Hook. If no eac_MatchFunc is to be called, then this entry should be NULL. The Hook is called with the following parameters (as is standard for Hooks):

accept = MatchFunc( hookptr, exalldata, typeptr )

D0 A0 A1 A2

(A0 = pointer to 'struct Hook', A1 = pointer to filled-in

'struct ExAllData', A2 = pointer to LONG of type).

MatchFunc() should return FALSE if the entry is not to be accepted, otherwise return TRUE.

Note that dos.library will emulate ExAll() using Examine() and ExNext() if the file system in question does not support the features which enable ExAll() to be used.

lock

Lock on directory to be examined. NOTE: Not all file systems will accept a NULL Lock here.

buffer

Buffer for data returned (MUST be at least word-aligned, preferably long-word aligned).

size

Size in bytes of 'buffer'.

type

Type of data to be returned.

control

Control data structure (see notes above). MUST have been allocated by AllocDosObject(DOS_EXALLCONTROL, NULL)!

continue

Whether ExAll() is done. If FALSE is returned, either ExAll() has completed (with the IoErr() function returning ERROR_NO_MORE_ENTRIES), or an error occurred (check IoErr()). If non-zero is returned, you MUST keep calling ExAll() again until it returns FALSE.

It is never safe to use ExAll() with a NULL Lock!

If you call ExAll() once, you should either continue calling it until it returns FALSE, or (requires Kickstart 3.0 or better), call ExAllEnd() in order to bring the scanning operation to a conclusion. Some file systems, e.g. network file systems, may still be busy processing directory records when you stop calling ExAll(). ExAllEnd() could be the fastest way to make them stop, releasing any resources currently tied up with preparing directory records which will not be needed. In any case, by the time you call UnLock() on the Lock you passed to ExAll() the file system should be aware that directory scanning has come to an end.

Filling the buffer with ExAllData records will take its time, and the larger the buffer, the more time the file system will spend on filling it. This may result in the data provided being stale by the time the ExAll() function returns. Directory entries may have been removed, replaced or changed by the time you are ready to process them. This is certainly true for Examine()/ExNext() style directory scanning, too, but the much larger buffer size used by ExAll() makes it much more likely for the ExAllData records to go out of sync with the directory contents. Be prepared to handle this.

The use of ExAll() is discouraged, both from the file system implementor's point of view as well as from the ExAll() user's point of view. The promise of ExAll()'s advantages over the use of Examine()/ExNext() must be weighed against the challenge of using ExAll() correctly and certainly of the challenge of implementing it correctly in a file system, assuming that it is implemented correctly to begin with. Support for ExAll() in file systems used to be rare and tended to be poorly-tested.

As experience shows, file system implementors struggle with correctly handling all the corner cases, leading to unpredictable behaviour on both the file system side and the ExAll() user's side. This is especially true for the Amiga operating system itself which never shipped with fully feature-complete and consistent ExAll() support in all its file systems until AmigaOS 3.2.2 (2023). Similar challenges exist for the ExAll() user's side in following the complex protocol documented in the example code (see section EXAMPLE below). There is very little room for error and very little to gain by using ExAll(), compared to the use of the Examine() .. ExNext() loop.

If you have a choice, try the Examine() .. ExNext() approach first before you decide to give ExAll() a chance. ExAll() is the perhaps most complex dos.library function and the complexity of using it correctly and successfully require particularly careful design, implementation and verification. You may want to invest this kind of effort elsewhere.

The advantage of ExAll() is in that most of the work being done happens inside the file system Process itself. Unlike calling Examine() and then ExNext() over and over again, ExAll() does not have to incur a DosPacket exchange delay for every directory entry. That said, the file system still has to produce the directory entry records by following the metadata structures on the storage medium, which, e.g. for the FFS, still involves plenty of individual disk blocks to be read and processed. The DirCache mode of the FFS features an optimized directory layout which lends itself to filling the ExAll() buffer very efficiently and quickly. However, few file systems are able to provide directory records quite so efficiently and may suffer from other drawbacks, which is certainly the case for the DirCache mode of the FFS.

ExAll() will fall back onto emulating the directory scanning and filtering if the file system does not feature built-in support for it, using Examine() .. ExNext(). Worst case, the file system will only be marginally faster in filling the ExAllData buffer than your own Examine() .. ExNext() calls. Part of the complexity of what the ExAll() function accomplishes is in dealing with the emulation and what it entails. You may want to avoid this.

In V36, there were problems with ExAll (particularily with eac_MatchString, and ed_Next with the ram-disk and the emulation of it in dos.library for handlers that do not support the packet. It is advised you only use this under V37 and later.

The V39 DirCache variant of the FFS had a bug in ExAll that required to first Examine() the Lock before passing it to ExAll. This was fixed in V40, with a patch in SetPatch.

The V40 version passed an invalid argument to the dos.library error report handler in case of trouble, potentially causing crashes or other mischiefs. This was fixed in V47, with a patch in SetPatch V45.

See note above regarding extensions to the Type parameter.

Examine(), ExNext(), ExamineFH(), MatchPatternNoCase(), ParsePatternNoCase(), AllocDosObject(), ExAllEnd(), utility.library/CallHookPkt, <utility/hooks.h>