www.beck-ipc.com

@CHIP-RTOS C Library - BIOS API


BIOS_Fast_Findfirst

Begins a file system directory scan with node locked.

int BIOS_Fast_Findfirst (const char far *filename,
                          FILE_FIND far *find,
                          unsigned int attributes );

Parameters

filename

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

find

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

attributes

File attributes (provisional, not used!)

Return Value

0:  No file found
1:  Success

Comments

This function and the BIOS_Fast_Findnext provide a slightly faster findfirst/next access than do the DOS compatible functions available on software interrupt 0x21.   (Historically, this function was significantly faster than the @Chip-RTOS's DOS findfirst/findnext implementation.   But since this time the DOS functions have been corrected so the speed advantage is no longer an issue here.)   This function places a delete protection lock on the directory being searched.

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.

These functions work in a similar way to the DOS SWI 0x21 findfirst/next functions.   BIOS_Fast_Findfirst must be called first.   Then the BIOS_Fast_Findnext is used repeatedly as required to iterate through all the files in a directory matching the specified filename pattern.

When a lock protection against directory delete is not desired between calls to the file iteration functions, the normal C-library findfirst/findnext functions may instead be used. (Or BIOS_LFN_Findfirst functions for SC1x3/SC2x case.)

CAUTION:

The BIOS_Fast_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 file system resources released!

SC1x3/SC2x Comments

Long file names can be accessed with the BIOS_LFN_Findfirst function. Long file names cannot be accessed with this API. Only DOS 8.3 file names can be accessed with this API.

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
    V1.20V1.20V1.20V0.91V1.00

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


End of document