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
0	Defines the offset position used by UtilsFileSeek in a file to start offsetting from the file header.
1	Defines the offset position used by UtilsFileSeek in a file to start offsetting from the current read and write position.
2	Defines the offset position used by UtilsFileSeek in a file to start offsetting from the end of the file.
00	Defines a flag used byUtilsFileOpen to open a file in read-only mode.
01	Defines a flag used by UtilsFileOpen to open a file in write-only mode.
02	Defines a flag used by UtilsFileOpen to open a file in read-and-write mode.
0100	Defines a flag used by UtilsFileOpen to create a file when the file to open does not exist.
0200	Defines a flag used by UtilsFileOpen to check whether the file to open exists when is already set.
O_TRUNC_FS 01000	Defines a flag used by to clear the file content if the file exists and can be opened in write mode.
O_APPEND_FS 02000	Defines a flag used by 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)	int 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

Details

Macro Definition Documentation

O_APPEND_FS

Description:

Defines a flag used by UtilsFileOpen to start reading or writing from the end of a file.

O_CREAT_FS

Description:

Defines a flag used by UtilsFileOpen to create a file when the file to open does not exist.

#define O_EXCL_FS   0200

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.

O_RDONLY_FS

#define O_RDONLY_FS   00

Description:

Defines a flag used byUtilsFileOpen to open a file in read-only mode.

O_RDWR_FS

#define O_RDWR_FS   02

Description:

Defines a flag used by UtilsFileOpen to open a file in read-and-write mode.

O_TRUNC_FS

#define O_TRUNC_FS   01000

Description:

Defines a flag used by UtilsFileOpen to clear the file content if the file exists and can be opened in write mode.

O_WRONLY_FS

Description:

Defines a flag used by UtilsFileOpen to open a file in write-only mode.

SEEK_CUR_FS

Description:

Defines the offset position used by UtilsFileSeek in a file to start offsetting from the current read and write position.

SEEK_END_FS

#define SEEK_END_FS   2

Description:

Defines the offset position used by UtilsFileSeek in a file to start offsetting from the end of the file.

SEEK_SET_FS

#define SEEK_SET_FS   0

Description:

Defines the offset position used by UtilsFileSeek in a file to start offsetting from the file header.

Function Documentation

int UtilsFileClose (int fd)

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.

UtilsFileMove()

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()

int UtilsFileRead (int fd, char * buf, unsigned int len )

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()

int UtilsFileSeek (int fd, int offset, unsigned int whence )

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