MatchFirst

Finds file that matches pattern (V36)

Locates the first file or directory that matches a given pattern. MatchFirst() is passed your pattern (you do not pass it through ParsePattern() - MatchFirst() does that for you), and the control structure. MatchFirst() normally initializes your AnchorPath structure for you and returns the first file that matched your pattern, or an error. Note that MatchFirst()/MatchNext() are unusual for AmigaDOS in that they return 0 for success, or the error code (see <dos/dos.h>), instead of the application getting the error code from IoErr().

Pattern matching is performed by MatchPatternNoCase().

When looking at the result of MatchFirst()/MatchNext(), the ap_Info field of your AnchorPath has the results of an Examine() of the object. You normally get the name of the object from AnchorPath->ap_Info.fib_FileName, and the directory it's in from AnchorPath->ap_Current->an_Lock. To access this object, normally you would temporarily CurrentDir() to the Lock, do an action to the file/dir, and then CurrentDir() back to your original directory. This makes certain you affect the right object even when two volumes of the same name are in the system. You can use AnchorPath->ap_Buf (with AnchorPath->ap_ap_Strlen) to get a name to report to the user.

To initialize the AnchorPath structure (particularily when reusing it), set ap_BreakBits to the signal bits (SIGBREAKF_CTRL_C, etc.) that you want MatchFirst() and MatchNext() to stop scanning on, or 0 if no signal sent should result in the scanning process to stop. ap_FoundBreak should be cleared if ap_BreakBits is used. When calling MatchFirst(), ap_Flags should always be set to 0.

The following flags are defined for the AnchorPath->ap_Flags structure member:

APF_DOWILD (not implemented)

Do not use this flag: it serves no purpose at all due to changes made to the directory scanning code late in Kickstart 2.0 (V36) development. The published example source code which makes use of it dates back to the time when it still had a purpose. While is is common to see example code set AnchorPath->ap_Flags = APF_DOWILD, it has the same effect as setting ap_Flags to 0.

APF_ITSWILD (set by MatchFirst, used by MatchNext)

MatchFirst() will set this flag if it finds AmigaDOS wildcard pattern characters in the "pat" parameter string.

As the name implies, MatchFirst() is designed to find directory entries which match a pattern. This can lead to unexpected behaviour if, for example, the name of an existing directory entry contains wildcard patterns which then are misinterpreted (see the WARNING section).

MatchNext() will check if the APF_ITSWILD flag is set and then proceed to find every directory entry which matches the pattern. You can prevent this by clearing the flag before calling MatchNext().

APF_DODIR (used by MatchNext)

You can set this flag if MatchFirst() or MatchNext() found a directory entry and the directory scanning process should continue by entering and eventually returning from this directory.

APF_DIDDIR (set by MatchNext)

This flag will be set after scanning had entered a directory and reached the end of the directory. This is used by, for example, the "Delete" CLI command as an indication that it can now delete the directory whose contents it has just deleted.

APF_NOMEMERR (set by MatchNext)

This flag will be set if the directory scanning process fails to allocate sufficient memory for its data structures or if obtaining a Lock on a volume, file or directory has failed. Both types of errors are lumped together and will make MatchNext() stop and return ERROR_NO_FREE_STORE. Calling MatchNext() again will keep returning an error.

APF_DODOT (not implemented)

Do not use this flag. This feature was not implemented in Kickstart 2.0 (V36) and has never been implemented since.

APF_DirChanged (set by MatchNext)

This flag will be set if the directory being scanned has changed since MatchFirst() or MatchNext() has been called. Otherwise, it will be cleared.

APF_FollowHLinks (used by MatchNext)

If you tell MatchNext() to continue directory scanning by entering a directory, it will not enter a hard linked directory unless you also set the APF_FollowHLinks flag. Use with caution: hard linked directories can cause the directory scanning process to enter an infinite loop.

If you want to have the full path name of the files you found filled in, allocate a buffer at the end of this structure, and put the size of it into AnchorPath->ap_Strlen:

If you do not need the full path name, make sure you set ap_Strlen to zero. In this case, the name of the file, and stats are available in AnchorPath->ap_Info, as per usual.

Then call MatchFirst() and then afterwards, MatchNext() with this structure. You should check the return value each time and take the appropriate action, ultimately calling MatchEnd() when there are no more files, or you are done. You can tell when you are done by checking for the normal AmigaDOS return code ERROR_NO_MORE_ENTRIES.

See ParsePattern() for more information on the patterns.

pat

Pattern to search for. That pattern can be a path name such as "Fonts:", "DEVS:DOSDrivers", or even just the plain name of a file or directory. You can also use AmigaDOS wildcard patterns within a path name such as "SYS:Classes/#?/#?.gadget".

