## 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 to be created.
path
  Pointer to a 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 | Description
  --- | ---
  FA_READ | Specifies read access to the object. Data can be read from the file. Combine with `FA_WRITE` for read-write access.
  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_OPEN_ALWAYS | Opens the file if it is existing. If not, a new file is created. To append data to the file, use `f_lseek` function after file open in this method.
  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.

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

After `f_open` function succeeded, the file object is valid. The file object is used for subsequent read/write functions to identify the file. Open files must be closed prior to shutdown, media removal or re-mount, or the file data will 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 write mode flag is always prohibited.

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

#### QuickInfo

Always available. The mode flags, `FA_WRITE, FA_CREATE_ALWAYS, FA_CREATE_NEW and FA_OPEN_ALWAYS`, are not available 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_OPEN_EXISTING | FA_READ);
        if (fr) return (int)fr;

        /* Create destination file on the drive 0 */
        fr = f_open(&fdst, "0:file.bin", FA_CREATE_ALWAYS | FA_WRITE);
        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