f_open

The f_open function creates a file object to be used to access the file.

FRESULT f_open (
  FIL* FileObject,       /* Pointer to the blank file object structure */
  const XCHAR* FileName, /* Pointer to the file neme */
  BYTE ModeFlags         /* Mode flags */
);

Parameters

FileObject
Pointer to the file object structure to be created. After the f_open funciton succeeded, the file can be accessed with the file object structure until it is closed.
FileName
Pointer to a null-terminated string that specifies the file name to create or open.
ModeFlags
Specifies the type of access and open method for the file. It is specified by a combination of following flags.
ValueDescription
FA_READSpecifies read access to the object. Data can be read from the file.
Combine with FA_WRITE for read-write access.
FA_WRITESpecifies write access to the object. Data can be written to the file.
Combine with FA_READ for read-write access.
FA_OPEN_EXISTINGOpens the file. The function fails if the file is not existing. (Default)
FA_OPEN_ALWAYSOpens the file, if it is existing. If not, a new file is created.
FA_CREATE_NEWCreates a new file. The function fails if the file is already existing.
FA_CREATE_ALWAYSCreates a new file. If the file is existing, it is truncated and overwritten.

Return Values

FR_OK (0)
The function succeeded and the file object is valid.
FR_NO_FILE
Could not find the file.
FR_NO_PATH
Could not find the path.
FR_INVALID_NAME
The file name is invalid.
FR_INVALID_DRIVE
The drive number is invalid.
FR_EXIST
The file is already existing.
FR_DENIED
The required access was denied due to one of the following reasons:
  • Write mode open of a read-only file.
  • File cannot be created due to a read-only file or same name directory is existing.
  • File cannot be created due to the directory table or disk is full.
FR_NOT_READY
The disk drive cannot work due to no medium in the drive or any other reason.
FR_WRITE_PROTECTED
Write mode open or creation under the medium is write protected.
FR_DISK_ERR
The function failed due to an error in the disk function.
FR_INT_ERR
The function failed due to a wrong FAT structure or an internal error.
FR_NOT_ENABLED
The logical drive has no work area.
FR_NO_FILESYSTEM
There is no valid FAT volume on the disk.

Description

The created file object is used for subsequent calls to refer to the file. When close an open file object, use f_close function. If the modified file is not closed, the file may be collapsed.

Before using any file function, a work area (file system object) must be given to the logical drive with f_mount function. All file functions can work after this procedure.

QuickInfo

Always available. The mode flags, FA_WRITE, FA_CREATE_ALWAYS, FA_CREATE_NEW, FA_OPEN_ALWAYS, are not available when _FS_READONLY == 1.

Example (File Copy)

void main (void)
{
    FATFS fs[2];         // Work area (file system object) for logical drives
    FIL fsrc, fdst;      // file objects
    BYTE buffer[4096];   // file copy buffer
    FRESULT res;         // FatFs function common result code
    UINT br, bw;         // File R/W count


    // Register work area for logical drives
    f_mount(0, &fs[0]);
    f_mount(1, &fs[1]);

    // Open source file on the drive 1
    res = f_open(&fsrc, "1:srcfile.dat", FA_OPEN_EXISTING | FA_READ);
    if (res) die(res);

    // Create destination file on the drive 0
    res = f_open(&fdst, "0:dstfile.dat", FA_CREATE_ALWAYS | FA_WRITE);
    if (res) die(res);

    // Copy source to destination
    for (;;) {
        res = f_read(&fsrc, buffer, sizeof(buffer), &br);
        if (res || br == 0) break;   // error or eof
        res = f_write(&fdst, buffer, br, &bw);
        if (res || bw < br) break;   // error or disk full
    }

    // Close open files
    f_close(&fsrc);
    f_close(&fdst);

    // Unregister work area prior to discard it
    f_mount(0, NULL);
    f_mount(1, NULL);
}

See Also

f_read, f_write, f_close, FIL, FATFS

Return