11. FileSystem

The fs object is a built-in object that provides access to any file in the file system.

Functional overview:

• Provides the functions of retrieving information, copying, renaming, deleting, and changing permissions for a file or directory.
• Provides the function to read/write files by sequential access.
• Provides the function to read/write files by random access.

Limitations:

• The number of file resources that can be used is 5. (Version 00.00.04+) (Previous version: 3)

---

fs Global Object

Methods()/Properties	Summary	Version	Note
fs.stat()	Gets the detailed information of a file or directory.
fs.configure()	Changes the configuration of a file or directory.
fs.rename()	Renames a file or directory.
fs.remove()	Removes a file or directory.
fs.mkdir()	Makes a directory.
fs.fcopy()	Copies a file.
fs.fopen()	Opens a file and creates a file instance.

---

Details

fs.stat(path)

Gets the detailed information of a file or directory.

Name	Type	M/O	Summary	Note
path	string	mandatory	Specify a file or directory path. Ex) /tmp/dir1, /tmp/dir1/test.txt
return	{Stat}, null	-	{Stat} : File information (If the file or directory exists) null : If file information could not be obtained (If the file or directory does not exist)	If the parameter is abnormal, an exception occurs.

{Stat}

Name	Type	Summary	Note
.isFile	boolean	Whether it is a file or not
.isDirectory	boolean	Whether it is a directory or not
.size	number	Total size [Byte]
.blksize	number	Preferred I/O block size [Byte]
.atime	number	Time of last access (unixtime[ms])
.mtime	number	Time of last data modification (unixtime[ms])
.ctime	number	Time of last file status change (unixtime[ms])
.permission	string	Permissions It will be an octal notation string. Ex) '0777', '0754'
.uid	number	User ID of owner
.gid	number	Group ID of owner
.owner	string	User name of owner
.group	string	Group name of owner

fs.configure(path,options)

Changes the configuration of a file or directory.

Name	Type	M/O	Summary	Note
path	string	mandatory	Specify a file or directory path. Ex) /tmp/dir1, /tmp/dir1/test.txt
options	Object	mandatory	Options Refer to Options for details.
return	boolean	-	true : Success false : Failure	If the parameter is abnormal, an exception occurs.

Options

Name	Type	M/O	Summary	Note
permission	string	optional	Change the permissions. Specify in octal notation string. Ex) '0777', '0754'
owner	number, string	optional	Change the user of owner. Specify the owner's user ID (type number) or owner's user name (type string). The specified user must have already been created. New registration is not allowed.
group	number, string	optional	Change the group of owner. Specify the owner's group ID (type number) or the owner's group name (type string). The specified group must have already been created. New registration is not allowed.

fs.rename(oldPath,newPath)

Renames a file or directory.

Name	Type	M/O	Summary	Note
oldPath	string	mandatory	Specify the file or directory path to change from. Ex) /tmp/dir1, /tmp/dir1/test.txt
newPath	string	mandatory	Specify the file or directory path to change to. Ex) /tmp/dir2, /tmp/dir1/test2.txt
return	boolean	-	true : Success false : Failure	If the parameter is abnormal, an exception occurs.

fs.remove(path)

Removes a file or directory.
If a directory is to be removed, it must be empty under that directory.

Name	Type	M/O	Summary	Note
path	string	mandatory	Specify a file or directory path. Ex) /tmp/dir1, /tmp/dir1/test.txt
return	boolean	-	true : Success false : Failure	If the parameter is abnormal, an exception occurs.

fs.mkdir(path[,options])

Makes a directory.
Note that recursive directory creation is not possible.

Name	Type	M/O	Summary	Note
path	string	mandatory	Specify a new directory path. Ex) /tmp/dir2
options	Object	optional	Options Refer to Options for details.	The directory is created with owner 'root' and permission '0777'. If changed, specify the options.
return	boolean	-	true : Success false : Failure	If the parameter is abnormal, an exception occurs.

fs.fcopy(srcPath,dstPath[,options])

Copies a file.
Note that the destination directory path must exist.

Name	Type	M/O	Summary	Note
srcPath	string	mandatory	Specify the file path to copy from. Ex) /tmp/dir1/test.txt
dstPath	string	mandatory	Specify the file path to copy to. Ex) /tmp/dir2/test2.txt
options	Object	optional	Options Refer to Options and Additional options for details.	The owner and permissions settings of the files are inherited from the copy source. If changed, specify the options.
return	boolean	-	true : Success false : Failure	If the parameter is abnormal, an exception occurs.

Additional options for .fcopy() only

Name	Type	M/O	Summary	Note
overwrite	boolean	optional	File Overwrite Settings true: Allow overwriting. false: Prohibits overwriting. The default value is true.	If overwriting is prohibited and the file exists at the destination, failure occurs.

fs.fopen(path,flags[,options])

Opens a file and creates a file instance.
Note that the destination directory path must exist.

