## 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. If a null pointer is given, the function fails with `FR_INVALID_OBJECT`.
path
  Pointer to the null-terminated string that specifies the file name to open or create. If a null pointer is given, the function fails with `FR_INVALID_DRIVE`.
mode
  Mode flags that specifies the type of access and open method for the file. It is specified by a combination of following flags.

  Flags | Meaning
  --- | ---
  FA_READ | Specifies read access to the file. Data can be read from the file.
  FA_WRITE | Specifies write access to the file. 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_ALWAYS | Creates a new file. If the file is existing, the file is truncated and overwritten.
  FA_CREATE_NEW | Creates a new file. The function fails if the file is existing.
  FA_OPEN_ALWAYS | Opens the file. If it is not exist, a new file is created.
  FA_OPEN_APPEND | Same as `FA_OPEN_ALWAYS` except the read/write pointer is set end of the file.

  Mode flags in POSIX fopen() function corresponds to FatFs mode flags as follows:

  POSIX | FatFs
  --- | ---
  "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
  "wx" | FA_CREATE_NEW | FA_WRITE
  "w+x" | FA_CREATE_NEW | FA_WRITE | FA_READ

#### 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. It is the identifier for subsequent read/write operations to the file. After the function succeeded, the file object is valid. If the function failed, the file object is set invalid.

Open file should be closed with `f_close` function after the session of the file access. If any change to the file has been made and not closed prior to power off, 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 available for the mode flags 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 */

        /* Give a 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 every line 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 fs0, fs1;      /* 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 */

        /* Give work areas to each logical drive */
        f_mount(&fs0, "0:", 0);
        f_mount(&fs1, "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 data from the source file */
            if (br == 0) break; /* error or eof */
            fr = f_write(&fdst, buffer, br, &bw);           /* Write it to the destination file */
            if (bw < br) break; /* error or disk full */
        }

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

        /* Unregister work area prior to discard it */
        f_unmount("0:");
        f_unmount("1:");

        return (int)fr;
    }

#### See Also

`f_read, f_write, f_close, FIL, FATFS`

Return