我的书签
添加书签
移除书签Utils_file
This module allows you to performs file operations such as to open, close, read, and write a file, and to obtain the file size. The filing system varies according to the hardware platform. The following limitations are imposed on a platform that uses the Serial Peripheral Interface Flash Filing System (SPIFFS):
Since:
1.0
Version:
1.0
Summary
Files
Macros
Macro Name and Value |
Description |
|---|---|
Defines the offset position used by in a file to start offsetting from the file header. |
|
Defines the offset position used by UtilsFileSeek in a file to start offsetting from the current read and write position. |
|
Defines the offset position used by in a file to start offsetting from the end of the file. |
|
Defines a flag used byUtilsFileOpen to open a file in read-only mode. |
|
Defines a flag used by to open a file in write-only mode. |
|
Defines a flag used by UtilsFileOpen to open a file in read-and-write mode. |
|
Defines a flag used by to create a file when the file to open does not exist. |
|
O_EXCL_FS 0200 |
Defines a flag used by to check whether the file to open exists when O_CREAT_FS is already set. |
Defines a flag used by to clear the file content if the file exists and can be opened in write mode. |
|
Defines a flag used by UtilsFileOpen to start reading or writing from the end of a file. |
Functions
Function Name |
Description |
|---|---|
UtilsFileOpen (const char path, int oflag, int mode) |
int Opens or creates a file. |
(int fd) |
int Closes a file with the specified file descriptor. |
UtilsFileRead (int fd, char buf, unsigned int len) |
int Reads a specified length of data from a file with the specified file descriptor and writes the data into the buffer. |
(int fd, const char buf, unsigned int len) |
int Writes a specified length of data into a file with the specified file descriptor. |
UtilsFileDelete (const char path) |
int Deletes a specified file. |
(const char path, unsigned int fileSize) |
int Obtains the file size. |
UtilsFileSeek (int fd, int offset, unsigned int whence) |
Adjusts the read and write position offset in a file. |
(const char src, const char dest) |
int Copies the source file to a target file. |
UtilsFileMove (const char src, const char dest) |
int Moves the source file into a target file. |
Details
O_EXCL_FS
Description:
Defines a flag used by to check whether the file to open exists when O_CREAT_FS is already set.
If the file does not exist, a new file will be created. If the file exists, the file cannot be opened.
Function Documentation
UtilsFileClose()
Description:
Closes a file with the specified file descriptor.
Parameters:
Name |
Description |
|---|---|
| fd | Indicates the file descriptor of the file to close. |
Returns:
Returns 0 if the file is closed; returns -1 otherwise.
UtilsFileCopy()
int UtilsFileCopy (const char * src, const char * dest )
Description:
Copies the source file to a target file.
Parameters:
Attention:
If the number of opened files reaches the upper limit (32), close any two files first. Otherwise, the file cannot be copied.
Returns:
Returns 0 if the operation is successful; returns -1 otherwise.
UtilsFileDelete()
Description:
Deletes a specified file.
Parameters:
Name |
Description |
|---|---|
| path | Indicates the file to delete. |
Attention:
If the number of opened files reaches the upper limit (32), close any of them first. Otherwise, the file cannot be deleted.
Returns:
Returns 0 if the file is deleted; returns -1 otherwise.
Description:
Moves the source file into a target file.
Parameters:
Name |
Description |
|---|---|
| src | Indicates the source file. |
| dest | Indicates the target file. |
Attention:
If the number of opened files reaches the upper limit (32), close any two files first. Otherwise, the file cannot be moved.
Returns:
Returns 0 if the operation is successful; returns -1 otherwise.
UtilsFileOpen()
int UtilsFileOpen (const char * path, int oflag, int mode )
Description:
Opens or creates a file.
Parameters:
Name |
Description |
|---|---|
| path | Indicates the file to open or create. |
| oflag | Indicates the mode of opening a file. The following modes are supported. These modes can be used together, with each of them identified by “or”. |
| mode | Used for function compatibility. This parameter does not take effect in any scenario. |
Returns:
Returns the file descriptor if the file is opened or created; returns -1 otherwise.
UtilsFileRead()
Description:
Reads a specified length of data from a file with the specified file descriptor and writes the data into the buffer.
Parameters:
Name |
Description |
|---|---|
| fd | Indicates the file descriptor of the file to read. |
| buf | Indicates the buffer that stores the read data. This is an output parameter. |
| len | Indicates the length of the data to read. |
Returns:
Returns the number of bytes of the data if the data is read; returns -1 otherwise.
UtilsFileSeek()
Description:
Adjusts the read and write position offset in a file.
Parameters:
Name |
Description |
|---|---|
| fd | Indicates the file descriptor of the file where the read and write position offset needs adjustment. |
| offset | Indicates the offset of the read and write position based on the whence parameter. The value can be negative if the value of whence is SEEK_CUR_FS or SEEK_END_FS. |
| whence | Indicates the start position of the offset. The following start positions are supported. |
whence |
Description |
|---|---|
SEEK_SET_FS |
Adjusts the read and write position to the file header. |
^ |
Then adds the offset after the read and write position. |
SEEK_CUR_FS |
Adds the offset after the current read and write position. |
SEEK_END_FS |
Adjusts the read and write position to the end of the file. |
^ |
Then adds the offset after the read and write position. |
Returns:
Returns the current read and write position if the operation is successful; returns -1 otherwise.
UtilsFileStat()
Description:
Obtains the file size.
Parameters:
Returns:
Returns 0 if the file size is obtained; returns -1 otherwise.
UtilsFileWrite()
Description:
Writes a specified length of data into a file with the specified file descriptor.
Parameters:
Name |
Description |
|---|---|
| fd | Indicates the file descriptor of the file where to write the data. |
| buf | Indicates the data to write. |
| len | Indicates the length of the data to write. |
Returns the number of bytes of the data if the data is written; returns -1 otherwise.