Name	Type	M/O	Summary	Note
path	string	mandatory	Specify the file path. Ex) /tmp/dir1/test.txt
flags	string	mandatory	Specify the open flag. 'r': Read only 'w': New write (overwrite) only 'a': Append write only 'r+': Read and write 'w+': New write (overwrite) and read 'a+': Append write and read	All are processed as binary.
options	Object	optional	Options Refer to Options and Additional options for details.	If the file is newly created, it will have owner 'root' and permission '0666'. If changed, specify the options.
return	{File}, null	-	{File} : Generated {File} null : If the file could not be opened	If the parameter is abnormal, an exception occurs.

Additional options for .fopen() only

Name	Type	M/O	Summary	Note
buffering	boolean	optional	Stream buffering true: Enable (fully buffered) false: Disable (unbuffered) The default value is true.	Version 00.00.04+

---

{File}

Methods()/Properties	Summary	Version	Note
.read()	Reads data from a file.
.write()	Writes data to a file.
.getStatus()	Gets the file status at the present moment.
.getPosition()	Gets the file position (file position indicator) at the present moment.
.setPosition()	Changes the file position (file position indicator).
.sync()	Transfers cache data on memory updated by file writing to the storage device.
.fcntl() / .ioctl()	Executes the fcntl/ioctl command to the file descriptor handled by a file instance.	00.00.04+
.close()	Closes a file and releases a file resource.

---

Details

.read([isBin[,line[,size]]])

Reads data from a file.

Name	Type	M/O	Summary	Note
isBin	boolean	optional	Specify the readout data format. true: Readout in binary data format false: Readout in string format The default value is false.
line	boolean	optional	1 line readout Reads 1 line of data up to the newline character. true: Enable false: Disable The default value is false.	If the data in 1 line exceeds the maximum readout size, the data will be read out in divided readouts.
size	number	optional	Maximum readout size [Byte] Range: 1 - 2,147,483,647 The default value is 4096.
return	ArrayBuffer, string	-	Readout data The return type is determined by isBin. If isBin is true, the type is ArrayBuffer; otherwise, the type is string.	The readout data will be less than or equal to the maximum readout size. If there is no readout data, the size will be 0. If the parameter is abnormal, an exception occurs.

.write(data[,flush])

Writes data to a file.

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	mandatory	Written data
flush	boolean	optional	Stream force output After writing data, the flash process is executed. true: Enable false: Disable The default value is true.	Version 00.00.04+
return	number	-	Data size written	If the write fails, the result will be less than the length of the specified written data. If the parameter is abnormal, an exception occurs.

.getStatus()

Gets the file status at the present moment.
The file status is cleared after this method is called.

Name	Type	M/O	Summary	Note
return	{FileStatus}	-	{FileStatus} : File status

{FileStatus}

Name	Type	Summary	Note
.eof	number	Status of EOF (end-of-file) indicator Whether the end of the file has been reached or not 0: Not yet reached Other than 0: Reached
.err	number	Status of error indicator Whether an error occurred in the file read or write process 0: Not yet occurred Other than 0: Occurred

.getPosition()

Gets the file position (file position indicator) at the present moment.

Name	Type	M/O	Summary	Note
return	number	-	Offset value at the present moment If failed, -1 is returned.

.setPosition(offset[,whence])

Changes the file position (file position indicator).
Moves to the position from the specified whence position added the offset bytes.

Name	Type	M/O	Summary	Note
offset	number	mandatory	Offset Range: -2,147,483,648 - 2,147,483,647
whence	number	optional	Reference position 0: Beginning of file 1: Current position 2: End of file The default value is 0.
return	boolean	-	true : Success false : Failure	If the parameter is abnormal, an exception occurs.

.sync([dataOnly])

Transfers cache data on memory updated by file writing to the storage device.

Name	Type	M/O	Summary	Note
dataOnly	boolean	optional	Specify whether or not only data should be targeted for updating. true: Update data only, do not update file metadata false: Update data and file metadata The default value is false.
return	boolean	-	true : Success false : Failure	If the parameter is abnormal, an exception occurs.

.fcntl(cmd[,arg]) / .ioctl(cmd[,arg])

Executes the fcntl/ioctl command to the file descriptor handled by a file instance.

Refer to "fcntl(2)" or "ioctl(2)" in the "Linux Programmer's Manual" associated with your distribution for commands. Please note that any operations out of the command specifications may cause unexpected problems.

Name	Type	M/O	Summary	Note
cmd	number	mandatory	fcntl/ioctl command Range: 0x00000000 - 0xFFFFFFFF
arg	number, ArrayBuffer	optional	fcntl/ioctl command argument number : Used to execute commands that specify command arguments directly as numerical values. Range: 0x00000000 - 0xFFFFFFFF ArrayBuffer : Used to execute commands that require a buffer pointer in the command argument. If any of the setting commands are executed, the pre-set data to ArrayBuffer will be passed. The maximum buffer size that can be handled is 1024 bytes. If the specified ArrayBuffer size exceeds that, it will be truncated to the maximum size. If any of the getting commands are executed, the data in the specified ArrayBuffer is overwritten and updated. If the data size written by the command exceeds the ArrayBuffer size, it is truncated to the ArrayBuffer size. Note that commands that exceed 1024 bytes of data being written by the command cannot be handled.
return	number	-	fcntl/ioctl return value Specifications differ depending on the command handled. In most cases, 0 on success and -1 on failure.	If the parameter is abnormal, an exception occurs.

