## 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 char* FileName, /* Pointer to the file neme */
      BYTE ModeFlags        /* Mode flags */
    );

#### Parameters

FileObject
  Pointer to the file object structure to be created. After the f_open funciton succeeded, the file can be accessed with the file object structure until it is closed.
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.

  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, the function creates the new file.
  FA_CREATE_NEW | Creates a new file. The function fails if the file is already existing.
  FA_CREATE_ALWAYS | Creates 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_RW_ERROR
  The function failed due to a disk error or an internal error.
FR_NOT_ENABLED
  The logical drive has no work area.
FR_NO_FILESYSTEM
  There is no valid FAT partition on the disk.

#### Description

The created file object is used for subsequent calls to refer to the file. When close an open file object, use f_close function. If modified file is not closed correctly, the file will 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.

The mode flags, `FA_WRITE, FA_CREATE_ALWAYS, FA_CREATE_NEW, FA_OPEN_ALWAYS`, are not supported in read-only configuration.

#### Example (File Copy)

    void main ()
    {
        FATFS fs;            // Work area (file system object) for logical drive
        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 a work area for logical drive 0
        f_mount(0, &fs);

        // Open source file
        res = f_open(&fsrc, "srcfile.dat", FA_OPEN_EXISTING | FA_READ);
        if (res) die(res);

        // Create destination file
        res = f_open(&fdst, "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 all files
        f_close(&fsrc);
        f_close(&fdst);

        // Unregister a work area before discard it
        f_mount(0, NULL);
    }

#### References

`f_read, f_write, f_close, FIL, FATFS`

Return