Begin iteration of files in a specified long file name path.

int BIOS_LFN_Findfirst (const char far *filename,
                        LFN_FILE_FIND far *find),
                        unsigned char     lock_the_node);



Pointer to null terminated ASCII file name pattern for search which may contain * and ? wild card characters.


Pointer to a LFN_FILE_FIND structure that will be initialized inside this API call.


Boolean set non-zero to leave the directory node lock protected against delete on successful return.   Set to zero to leave the directory unlocked on return.

Return Value

0:  No file found
1:  Success


This function and the BIOS_LFN_Findnext provide access to the long file names.   When the lock_the_node Boolean is FALSE then these functions behave similar to the DOS findfirst/findnext functions provided by the compiler C-libraries.   A significant difference is that the BIOS_LFN_Find_Done function must be called to prevent a memory leak if the search is terminated before the end.

When the lock_the_node Boolean is TRUE then these functions behave similar to the BIOS_Fast_Findfirst and BIOS_Fast_Findnext functions.    A delete protection lock is placed on the directory being scanned by these functions.

This function is reentrant.   However, eventually the system will run out of file system resources (e.g. directory nodes) if too many sessions are simultaneously active.

For PLP drives, setting the lock_the_node non-zero will make the BIOS_LFN_Findnext function operate more efficiently.   When lock_the_node here is zero, the BIOS_LFN_Findnext function must rescan the directory block list from the top on each call in order to reestablish its cursor position within the directory list.   (This rescan covers for possible block movement that may have occurred on the PLP drive since the previous call.)   For directories with lots of files, this could require some significant amount of FAT reading on each BIOS_LFN_Findnext call.


    The BIOS_LFN_Find_Done function must be called if the Findfirst/Findnext sequence is stopped prior to these iteration functions returning with a zero ("File not found") indication.   This is important so that the directory can be unlocked and system resources released!

See Also


This library function invokes a RTOS software interrupt.   Refer to this RTOS API function's documentation for more details.

Supported since or modified in @CHIP-RTOS version


Supported by @CHIP-RTOS C Library since version


This API List
List of C Libraries
@CHIP-RTOS Main Index

End of document