file Module¶

Since	Origin / Contributor	Maintainer	Source
2014-12-22	Zeroday	Zeroday	file.c

Historically the file module provided both file meta information/manipulation as well as file contents manipulation. These days file content manipulation is handled via the standard Lua io module, and only meta information is handled by the file module.

The file module operates on the virtual file system provided by the Espressif VFS component, with a couple of exceptions. Specifically, the fsinfo() and format() functions operate only on the default SPIFFS file system, as configured in the platform settings in Kconfig.

file.exists()¶

Determines whether the specified file exists.

Syntax¶

file.exists(filename)

Parameters¶

• filename file to check

Returns¶

true if the file exists (even if 0 bytes in size), and false if it does not exist

Example¶

files = file.list()
if files["device.config"] then
    print("Config file exists")
end

if file.exists("device.config") then
    print("Config file exists")
end

See also¶

file.list()

file.format()¶

Format the file system. Completely erases any existing file system and writes a new one. Depending on the size of the flash chip in the ESP, this may take several seconds.

Syntax¶

file.format()

Parameters¶

none

Returns¶

nil

See also¶

file.remove()

file.fsinfo()¶

Return size information for the file system, in bytes.

Syntax¶

file.fsinfo()

Parameters¶

none

Returns¶

• remaining (number)
• used (number)
• total (number)

Example¶

-- get file system info
remaining, used, total=file.fsinfo()
print("\nFile system info:\nTotal : "..total.." (k)Bytes\nUsed : "..used.." (k)Bytes\nRemain: "..remaining.." (k)Bytes\n")

file.list()¶

Lists all files in the file system.

Syntax¶

file.list([mountpoint])

Parameters¶

mountpoint to list files in other file systems, the mountpoint can be given.

Returns¶

A lua table which contains the {file name: file size} pairs. For SPIFFS file systems the size is returned in bytes, whereas for FAT file systems the size is given in kilobytes.

Example¶

l = file.list();
for k,v in pairs(l) do
  print("name:"..k..", size:"..v)
end

file.mkdir()¶

Creates a directory, provided the underlying file system supports directories. SPIFFS does not, but FAT (which you may have on an attached SD card) does.

Syntax¶

file.mkdir(path [, mode])

Parameters¶

• path the full path name of the directory to create. E.g. "/SD0/MYDIR".
• mode optional, only used for file systems which use mode permissions. Defaults to 0777 (octal).

Returns¶

nil

Throws an error if the directory could not be created. Error code 134 (at the time of writing) indicates that the filesystem at the given path does not support directories.

file.rmdir()¶

Removes an empty directory, provided the underlying file system supports directories. SPIFFS does not, but FAT (which you may have on an attached SD card) does.

Syntax¶

file.rmdir(path)

Parameters¶

• path the path to the directory to remove. The directory must be empty.

Returns¶

nil

Throws an error if the directory could not be removed.

file.remove()¶

Remove a file from the file system. The file must not be currently open.

Syntax¶

file.remove(filename)

Parameters¶

filename file to remove

Returns¶

nil

Example¶

-- remove "foo.lua" from file system.
file.remove("foo.lua")

file.rename()¶

Renames a file.

Syntax¶

file.rename(oldname, newname)

Parameters¶

• oldname old file name
• newname new file name

Returns¶

true on success, false on error.

Example¶

-- rename file 'temp.lua' to 'init.lua'.
file.rename("temp.lua","init.lua")