Jump to main content

##

# 1.2.7.4.29 SYS_FS_DirSearch Function

## C

    SYS_FS_RESULT SYS_FS_DirSearch
    (
        SYS_FS_HANDLE handle,
        const char * name,
        SYS_FS_FILE_DIR_ATTR attr,
        SYS_FS_FSTAT *stat
    );

## Summary

Searches for a file or directory.

## Description

This function searches for the requested file or directory. The file or directory is specified in the attr parameter, which is of type SYS_FS_FILE_DIR_ATTR.

The file system supports 8.3 file name(Short File Name) and also long file name. 8.3 filenames are limited to at most eight characters, followed optionally by a filename extension consisting of a period . and at most three further characters. If the file name fits within the 8.3 limits then generally there will be no valid LFN for it.

For FAT File system

- If LFN is used the stat structure's altname field will contain the short file name and fname will contain the long file name. The "lfname" member of the SYS_FS_FSTAT is not applicable for FAT. It has to be initialized to NULL before calling the API. If "lfname" is not NULL, then first byte of lfname will be set to zero indicating no file found.

For other File systems based on thier implementation -If LFN is used then the "lfname" member of the SYS_FS_FSTAT structure should be initialized with the address of a suitable buffer and the "lfsize" should be initialized with the size of the buffer. Once the function returns, the buffer whose address is held in "lfname" will have the file name(long file name).

- The stat structure's fname field will contain the SFN and if there is a valid LFN entry for the file then the long file name will be copied into lfname member of the structure.

## Precondition

A valid directory handle must be obtained before searching the directory.

## Parameters

Param | Description
--- | ---
handle | directory handle obtained during directory open.
name | name of file or directory needed to be searched. The file name can have wild card entries as follows:
* | Indicates the rest of the filename or extension can vary (e.g. FILE.*)
? | Indicates that one character in a filename can vary (e.g. F?LE.T?T)
attr | Attribute of the name of type SYS_FS_FILE_DIR_ATTR. This attribute specifies whether to search a file or a directory. Other attribute types could also be specified.
stat | Pointer to SYS_FS_FSTAT, where the properties of the directory/file will be populated after the SYS_FS_DirSearch function returns successfully.

## Returns

SYS_FS_RES_SUCCESS - Indicates that the file or directory was found. The stat parameter will contain information about the file or directory.

SYS_FS_RES_FAILURE - Indicates that the file or directory was not found. The reason for the failure can be retrieved with SYS_FS_Error or SYS_FS_FileError.

## Example

    SYS_FS_HANDLE dirHandle;
    SYS_FS_FSTAT stat;

    dirHandle = SYS_FS_DirOpen("/mnt/myDrive/Dir1");

    if(dirHandle != SYS_FS_HANDLE_INVALID)
    {
        // Directory open is successful
    }

    if(SYS_FS_DirSearch(dirHandle, "FIL*.*", SYS_FS_ATTR_ARC, &stat) == SYS_FS_RES_FAILURE)
    {
        // Specified file not found or reached end of directory
    }
    else
    {
        // File found. Read the complete file name from "stat.fname" or "stat.lfname" and
        // other file parameters from the "stat" structure
    }

## Remarks

None.