The following is a usage example.

var cmd = 0x1234; //A command to be specified by a numerical value [dummy]
var arg = 0x0800;
var ret = file.ioctl(cmd, arg);
if(ret == 0) print('OK');

var cmd = 0x1234; //A setting command specified by a buffer pointer [dummy]
var buf = new ArrayBuffer(16);
var arr = new Uint8Array(buf);
//Parameter pre-setting
for(var i=0; i<arr.length; i++) arr[i] = 0;
arr[0] = 0x01;
var ret = file.ioctl(cmd, buf);
if(ret == 0) print('OK');

var cmd = 0x1234; //A getting command specified by a buffer pointer [dummy]
var buf = new ArrayBuffer(32);
var arr = new Uint8Array(buf);
var ret = file.ioctl(cmd, buf); //'buf' will be overwritten
if(ret == 0) {
    for(var i=0; i<arr.length; i++) print(arr[i]);
}

.close()

Closes a file and releases a file resource.

Name	Type	M/O	Summary	Note
return	undefined	-	-

---

Object Usage Examples

Sample 1

This is a sample of file writing and file reading.
Writes a multi-line string to a file and reads it out 1 line at a time.

var filePath = '/tmp/test.txt';
var file = fs.fopen(filePath, 'w+');
file.write('abc\ndefg\nhijklmn\nopqrstuvwxyz');
file.sync();
var position = file.getPosition();
print('position: ' + position.toString());
file.setPosition(0);
while(1) {
    var str = file.read(false, true, 128);
    if(str.length) print(str.replace(/\n/g, ''));
    else break;
}
var sts = file.getStatus();
for(var key in sts) {
    print(key + ': ' + sts[key]);
}
file.close();
file = undefined;
fs.remove(filePath);

Sample 2

This is a sample of file writing and file reading.
Writes a binary to a file and reads it out.

var filePath = '/tmp/test.bin';
var file = fs.fopen(filePath, 'w+');
var wbin = new ArrayBuffer(16);
var wArr = new Uint8Array(wbin);
for(var i=0; i<wArr.length; i++) {
    wArr[i] = i;
}
file.write(wbin);
file.sync();
var position = file.getPosition();
print('position: ' + position.toString());
file.setPosition(0);
var rBin = file.read(true);
var rArr = new Uint8Array(rBin);
for(var i=0; i<rArr.length; i++) {
    print(rArr[i].toString());
}
var sts = file.getStatus();
for(var key in sts) {
    print(key + ': ' + sts[key]);
}
file.close();
file = undefined;
fs.remove(filePath);

Sample 3

This is a sample of checking the existence of directories and files, obtaining information, creating, copying, renaming, and changing permissions.

var dirPath = '/tmp/test0/';
var filePath1 = dirPath + 'test1.bin';
var filePath2 = dirPath + 'test2.bin';
var filePath3 = dirPath + 'test3.bin';

var stat = fs.stat(dirPath);
if(stat == null) {
    fs.mkdir(dirPath);
}

var file = fs.fopen(filePath1, 'w+');
file.write('0123456789ABCEDF');
file.close();
file = undefined;

print('### rename ### filePath1 to filePath2');
fs.rename(filePath1, filePath2);

var stat = fs.stat(filePath1);
print('filePath: ' + filePath1);
if(stat == null) print('no such file');
for(var key in stat) {
    print(key + ': ' + stat[key]);
}

var stat = fs.stat(filePath2);
print('filePath: ' + filePath2);
if(stat == null) print('no such file');
for(var key in stat) {
    print(key + ': ' + stat[key]);
}

print('### configure ### filePath2 0644');
fs.configure(filePath2, {permission:'0644'});

var stat = fs.stat(filePath2);
print('filePath: ' + filePath2);
if(stat == null) print('no such file');
for(var key in stat) {
    print(key + ': ' + stat[key]);
}

print('### copy ### filePath2 to filePath3');
fs.fcopy(filePath2, filePath3);

var stat = fs.stat(filePath2);
print('filePath: ' + filePath2);
if(stat == null) print('no such file');
for(var key in stat) {
    print(key + ': ' + stat[key]);
}

var stat = fs.stat(filePath3);
print('filePath: ' + filePath3);
if(stat == null) print('no such file');
for(var key in stat) {
    print(key + ': ' + stat[key]);
}

fs.remove(filePath2);
fs.remove(filePath3);
fs.remove(dirPath);

---

Updated: 2023-05-30