#include <cafe/fs.h> FSStatus FSAppendFile( FSClient *client, FSCmdBlock *block, FSSize size, FSCount count, FSFileHandle fileHandle, FSRetFlag errHandling ); FSStatus FSAppendFileAsync( FSClient *client, FSCmdBlock *block, FSSize size, FSCount count, FSFileHandle fileHandle, FSRetFlag errHandling, const FSAsyncParams *asyncParams );
|client||Pointer to the client buffer.|
|size||Size of members to append at the end of a file [bytes].|
|count||Number of members to append at the end of a file.|
|errHandling||Auto error handling flag. Only indicated errors are returned.|
|asyncParams||(Async API only) Notification parameters for an asynchronous call.|
|Non-negative value ( ≥ 0 )||Newly appended size (newly added preallocation area [Byte] divided by size).|
||Command was canceled.|
||Access mode is invalid (e.g. Opened file is not writable mode).|
||Total file size reaches over maximum file size.|
||Not enough storage space can be allocated on the device.|
||Journaling space is full and new journaling block cannot be allocated.|
||(Only for manually mounted devices) Media is not present.|
||(Only for manually mounted devices) Media is in some inaccessible condition.|
||(Only for manually mounted devices) The data is corrupted beyond repair. The volume needs format.|
||(Only for manually mounted devices) Media is write protected.|
||Successfully issued the request.|
||The argument is invalid.|
Add the current file size to the end of the specified file to allocate an area.
The size to allocate is determined by arguments: size and count (size * count [Byte]).
If size or count indicates
0 without adding anything (=
If the already allocated area has space more than specified, return
0 without adding anything.
If not, allocate the amount that is short. However, due to the block size of the file system, more space than specified may be allocated
You can check the size of a pre-allocated area by looking at
alloc_size in the
FSStat structure obtained by
The value returned when
FSAppendFile is successful is obtained by dividing the newly allocated area [Byte] by size.
Because the value gets rounded off, note that 0 may return when size is big even if a pre-allocated area is actually allocated.
By specifying the size to 1, you can accurately check the return value in bytes.
FSStatus is a signed 32-bit value and this function can returns up to
0x7fffffff as a positive value.
If the value to be returned exceeds
0x80000000, this function returns
Processing is successful if the return value is 0 or more; a pre-allocated area that is greater than the specified size (size * count [Byte]) plus the file size should be appended.
If the data space cannot be allocated, this function returns the error
Both a sync and async style API are provided. To use the async API, set the user callback and parameters in asyncParams.
For more information, see
Note that this function returns
FS_STATUS_UNSUPPORTED_CMD if the underlying file system does not support
the pre-allocation feature.
|Thread that displays graphics||Do not call this function from a thread that displays graphics. This function may block indefinitely in error cases and the application must be able to display appropriate messages.|
|Thread that handles system messages||Do not call this function from a thread that handles system messages. This function may block indefinitely in error cases and the application must be able to handle system events such as shutdown.|
|Callbacks||Do not call this function from any callback function.|
|Interrupt handler||Do not call this function from any interrupt handler.|
|Exception handler||Do not call this function from any exception handler.|
2014/09/16 Added "Thread that displays graphics" and "Thread that handles system messages" to "Do not call from".
2013/05/23 Added FS_STATUS_DATA_CORRUPTED to return values.
2013/05/20 Added a note about restriction of the return value.
2013/05/20 Added FS_STATUS_MEDIA_NOT_READY and FS_STATUS_WRITE_PROTECTED to return values.
2013/05/08 Automated cleanup pass.
2013/03/04 Fixed Description.
2013/01/10 Added "Callback" to "Do not call from".
2012/08/25 Fixed Arguments "size" and "count", and Description.
2012/07/19 Readability and correctness cleanup.
2012/03/30 Fixed type name FSNotificationParams ->
2012/02/20 Initial version.