4 Functions

Mount a Volume

FRESULT pf_mount (
  FATFS*  fs/* [IN] Pointer to the work area */
);

The pf_mount() function should be used prior to attempting any interfacing. It mounts the storage volume and gives a work area to the Petit FatFS module.

  • Parameters:
    • fs: Pointer to the file system object (work area) to be registered.
  • Return Values:
    • FR_OK (0): Function success.
    • FR_NOT_READY: The volume could not be mounted, due to a hard error or no volume present.
    • FR_DISK_ERR: An error occurred in the disk read function.
    • FR_NO_FILESYSTEM: No valid FAT partition on the drive.

Open a File

FRESULT pf_open (
  const char* path /* [IN] Pointer to the file name */
);

The pf_open() function should be used prior to writing to or reading from a file. The open file is valid until the open function is used again for another file. Files cannot be created.

  • Parameters:
    • path: Pointer to a null-terminated string specifying the file name of the file to open.
  • Return Values:
    • FR_OK (0): Function success.
    • FR_NO_FILE: The file or path could not be found.
    • FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure or an internal error.
    • FR_NOT_ENABLED: The volume has not been mounted.

Read from a File

FRESULT pf_read (
  void* buff,  /* [OUT] Pointer to the read buffer */
  UINT btr,    /* [IN]  Number of bytes to read */
  UINT* br     /* [OUT] Number of bytes read */
);

The pf_read() function is used to read data from an open file. It is available when _USE_READ is written to '1' in the pffconf.h file. The file pointer (fptr) in the file system object increases by the number of bytes read. Upon function success, *br should be checked to detect end of file; if *br is less than btr at the end of the function, the end of the file was reached during the read operation. If the argument buff is given as NULL, the read data are forwarded to the outgoing stream rather than stored in a memory buffer. The streaming function depends on each project and will typically be implemented in the disk_readp() function.

  • Parameters:
    • buff: Pointer to the buffer where read data should be stored. A null pointer will result in the read data being forwarded to the output stream.
    • btr: Number of bytes to read.
    • br: Pointer to a variable which will indicate number of bytes read upon return.
  • Return Values:
    • FR_OK (0): Function success.
    • FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure or an internal error.
    • FR_NOT_OPENED: The file has not been opened.
    • FR_NOT_ENABLED: The volume has not been mounted.

Write to a File

FRESULT pf_write (
  const void* buff, /* [IN]  Pointer to the data to be written */
  UINT btw,         /* [IN]  Number of bytes to write */
  UINT* bw          /* [OUT] Pointer to the variable to return number of bytes written */
);

The pf_write() function is used to write data to an open file. It is available when _USE_WRITE is written to '1' in the pffconf.h file. The file pointer (fptr) in the file system object increases by the number of bytes written. Upon function success, *bw should be checked to detect end of file; if *bw is less than btw at the end of the function, the end of the file was reached during the write operation.

Restrictions:
  • Cannot create files
  • Cannot increase the size of existing files
  • Cannot update timestamp of the file, i.e. "Last Modified" attribute
  • A write operation can only start and stop on a sector boundary
  • A write operation will not be blocked by a file having a read-only attribute
File write must be completed in the following sequence:
  1. pf_lseek(ofs); The read/write pointer must be moved to a sector boundary prior to initiating a write operation. If this is not done, the pointer will be rounded down to the closest sector boundary.
  2. pf_write(buff, btw, &bw); Write data to the file. This function can be called repeatedly if necessary i.e., data are being produced continually. However, no data will be fully committed until the write is finalized in the next step.
  3. pf_write(0, 0, &bw); Finalize the write operation. If the read/write pointer is not on the sector boundary, the remaining bytes in the sector will be filled with zeros. This step must be completed to commit all written data.
  • Parameters:
    • buff: Pointer to the buffer where the data to be written are stored. A null pointer will indicate that a write operation might be finalized.
    • btw: Number of bytes to write.
    • bw: Pointer to a variable, which will indicate number of bytes written upon return.
  • Return Values:
    • FR_OK (0): Function success.
    • FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure or an internal error.
    • FR_NOT_OPENED: The file has not been opened.
    • FR_NOT_ENABLED: The volume has not been mounted.

Move the File Pointer

FRESULT pf_lseek (
  DWORD ofs        /* [IN] File offset in unit of byte */
);

The pf_lseek() function is used to move the read/write pointer within an open file. It is available when _USE_LSEEK is written to '1' in the pffconf.h file. The offset should be specified relative to the top of the file. The file pointer (fptr) in the file system object will reflect the change.

  • Parameters:
    • ofs: Where the read/write pointer should be moved, specified in bytes from the start of the file.
  • Return Values:
    • FR_OK (0): Function success.
    • FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure, or an internal error.
    • FR_NOT_OPENED: The file has not been opened.

Open a Directory

FRESULT pf_opendir (
  DIR* dp,          /* [OUT] Pointer to the blank directory object structure */
  const char* path  /* [IN]  Pointer to the directory name */
);

The pf_opendir() function is used to open an existing directory, and create a directory object for future reference that can be discarded at any time without a specific procedure. It is available when _USE_DIR is written to '1' in the pffconf.h file.

  • Parameters:
    • dp: Pointer to the blank directory object to be created.
    • path: Pointer to a null-terminated string specifying the directory name of the directory to open.
  • Return Values:
    • FR_OK (0): Function success.
    • FR_NO_FILE: The path could not be found.
    • FR_NOT_READY: No volume.
    • FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure or an internal error.
    • FR_NOT_ENABLED: The volume has not been mounted.

Read a Directory

FRESULT pf_readdir (
  DIR* dp,      /* [IN]  Pointer to the open directory object */
  FILINFO* fno  /* [OUT] Pointer to the file information structure */
);

The pf_readdir() function reads directory entries in sequence. It is available when _USE_DIR is written to '1' in the pffconf.h file. All items in the directory can be read by calling this function repeatedly. When all directory entries have been read, the function puts a null string into member f_name[] in the file information structure without returning an error. When fno is given as a null pointer, the read index of the directory object will be rewinded.

  • Parameters:
    • dp: Pointer to the open directory object.
    • fno: Pointer to the file information structure in which to store the read item.
  • Return Values:
    • FR_OK (0): Function success.
    • FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure or an internal error.
    • FR_NOT_OPENED: The directory object has not been opened.