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_EXCL_FS

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

Function Documentation

UtilsFileClose()

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

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

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

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

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

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

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

^

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

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

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