FatFs - f_open

## f_open

The f_open function creates a file object to be used to access the 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.

  Value | Meaning
  --- | ---
  FA_READ | Specifies read access to the object. Data can be read from the file.
  FA_WRITE | Specifies write access to the object. Data can be written to the file. Combine with `FA_READ` for read-write access.
  FA_OPEN_EXISTING | Opens the file. The function fails if the file is not existing. (Default)
  FA_CREATE_NEW | Creates a new file. The function fails with `FR_EXIST` if the file is existing.
  FA_CREATE_ALWAYS | Creates a new file. If the file is existing, it will be truncated and overwritten.
  FA_OPEN_ALWAYS | Opens the file if it is existing. If not, a new file will be created.
  FA_OPEN_APPEND | Same as `FA_OPEN_ALWAYS` except the read/write pointer is set end of the file.

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

Before using any file function, a work area (file system object) needs to be registered to the logical drive with `f_mount` function. All API functions except for `f_mkfs/f_fdisk` function get ready to work after this procedure.

After `f_open` function succeeded, the file object is valid. The file object is used for subsequent operations to the file to identify the file. Open file must be closed prior to power down, media removal or re-mount, or the file can be collapsed. To close an open file, use `f_close` function.

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 `_FS_READONLY == 1`.

#### Example

    /* Read a text file and display it */

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

    int main (void)
    {
        FIL fil;       /* File object */
        char line[82]; /* 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 (file system 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