FSWriteFileWithPos

Syntax

#include <cafe/fs.h>

FSStatus FSWriteFileWithPos(
                FSClient                        *client,
                FSCmdBlock                      *block,
                const void                      *source,
                FSSize                          size,
                FSCount                         count,
                FSFilePosition                  fpos,
                FSFileHandle                    fileHandle,
                FSFlag                          flag,
                FSRetFlag                       errHandling
                );
FSStatus FSWriteFileWithPosAsync(
                FSClient                        *client,
                FSCmdBlock                      *block,
                const void                      *source,
                FSSize                          size,
                FSCount                         count,
                FSFilePosition                  fpos,
                FSFileHandle                    fileHandle,
                FSFlag                          flag,
                FSRetFlag                       errHandling,
                const FSAsyncParams             *asyncParams
                );

Parameters

client Pointer to the client buffer.
block Command block.
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.
fpos Stating file position.
fileHandle Handle of the file to write into.
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.

Return Values

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

Non-negative value ( ≥ 0 ) Number of elements write.
FS_STATUS_CANCELED The 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 is greater than the maximum file size.
FS_STATUS_UNSUPPORTED_CMD Associated file system does not support this function.
FS_STATUS_STORAGE_FULL Data space cannot be allocated.
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.

Async API: Immediate return values

FS_STATUS_OK Successfully issued request.
FS_STATUS_FATAL_ERROR The argument is invalid.

Description

Writes data to the file stream designated by fileHandle from the data array designated by source, specifying starting file position designated by fpos. The file position of the stream is advanced from the specified file position 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 size or count is zero, this function returns zero (=FS_STATUS_OK) without writing anything, but it will be followed by a 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.

If the access mode specified in FSOpenFile is set to "a" or "a+", The designated file position fpos is ignored. The file position is always set to the end of file.
When specifying the access mode to be "a" or "a+" for FSOpenFile and executing FSWriteFileWithPos with 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.

Alignment of the address and size of data buffer are constrained by FS_IO_BUFFER_ALIGN as same as FSWriteFile.

For good performance, allocate the source buffer on the heap.

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

Do Not Call From

FSWriteFileWithPos

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.

FSWriteFileWithPosAsync

None.

See Also

File/Directory operations
Rules and Conventions
FSOpenFile
FSReadFileWithPos
FSCloseFile

Revision History

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/30 Removed information about FSA.
2012/07/20 Readability and correctness cleanup.
2011/07/31 Noted about command priority.
2011/02/20 Initial version.


CONFIDENTIAL