FSOpenFile

Syntax

#include <cafe/fs.h>

FSStatus FSOpenFile(
                FSClient                        *client,
                FSCmdBlock                      *block,
                const char                      *path,
                const char                      *mode,
                FSFileHandle                    *fileHandle,
                FSRetFlag                       errHandling
                );
FSStatus FSOpenFileAsync(
                FSClient                        *client,
                FSCmdBlock                      *block,
                const char                      *path,
                const char                      *mode,
                FSFileHandle                    *fileHandle,
                FSRetFlag                       errHandling,
                const FSAsyncParams             *asyncParams
                );

Parameters

client Pointer to the client buffer.
block Command block.
path File path to open. Length must be less than FS_MAX_ARGPATH_SIZE.
mode Short string parameter that specifies access mode. Length must be less than FS_MAX_MODE_SIZE. It can be:
  • "r": Open a file for reading. The file must exist. This is the only read-specific mode. You may write in all other modes.
  • "w": Create an empty file for writing. If a file with the same name already exists, its contents will be erased and the file size will become 0 byte.
  • "a": Append to a file. Writing operations append data at the end of the file. The file is created if it does not exist.
  • "r+": Open a file for update both reading and writing. The file must exist.
  • "w+": Create an empty file for both reading and writing. If a file with the same name already exists, its content will be erased and the file size will become 0 byte.
  • "a+": Open a file for reading and appending. All writing operations are performed at the end of the file, protecting the previous contents from being overwritten. You can reposition the internal pointer to anywhere in the file for reading, but writing operations will move it back to the end of file. The file is created if it does not exist.
fileHandle Pointer to the handle of file stream associated to the file to be opened.
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

FS_STATUS_OK> Successfully completed.
FS_STATUS_CANCELED The command was canceled.
FS_STATUS_MAX System has too many file points to create more.
FS_STATUS_ALREADY_OPEN The file is already open.
You are trying to open the file illegally.
FS_STATUS_NOT_FOUND Target not found.
FS_STATUS_NOT_FILE Specified path is not a file.
FS_STATUS_NOT_DIR Specified path includes the entry as directory, though it is not a directory.
FS_STATUS_ACCESS_ERROR Access mode is invalid (e.g. specified "r+" for read-only media).
FS_STATUS_PERMISSION_ERROR The caller does not have correct access permission.
FS_STATUS_JOURNAL_FULL Journaling space is full and new journaling block cannot be allocated.
FS_STATUS_STORAGE_FULL Data space 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 request.
FS_STATUS_FATAL_ERROR The argument is invalid.

Description

Opens the file designated by path and creates a file stream associated with it. The position of the file stream is set to the head. mode is a short string parameter to specify access mode.

This API allows the same file to be opened multiple times. However, the mode of the entire FSOpenFile arguments must be "r". If you try to open the same file multiple times in non-r mode or a file that is already open in non-r mode, FS_STATUS_ALREADY_OPEN should return for such an attempt is invalid.

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.

The generated file handle is stored in fileHandle when completed.

The generated file handle is positive value (>0) if the function succeeds. Otherwise, the handle value is FS_INVALID_HANDLE_VALUE. The invalid handle value is not necessary to close.

Do Not Call From

FSOpenFile

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.

FSOpenFileAsync

None.

See Also

File/Directory operations
FSReadFile
FSWriteFile
FSCloseFile

Revision History

2014/09/16 Added "Thread that displays graphics" and "Thread that handles system messages" to "Do not call from".
2013/12/04 Added FS_STATUS_STORAGE_FULL and FS_STATUS_JOURNAL_FULL to return values.
2013/06/11 Changed description about "w" and "w+" mode.
2013/06/06 Added FS_STATUS_NOT_DIR to return values.
2013/05/23 Added FS_STATUS_DATA_CORRUPTED to return values.
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/13 Added "FS_STATUS_ALREADY_OPEN" to "Return Values".
2013/01/10 Added "Callback" to "Do not call from".
2012/07/19 Readability and correctness cleanup.
2011/12/12 Initial version.
2010/03/30 Fixed type name FSNotificationParams -> FSAsyncParams.


CONFIDENTIAL