AnchorPath

Placeholder for search. MUST be longword aligned!

error

0 for success or error code. (Opposite of most AmigaDOS calls!)

MatchFirst() is designed for finding directory entries which match an AmigaDOS wildcard pattern, but it is also useful for traversing a directory tree. When both are combined, by accident, unexpected behaviour will result which you may want to avoid:

The CLI "Delete" command makes use of MatchFirst()/MatchNext(), and directory entries which contain AmigaDOS wildcard pattern characters, such as "(example)", present a problem. If you enter "Delete (example)" in the shell, with an actual directory entry named "(example)", MatchFirst() will scan the current directory without picking up the entry called "(example)". This is because MatchFirst() identifies "(example)" as an AmigaDOS wildcard pattern, and not as the name of a directory or directory entry. Furthermore, there is no way to tell MatchFirst() by way of the AnchorPath->ap_Flags settings to treat "(example)" like a name rather than a pattern.

The only workaround available here is to use wildcard pattern character escape characters. Adding the "'" (apostrophe) character in front of every single AmigaDOS wildcard pattern character will turn it into a normal character. For example, "'(example')" will make MatchFirst() look for the directory entry named "(example)".

It is not safe to call this function from a Task!

Both MatchFirst() and MatchNext() will call MatchPatternNoCase(), which may end up using 1500 bytes of stack space. You should make sure that more than 1500 bytes of stack space are available before you call MatchFirst() or MatchNext().

Both MatchFirst() and MatchNext() return an error code, indicating completion of the scan operation (= ERROR_NO_MORE_ENTRIES), success (= 0) and failure. This does not mean, however, that IoErr() could be used in place of the error code returned by the respective function. This is never the case. Only use the return code of the MatchFirst() and MatchNext() functions.

MatchFirst() and MatchNext() may show undefined behaviour if you use a pattern which features a file or link in place of what should be a directory. For example, the pattern "volume:directory/file1/file2" will make MatchFirst() stop when it attempts to examine the contents of "file1", expecting it to be a directory. What happens next is up to the file system implementation, which may or may not flag this attempt as an error. If the file system considers it an error, then MatchFirst() and MatchNext() will abort the scanning operation, returning ERROR_NO_MORE_ENTRIES. This behaviour is indistinguishable from MatchFirst() and MatchNext() finding an empty directory.

If the buffer you provided in AnchorPath->ap_Buf, with AnchorPath->ap_StrLen indicating its size, is too small, MatchFirst()/MatchNext() will stop and return an error.

MatchFirst() and MatchNext() will call ParsePattern(), as well as MatchPatternNoCase(). Any errors these functions may produce will cause MatchFirst() and MatchNext() to return an error code.

When accessing the Lock and the name of the directory entry found by MatchFirst()/MatchNext(), the following is the correct method:

Note that the name comes from AnchorPath->ap_Info and not from AnchorPath->ap_Current->an_Info.

Patterns with trailing slashes may cause MatchFirst()/MatchNext() to return with an AnchorPath->ap_Current->an_Lock on the object, and a filename of the empty string ("").

MatchFirst() will change the error code value which can be retrieved by IoErr() if the function fails. Note that the return value of MatchFirst() already provides you with the error code, and you do not need to call IoErr().

In V36, there were a number of bugs with MatchFirst()/MatchNext(). One was that if you entered a directory with a name like "df0:l" using APF_DODIR, it would re-Lock the full string "df0:l", which can cause problems if the disk has changed. It also had problems with patterns such as #?/abc/def - the ap_Current->an_Lock would not be on the directory def is found in. ap_Buf would be correct, however. It had similar problems with patterns with trailing slashes. These have been fixed for V37 and later.

A bug that has not been fixed for V37 concerns a pattern of a single directory name (such as "L"). If you enter such a directory via APF_DODIR, it re-locks "L" relative to the current directory. Thus, you must not change the current directory before calling MatchNext() with APF_DODIR in that situation. If you are not using APF_DODIR to enter directories, you can ignore this. This may be fixed in some upcoming release.

In case the pattern does not contain any wildcards and refers to a softlink that cannot be resolved, MatchFirst() returns ERROR_OBJECT_NOT_FOUND. A workaround is to replace the file name by a pattern that resolves only to this particular file name, e.g. foo -> foo(|). Heed the warning regarding names which contain wildcard pattern characters.

MatchNext(), ParsePattern(), Examine(), CurrentDir(), Examine(), MatchEnd(), ExNext(), <dos/dos.h>, <dos/dosasl.h>