Utils_file

Utils_file

Overview

Performs operations on a 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

File Name	Description
utils_file.h	Performs operations on a file, including to open, close, write, read, and delete a file.

Macros

Macro Name and Value	Description
SEEK_SET_FS 0	Defines the offset position used by UtilsFileSeek in a file to start offsetting from the file header.
SEEK_CUR_FS 1	Defines the offset position used by UtilsFileSeek in a file to start offsetting from the current read and write position.
SEEK_END_FS 2	Defines the offset position used by UtilsFileSeek in a file to start offsetting from the end of the file.
O_RDONLY_FS 00	Defines a flag used byUtilsFileOpen to open a file in read-only mode.
O_WRONLY_FS 01	Defines a flag used by UtilsFileOpen to open a file in write-only mode.
O_RDWR_FS 02	Defines a flag used by UtilsFileOpen to open a file in read-and-write mode.
O_CREAT_FS 0100	Defines a flag used by UtilsFileOpen to create a file when the file to open does not exist.
O_EXCL_FS 0200	Defines a flag used by UtilsFileOpen to check whether the file to open exists when O_CREAT_FS is already set.
O_TRUNC_FS 01000	Defines a flag used by UtilsFileOpen 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 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.
UtilsFileClose (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.
UtilsFileWrite (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.
UtilsFileStat (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.
UtilsFileCopy (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

Macro Definition Documentation

O_APPEND_FS

#define O_APPEND_FS   02000

Description:

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

O_CREAT_FS

#define O_CREAT_FS   0100

Description:

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

O_EXCL_FS

#define O_EXCL_FS   0200

Description:

Defines a flag used by UtilsFileOpen 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

#define O_WRONLY_FS   01

Description:

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

SEEK_CUR_FS

#define SEEK_CUR_FS   1

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

UtilsFileClose()

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:

Name	Description
src	Indicates the source file to copy.
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 copied.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

UtilsFileDelete()

int UtilsFileDelete (const char * path)

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

int UtilsFileMove (const char * src, const char * dest )

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.

oflag	Description
O_RDONLY_FS	For details, see O_RDONLY_FS.
O_WRONLY_FS	For details, see O_WRONLY_FS.
O_RDWR_FS	For details, see O_RDWR_FS.
O_CREAT_FS	For details, see O_CREAT_FS.
O_EXCL_FS	For details, see O_EXCL_FS.
O_TRUNC_FS	For details, see O_TRUNC_FS.
O_APPEND_FS	For details, see O_APPEND_FS.

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

int UtilsFileStat (const char * path, unsigned int * fileSize )

Description:

Obtains the file size.

Parameters:

Name	Description
path	Indicates the file name.
fileSize	Indicates the file size. This is an output parameter.

Returns:

Returns 0 if the file size is obtained; returns -1 otherwise.

UtilsFileWrite()

int UtilsFileWrite (int fd, const char * buf, unsigned int len )

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:

Returns the number of bytes of the data if the data is written; returns -1 otherwise.