FSAppendFile

Syntax

#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
                );

Parameters

client Pointer to the client buffer.
block Command block.
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.
fileHandle File handle.
errHandling Auto error handling flag. Only indicated errors are returned.
asyncParams (Async API only) Notification parameters for an asynchronous call.

Return Values

Sync API : Return values / Async API: Callback return values

Non-negative value ( ≥ 0 ) Newly appended size (newly added preallocation area [Byte] divided by size).
FS_STATUS_CANCELED Command was canceled.
FS_STATUS_ACCESS_ERROR Access mode is invalid (e.g. Opened file is not writable mode).
FS_STATUS_FILE_TOO_BIG Total file size reaches over maximum file size.
FS_STATUS_STORAGE_FULL Not enough storage space can be allocated on the device.
FS_STATUS_JOURNAL_FULL Journaling space is full and new journaling block cannot be allocated.
FS_STATUS_MEDIA_NOT_READY (Only for manually mounted devices) Media is not present.
FS_STATUS_MEDIA_ERROR (Only for manually mounted devices) Media is in some inaccessible condition.
FS_STATUS_DATA_CORRUPTED (Only for manually mounted devices) The data is corrupted beyond repair. The volume needs format.
FS_STATUS_WRITE_PROTECTED (Only for manually mounted devices) Media is write protected.

Async API: Immediate return values

FS_STATUS_OK Successfully issued the request.
FS_STATUS_FATAL_ERROR The argument is invalid.

Description

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, return 0 without adding anything (=FS_STATUS_OK). 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 FSGetStatFile or FSGetStat. 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. Note that 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 0x7fffffff.

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 FS_STATUS_STORAGE_FULL.

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 FSAsyncParams.

Note that this function returns FS_STATUS_UNSUPPORTED_CMD if the underlying file system does not support the pre-allocation feature.

Do Not Call From

FSAppendFile

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.

FSAppendFileAsync

None.

See Also

File/Directory operations
Rules and Conventions
FSOpenFile
FSGetStatFile
FSCloseFile

Revision History

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 -> FSAsyncParams.
2012/02/20 Initial version.


CONFIDENTIAL