<< Previous | Next >>

fshift

int fshift( File * f, int len, void * buf );

Description

Delete data from the start of a file opened for writing. Optionally, the data that was removed can be read into a buffer. The "current position" of the file descriptor is adjusted to take account of the changed file offsets. If the current position is pointing into the data that is removed, then it is set to zero, i.e., the start of data immediately after the deleted section.

The specified file must not be opened with other file descriptors, otherwise an EBUSY error is returned. The exception to this is if FS2_SHIFT_DOESNT_UPDATE_FPOS is defined before #use fs2.lib. If defined, multiple file descriptors can be opened, but their current position will not be updated if fshift() is used. In this case, the application should explicitly use fseek() on all file descriptors open on this file (including the one used to perform the fshift()). If this is not done, then their current position is effectively advanced by the number of characters shifted out by the fshift().

The purpose of this function is to make it easy to implement files which worm their way through the filesystem: adding at the head and removing at the tail, such that the total file size remains approximately constant.

Surprisingly, it is possible for an out-of-space error to occur, since the addition of the journaling (meta-data) entry for the shift operation may cause an error before deleted blocks (if any) are made available.

Parameters

f

Pointer to file descriptor (initialized by fopen_wr() or fcreate()).

len

Length of data to remove (0 to 32767 inclusive).

*buf

Data buffer located in root data memory or stack. This must be dimensioned with at least len bytes. This parameter may also be null if the deleted data is not needed.

Return value

len: Success.
<len: Partial success - returns amount successfully deleted. errno gives further details (probably ENOSPC)
0: Error or len was zero.

ERRNO values

EBADFD - File descriptor not opened, or is read-only.
EINVAL - len less than zero.
0 - Success, but len was zero.
EIO - I/O error.
ENOSPC - extent out of space.
EBUSY - file opened more than once. This is only possible if FS2_SHIFT_DOESNT_UPDATE_FPOS is not defined, which is the default case.

Library

FS2.LIB

See Also

fread (FS2), fwrite (FS2)