f_open

The f_open function opens a file.

FRESULT f_open (
  FIL* fp,           /* [OUT] Pointer to the file object structure */
  const TCHAR* path, /* [IN] File name */
  BYTE mode          /* [IN] Mode flags */
);

Parameters

fp
Pointer to the blank file object structure.
path
Pointer to the null-terminated string that specifies the file name to open or create.
mode
Mode flags that specifies the type of access and open method for the file. It is specified by a combination of following flags.
FlagsMeaning
FA_READSpecifies read access to the object. Data can be read from the file.
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_CREATE_NEWCreates a new file. The function fails with FR_EXIST if the file is existing.
FA_CREATE_ALWAYSCreates a new file. If the file is existing, it will be truncated and overwritten.
FA_OPEN_ALWAYSOpens the file if it is existing. If not, a new file will be created.
FA_OPEN_APPENDSame as FA_OPEN_ALWAYS except the read/write pointer is set end of the file.
Mode flags of POSIX fopen() corresponds to FatFs mode flags as follows:
POSIXFatFs
"r"FA_READ
"r+"FA_READ | FA_WRITE
"w"FA_CREATE_ALWAYS | FA_WRITE
"w+"FA_CREATE_ALWAYS | FA_WRITE | FA_READ
"a"FA_OPEN_APPEND | FA_WRITE
"a+"FA_OPEN_APPEND | FA_WRITE | FA_READ
"x"*1FA_CREATE_NEW | FA_WRITE
"x+"*1FA_CREATE_NEW | FA_WRITE | FA_READ
*1: glibc extension

Return Values

FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_FILE, FR_NO_PATH, FR_INVALID_NAME, FR_DENIED, FR_EXIST, FR_INVALID_OBJECT, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_LOCKED, FR_NOT_ENOUGH_CORE, FR_TOO_MANY_OPEN_FILES

Description

The f_open function opens a file and creates a file object. The file object is used for subsequent read/write operations to the file to identify the file. Open file should be closed with f_close function after the session of the file access. If any change to the file is made and not closed prior to power down, media removal or re-mount, or the file can be collapsed.

If duplicated file open is needed, read here carefully. However duplicated open of a file with any write mode flag is always prohibited.

QuickInfo

Always available. Only FA_READ and FA_OPEN_EXISTING are supported when FF_FS_READONLY == 1.

Example

/* Read a text file and display it */

FATFS FatFs;   /* Work area (filesystem object) for logical drive */

int main (void)
{
    FIL fil;        /* File object */
    char line[100]; /* Line buffer */
    FRESULT fr;     /* FatFs return code */


    /* Register work area to the default drive */
    f_mount(&FatFs, "", 0);

    /* Open a text file */
    fr = f_open(&fil, "message.txt", FA_READ);
    if (fr) return (int)fr;

    /* Read all lines and display it */
    while (f_gets(line, sizeof line, &fil)) {
        printf(line);
    }

    /* Close the file */
    f_close(&fil);

    return 0;
}
/* Copy a file "file.bin" on the drive 1 to drive 0 */

int main (void)
{
    FATFS fs[2];         /* Work area (filesystem object) for logical drives */
    FIL fsrc, fdst;      /* File objects */
    BYTE buffer[4096];   /* File copy buffer */
    FRESULT fr;          /* FatFs function common result code */
    UINT br, bw;         /* File read/write count */


    /* Register work area for each logical drive */
    f_mount(&fs[0], "0:", 0);
    f_mount(&fs[1], "1:", 0);

    /* Open source file on the drive 1 */
    fr = f_open(&fsrc, "1:file.bin", FA_READ);
    if (fr) return (int)fr;

    /* Create destination file on the drive 0 */
    fr = f_open(&fdst, "0:file.bin", FA_WRITE | FA_CREATE_ALWAYS);
    if (fr) return (int)fr;

    /* Copy source to destination */
    for (;;) {
        fr = f_read(&fsrc, buffer, sizeof buffer, &br);  /* Read a chunk of source file */
        if (fr || br == 0) break; /* error or eof */
        fr = f_write(&fdst, buffer, br, &bw);            /* Write it to the destination file */
        if (fr || 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(NULL, "0:", 0);
    f_mount(NULL, "1:", 0);

    return (int)fr;
}

See Also

f_read, f_write, f_close, FIL, FATFS

Return