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.

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.

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.

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

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.

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.

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.