<< Previous | Next >>

fat_Seek

int fat_Seek( FATfile *file, long pos, int whence );

Description

Positions the internal file position pointer. fat_Seek() will allocate clusters to the file if necessary, but will not move the position pointer beyond the original end of file (EOF) unless doing a SEEK_RAW. In all other cases, extending the pointer past the original EOF will preallocate the space that would be needed to position the pointer as requested, but the pointer will be left at the original EOF and the file length will not be changed. If this occurs, an EOF error will be returned to indicate the space was allocated but the pointer was left at the EOF.

Parameters

file

Pointer to the file structure of the open file.

pos

Position value in number of bytes (may be negative). This value is interpreted according to the third parameter, whence.

whence

Must be one of the following:

• SEEK_SET - pos is the byte position to seek, where 0 is the first byte of the file. If pos is less than 0, the position pointer is set to 0 and no error code is returned. If pos is greater than the length of the file, the position pointer is set to EOF and error code -EEOF is returned.

• SEEK_CUR - seek pos bytes from the current position. If pos is less than 0 the seek is towards the start of the file. If this goes past the start of the file, the position pointer is set to 0 and no error code is returned. If pos is greater than 0 the seek is towards EOF. If this goes past EOF the position pointer is set to EOF and error code -EEOF is returned.

• SEEK_END - seek to pos bytes from the end of the file. That is, for a file that is x bytes long, the statement:

  fat_Seek (&my_file, -1, SEEK_END);

will cause the position pointer to be set at x-1 no matter its value prior to the seek call. If the value of pos would move the position pointer past the start of the file, the position pointer is set to 0 (the start of the file) and no error code is returned. If pos is greater than or equal to 0, the position pointer is set to EOF and error code -EEOF is returned..

• SEEK_RAW - is similar to SEEK_SET, but if pos goes beyond EOF, using SEEK_RAW will set the file length and the position pointer to pos.

Return Value

0: success.
-EIO: device I/O error.
-EINVAL: file, pos, or whence contain invalid values.
-EPERM: the file is locked or writes are not permitted.
-ENOENT: the file does not exist.
-EEOF: space is allocated, but the pointer is left at original EOF.
-ENOSPC: no space is left on the device to complete the seek.
-EBUSY: the device is busy (Only if non-blocking).
-EFSTATE: if file in inappropriate state (Only if non-blocking).

Library

FAT.LIB

See Also

fat_Open, fat_Read, fat_Write, fat_xWrite