Previous

Next

Function RTFExtendEx

RTFExtendEx extends a file with a contiguous chain of clusters:

int RTFExtendEx(RTFHANDLE File, const ULARGE_INTEGER * Length);

Parameters

File

References the open file to be extended.

Length

Specifies by how many bytes the file is to be extended relative to the current file pointer.

return value

If the function succeeds, the return value is RTF_NO_ERROR. If the function fails, the return value is a negative error code.

If RTFExtendEx cannot find a chain of free clusters long enough to satisfy the request, error RTF_DISK_FULL is returned. However, it may still be possible to extend the file by some other means (e.g., RTFSeekEx or RTFWrite); only contiguous extension of the file is not possible.

RTFExtendEx will add *Length to the current file pointer value. If fewer than required clusters are currently allocated for the file, new clusters are allocated for the file. The allocation is guaranteed to consist of a single cluster chain. If the file has a current file size of 0, the file will be unfragmented after this call. If, however, clusters are already allocated, RTFExtendEx will attempt to allocate the new cluster chain immediately following the existing last cluster chain. If this fails, the new cluster chain is allocated somewhere else and the file will not be contiguous.

Files allocated contiguously may exhibit improved and possibly even deterministic access times (see Advanced Topics for a detailed discussion on file I/O performance considerations). However, RTFExtendEx itself can take substantially longer than RTFSeek to extend a file. In particular on volumes with only little free space, reading the complete FAT (or the cluster bitmap on exFAT) may be required.

General File I/O

Function RTFSeek

Function RTFCommit