www.beck-ipc.com

@CHIP-RTOS C Library - BIOS API


BIOS_LFN_Findfirst

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);

Parameters

filename

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

find

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

lock_the_node

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

Comments

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.

CAUTION:

    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

RTOS API

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

    SC12SC13SC11SC1x3SC2x
    n/an/an/aV0.91V1.00

Supported by @CHIP-RTOS C Library since version

    CLIB
    V2.02

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


End of document