<< Previous | Next >>

fat_CreateFile

int fat_CreateFile( fat_part * part, char * filename, long alloc_size, FATfile * file );

Description

Creates a file if it does not already exist. The parent directory must already exist.

In non-blocking mode, if file is NULL, only one file or directory can be created at any one time, since a single static FATfile is used for temporary storage. Each time you call this function, pass the same dirname pointer (not just the same string contents).

Valid filenames are limited to an 8 character filename and 3 character extension separated by a period; this is commonly known as the "8.3" format. Examples include but are not limited to "12345678.123", "filename.txt", and "webpage1.htm".

Parameters

part

Pointer to the partition being used.

filename

Pointer to the full pathname of the file to be created.

alloc_size

Initial number of bytes to pre-allocate. Note that at least one cluster will be allocated. If there is not enough space beyond the first cluster for the requested allocation amount, the file will be allocated with whatever space is available on the partition, but no error code will be returned. If not even the first cluster is allocated, the -ENOSPC error code will return. This initial allocation amount is rounded up to the next whole number of clusters.

file

If not NULL, the created file is opened and accessible using this handle.

If NULL, the file is closed after it is created.

Return Value

0: success.
-EINVAL: part, filename, alloc_size, or file contain invalid values.
-ENOENT: the parent directory does not exist.
-ENOSPC: no allocatable sectors were found.
-EPERM: write-protected, trying to create a file on a read-only partition.
-EBUSY: the device is busy (non-blocking mode only).
-EFSTATE: if non-blocking, but a previous sequence of calls to this function (of fat_CreateFile) has not completed but you are trying to create a different file or directory. You must complete the sequence of calls for each file or directory i.e. keep calling until something other than -EBUSY is returned. This code is only returned if you pass a NULL file pointer, or if the file pointer is not NULL and the referenced file is already open.
-EPATHSTR: Bad file/directory path string. Valid filenames are limited to the 8.3 format.

Other negative values indicate I/O error, etc.

Library

FAT.LIB

See Also

fat_Open, fat_ReadDir, fat_Write