#include <cafe/fs.h> FSStatus FSWriteFile( FSClient *client, FSCmdBlock *block, const void *source, FSSize size, FSCount count, FSFileHandle fileHandle, FSFlag flag, FSRetFlag errHandling ); FSStatus FSWriteFileAsync( FSClient *client, FSCmdBlock *block, const void *source, FSSize size, FSCount count, FSFileHandle fileHandle, FSFlag flag, FSRetFlag errHandling, const FSAsyncParams *asyncParams );
|client||Pointer to the client buffer.|
|source||Pointer to data array to write into the file stream. This must be aligned properly. See description.|
|size||Size of one array member [bytes].|
|count||Number of array members to write.|
|fileHandle||Handle of the file to write from.|
|flag||Bitfield of flag values. No effective flag is defined yet.|
|errHandling||Auto error handling flag. Only indicated errors are returned.|
|asyncParams||(Async API only) Notification parameters for an asynchronous call.|
|Non-negative value ( ≥ 0 )||Number of elements write.|
||The command was canceled.|
||Access mode is invalid (e.g. Opened file is not writable mode).|
||Total file size is greater than the maximum file size.|
||Associated file system does not support this function.|
||Data space cannot be allocated.|
||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.|
||Successfully issued request.|
||The argument is invalid.|
Writes data to the current file position of file stream designated by fileHandle from the data array designated by source. The file position of the stream is advanced by the number of characters written. If an error occurs, the file position is indeterminate. If a partial element is write, its value is indeterminate. If you concurrently called another API which may change file position of the same file handle, the result is indeterminate.
If size or count is zero, this function returns zero (=
FS_STATUS_OK) without writing anything, but it will be followed by
physical seek motion on the device to the requested location if the device supports it.
NULL can be specified to source if and
only if size or count is zero.
When specifying the access mode for
FSOpenFile to be "
a" or "
a+" and executing
the size and count greater than 0, it should start writing from the end of a file.
When specifying the access mode to be "
a" or "
FSOpenFile and executing
the size or count equal to 0, WFS and FAT should start writing from the end of a file;
however, the position of a file in other file systems is undefined.
Of critical importance are the alignment requirements for write data buffers.
Both the CPU and device-specific alignment requirements must be satisfied for all FS data transactions.
Both allocated data buffer address and size, which are specified by source, must be aligned by
For good performance, allocate the source buffer on the heap.
As mentioned above, the address and size of data buffer must be aligned by
However, the total access size which is calculated by size and count does not have to be aligned by this value.
Large file write transaction will be automatically paused when a command with higher priority is queued to the same client.
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
|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/12/10 Added FS_STATUS_UNSUPPORTED_CMD to return values.
2013/05/23 Added FS_STATUS_DATA_CORRUPTED to return values.
2013/05/20 Added FS_STATUS_MEDIA_NOT_READY to return values.
2013/05/08 Automated cleanup pass.
2013/01/19 Added description that
NULL can be specified to source if and only if size or count is zero.
2013/01/10 Added "Callback" to "Do not call from".
2012/12/21 Updated access mode information.
2012/07/31 Added precautions that concurrent API calls may make the result indeterminate. Noted about command priority.
2012/07/20 Readability and correctness cleanup.
2011/12/12 Initial version.