User`s manual

158 digi.com File Systems
files on the device and unmount all mounted FAT partitions. Unmounting the device is the safest method
for shutting down after using the device.
10.2.4.2.3 Going to a Specified Position in a File
The position pointer is at the start of the file when it is first opened. Two API functions, fat_Tell()
and fat_Seek(), are available to help you with the position pointer.
The fat_Tell() function does not change the position pointer, but reads its value (which is the number
of bytes from the beginning of the file) into the variable pointed to by &pos. Zero indicates that the posi-
tion pointer is at the start of the file. The first parameter, &my_file, is the file handle already opened by
fat_Open().
The fat_Seek() function changes the position pointer. Clusters are allocated to the file if necessary, but
the position pointer will not go 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, the error code -EEOF is returned to indicate the space was allocated but the
pointer was left at the EOF. If the position requires allocating more space than is available on the device,
the error code -ENOSPC is returned.
The first parameter passed to fat_Seek() is the file handle that was passed to fat_Open(). The sec-
ond parameter, pos, is a long integer that may be positive or negative. It is interpreted according to the
value of the third parameter. The third parameter 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 state-
ment:
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. This adds whatever data exists on the allocated space onto the
end of the file..
fat_Tell(&my_file, &pos);
fat_Seek(&my_file, pos, SEEK_SET);