[DOC] ff_truncate documentation inadequate

[carlk3]

Describe the issue
Please describe the issue and expected clarification in concise language.

ff_truncate has important restrictions that are not mentioned. Since this behavior is non-standard, I believe it would be best to state the restrictions rather than leave them unsaid. They might come as a surprise to someone used to, say, POSIX.

ff_truncate says that it " Opens a file for writing...", but technically, that is not true. It actually opens a file for append, as in ff_fopen pcMode "a" or "a+". Therefore, because of the limitations of fseek and ff_rewind, if the file already exists and it is opened with ff_truncate it is impossible to move the file position to the absolute beginning of the file or to any position between there and the end of the preexisting file.

Also, it's non-standard that ff_truncate returns a pointer to an opened file. See truncate or File Size.

Reference
Please attach the URL at which you are experiencing the issue.

https://www.freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_FAT/stdio_API/ff_truncate.html

Screenshot
If applicable, please attach screenshot.

Browser

• Browser: [e.g. Chrome]
• Version: [e.g. 80.0.3987.132]

[AniruddhaKanhere]

Hello @carlk3,

Apologies for the late reply. We somehow missed looking at the issues in this repository.

It seems that you are correct about ff_truncate opening the file in append mode - which does allow reading and writing. We will update the documentation to say that.
I am not sure that I understand when you say that there is a limitation with ff_rewind. Looking at the code, it seems that ff_rewind can be called after opening the file with ff_truncate. Could you help me by pointing out the issue that you are talking about?

We are aware that it is non-standard for ff_truncate to return a pointer to an opened file. It was done because when ff_truncate fails it is unclear by the return code whether the file is left in an open state or not. Returning file pointer gets around that issue.

Tagging @htibosch here so that he can also chime in and correct me if I am wrong.

Thanks,
Aniruddha

[carlk3]

Hi,

On Thu, Feb 15, 2024 at 12:10 PM Aniruddha Kanhere notifications@github.com wrote:

...
I am not sure that I understand when you say that there is a limitation with ff_rewind. Looking at the code, it seems that ff_rewind can be called after opening the file with ff_truncate. Could you help me by pointing out the issue that you are talking about?

This issue: [DOC] ff_fseek() documentation inadequate

Append mode is weird. In append mode, output to files is always appended sequentially to the end of the file, regardless of the file position. However, there should be a way to move the file position to the absolute beginning of the file for reading, but there is not. The point of this Issue is that there are major differences in the behavior if ff_truncate "Opens a file for writing" vs "Opens a file for appending" (which is what it does).

...

[htibosch]

ff_truncate() returns a file handle: that was done because it is handy for many users.
It save a call to ff_fopen().

Seek past the end of file: I didn't want to implement that because it is error prone.

if the file already exists and it is opened with ff_truncate it is impossible to move the file position to the absolute beginning of the file or to any position between there and the end of the preexisting file.

I would classify that as a bug, it is not what you want.

I'm sorry for being brief.

[bhoomrs]

Updated the website to include behaviour and restrictions of the FreeRTOS-specific ff_truncate() function.