# 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

## Files

File Name

Description

Performs operations on a file, including to open, close, write, read, and delete a file.

## Macros

Macro Name and Value

Description

Defines the offset position used by UtilsFileSeek 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 UtilsFileSeek 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 UtilsFileOpen to open a file in write-only mode.

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

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.

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

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

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:

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

SEEK_CUR_FS

SEEK_END_FS

Adjusts the read and write position to the end of the file.

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.