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

A file object is created when the function succeeded. The file object is used for subsequent read/write functions 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