11. FileSystem

fsオブジェクトは、ファイルシステム内の任意ファイルへアクセスする機能を提供する組み込みオブジェクトです。

機能概要:

• ファイルまたはディレクトリの情報取得、コピー、リネーム、削除、パーミッション変更機能を提供します。
• シーケンシャルアクセスによるファイル読み書き機能を提供します。
• ランダムアクセスによるファイル読み書き機能を提供します。

制限事項:

• 使用可能なファイルリソースは5本です。(Version 00.00.04+) (旧バージョン: 3)

---

fs Global Object

Methods()/Properties	Summary	Version	Note
fs.stat()	ファイルまたはディレクトリの詳細情報を取得します。
fs.configure()	ファイルまたはディレクトリの設定を変更します。
fs.rename()	ファイル名またはディレクトリ名を変更します。
fs.remove()	ファイルまたはディレクトリを削除します。
fs.mkdir()	ディレクトリを作成します。
fs.fcopy()	ファイルをコピーします。
fs.fopen()	ファイルをオープンし、ファイルインスタンスを生成します。

---

Details

fs.stat(path)

ファイルまたはディレクトリの詳細情報を取得します。

Name	Type	M/O	Summary	Note
path	string	mandatory	ファイルまたはディレクトリパスを指定します。 例: /tmp/dir1, /tmp/dir1/test.txt
return	{Stat}, null	-	{Stat} : ファイル情報 (ファイルまたはディレクトリが存在する場合) null : ファイル情報が取得できなかった場合 (ファイルまたはディレクトリが存在しない場合)	パラメータ異常の場合は例外となります。

{Stat}

Name	Type	Summary	Note
.isFile	boolean	ファイルか否か
.isDirectory	boolean	ディレクトリか否か
.size	number	全体のサイズ[Byte]
.blksize	number	最適なI/Oブロックサイズ[Byte]
.atime	number	最終アクセス時刻 (unixtime[ms])
.mtime	number	最終修正時刻 (unixtime[ms])
.ctime	number	最終状態変更時刻 (unixtime[ms])
.permission	string	パーミッション 8進数表記文字列となります。 例: '0777', '0754'
.uid	number	所有者のユーザーID
.gid	number	所有者のグループID
.owner	string	所有者のユーザー名
.group	string	所有者のグループ名

fs.configure(path,options)

ファイルまたはディレクトリの設定を変更します。

Name	Type	M/O	Summary	Note
path	string	mandatory	ファイルまたはディレクトリパスを指定します。 例: /tmp/dir1, /tmp/dir1/test.txt
options	Object	mandatory	オプション 詳細はOptionsを参照してください。
return	boolean	-	true : 成功 false : 失敗	パラメータ異常の場合は例外となります。

Options

Name	Type	M/O	Summary	Note
permission	string	optional	パーミッションを変更します。 8進数表記文字列で指定します。 例: '0777', '0754'
owner	number, string	optional	所有者のユーザーを変更します。 所有者のユーザーID(number型)または所有者のユーザー名(string型)を指定します。尚、指定のユーザーは既に作成済みである必要があります。新規登録はできません。
group	number, string	optional	所有者のグループを変更します。 所有者のグループID(number型)または所有者のグループ名(string型)を指定します。尚、指定のグループは既に作成済みである必要があります。新規登録はできません。

fs.rename(oldPath,newPath)

ファイル名またはディレクトリ名を変更します。

Name	Type	M/O	Summary	Note
oldPath	string	mandatory	変更元のファイルまたはディレクトリパスを指定します。 例: /tmp/dir1, /tmp/dir1/test.txt
newPath	string	mandatory	変更先のファイルまたはディレクトリパスを指定します。 例: /tmp/dir2, /tmp/dir1/test2.txt
return	boolean	-	true : 成功 false : 失敗	パラメータ異常の場合は例外となります。

fs.remove(path)

ファイルまたはディレクトリを削除します。
尚、ディレクトリを削除する場合、対象ディレクトリ下が空である必要があります。

Name	Type	M/O	Summary	Note
path	string	mandatory	ファイルまたはディレクトリパスを指定します。 例: /tmp/dir1, /tmp/dir1/test.txt
return	boolean	-	true : 成功 false : 失敗	パラメータ異常の場合は例外となります。

fs.mkdir(path[,options])

ディレクトリを作成します。
尚、再帰的にディレクトリを作成することはできません。

Name	Type	M/O	Summary	Note
path	string	mandatory	新規ディレクトリパスを指定します。 例: /tmp/dir2
options	Object	optional	オプション 詳細はOptionsを参照してください。	ディレクトリは所有者'root'、パーミッション'0777'で作成されます。変更する場合はオプションで指定します。
return	boolean	-	true : 成功 false : 失敗	パラメータ異常の場合は例外となります。

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

ファイルをコピーします。
尚、コピー先のディレクトリパスが存在している必要があります。

Name	Type	M/O	Summary	Note
srcPath	string	mandatory	コピー元ファイルパスを指定します。 例: /tmp/dir1/test.txt
dstPath	string	mandatory	コピー先ファイルパスを指定します。 例: /tmp/dir2/test2.txt
options	Object	optional	オプション 詳細はOptions及び本メソッド専用の追加オプションを参照してください。	ファイルの所有者およびパーミッション設定はコピー元の設定が継承されます。変更する場合はオプションで指定します。
return	boolean	-	true : 成功 false : 失敗	パラメータ異常の場合は例外となります。

Additional options for .fcopy() only

Name	Type	M/O	Summary	Note
overwrite	boolean	optional	ファイルの上書き設定 true: 上書きを許可します。 false: 上書きを禁止します。 デフォルト値はtrueとなります。	上書きを禁止設定で、コピー先にファイルが存在していた場合、失敗となります。

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

ファイルをオープンし、ファイルインスタンスを生成します。
尚、対象ファイルのディレクトリが存在している必要があります。

Name	Type	M/O	Summary	Note
path	string	mandatory	ファイルパスを指定します。 例: /tmp/dir1/test.txt
flags	string	mandatory	オープンフラグを指定します。 'r': 読み取り専用 'w': 新規書き込み(上書き)専用 'a': 追記書き込み専用 'r+': 読み取り及び書き込み 'w+': 新規書き込み(上書き)及び読み取り 'a+': 追記書き込み及び読み取り	すべてバイナリ扱いで処理されます。
options	Object	optional	オプション 詳細はOptions及び本メソッド専用の追加オプションを参照してください。	ファイルが新規作成された場合、所有者'root'、パーミッション'0666'となります。変更する場合はオプションで指定します。
return	{File}, null	-	{File} : 生成された{File} null : ファイルがオープンできなかった場合	パラメータ異常の場合は例外となります。

Additional options for .fopen() only

Name	Type	M/O	Summary	Note
buffering	boolean	optional	ストリームバッファリング true: 有効 (fully buffered) false: 無効 (unbuffered) デフォルト値はtrueとなります。	Version 00.00.04+

---

{File}

Methods()/Properties	Summary	Version	Note
.read()	ファイルからデータを読み出します。
.write()	ファイルにデータを書き込みます。
.getStatus()	現時点のファイルステータスを取得します。
.getPosition()	現時点のファイル位置(ファイル位置指示子)を設定します。
.setPosition()	ファイル位置(ファイル位置指示子)を変更します。
.sync()	ファイル書き込みにより更新されたメモリ上のデータ(キャッシュ)をストレージデバイスに転送します。
.fcntl() / .ioctl()	ファイルインスタンスがハンドリングしているファイルディスクリプタに対してfcntl/ioctlコマンドを実行します。	00.00.04+
.close()	ファイルをクローズし、ファイルリソースを解放します。

---

Details

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

ファイルからデータを読み出します。

Name	Type	M/O	Summary	Note
isBin	boolean	optional	読み出しデータの形式を指定します。 true: バイナリデータ形式で読み出し false: 文字列形式で読み出し デフォルト値はfalseとなります。
line	boolean	optional	1ライン読み出し 改行文字までの1ラインデータを読み出します。 true: 有効 false: 無効 デフォルト値はfalseとなります。	1ラインのデータが最大読み出しサイズを超えた場合は、分割読み出しとなります。
size	number	optional	最大読み出しサイズ[Byte] 設定範囲: 1～2,147,483,647 デフォルト値は4096となります。
return	ArrayBuffer, string	-	読み出しデータ 戻り値の型はisBinで決定されます。 trueを指定した場合はArrayBuffer型、falseを指定した場合は、string型となります。	読み出しデータは最大読み出しサイズ以下となります。読み出しデータがない場合はサイズが0となります。 パラメータ異常の場合は例外となります。

.write(data[,flush])

ファイルにデータを書き込みます。

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	mandatory	書き込みデータ
flush	boolean	optional	ストリーム強制出力 データ書き込み後、フラッシュ処理を実行します。 true: 有効 false: 無効 デフォルト値はtrueとなります。	Version 00.00.04+
return	number	-	書き込まれたデータサイズ	書き込みが失敗した場合、指定した書き込みデータ長より小さい値となります。 パラメータ異常の場合は例外となります。

.getStatus()

現時点のファイルステータスを取得します。
尚、本メソッド呼び出し後、ファイルステータスはクリアされます。

Name	Type	M/O	Summary	Note
return	{FileStatus}	-	{FileStatus} : ファイルステータス

{FileStatus}

Name	Type	Summary	Note
.eof	number	EOF(end-of-file)指示子状態 ファイルの終わりに到達したか否か 0: 到達していない 以外: 到達した
.err	number	エラー指示子状態 ファイル読出しまたは書き込み処理でエラーが発生したか否か 0: 発生していない 以外: 発生した

.getPosition()

現時点のファイル位置(ファイル位置指示子)を取得します。

Name	Type	M/O	Summary	Note
return	number	-	現時点のオフセット値 失敗した場合は-1が返却されます。

.setPosition(offset[,whence])

ファイル位置(ファイル位置指示子)を設定します。
whenceで指定された位置からoffsetバイトを加えた位置に移動します。

Name	Type	M/O	Summary	Note
offset	number	mandatory	オフセット 設定範囲: -2,147,483,648～2,147,483,647
whence	number	optional	基準位置 0: ファイルの先頭 1: 現在位置 2: ファイルの末尾 デフォルト値は0となります。
return	boolean	-	true: 成功 false: 失敗	パラメータ異常の場合は例外となります。

.sync([dataOnly])

ファイル書き込みにより更新されたメモリ上のデータ(キャッシュ)をストレージデバイスに転送します。

Name	Type	M/O	Summary	Note
dataOnly	boolean	optional	データのみ更新の対象とするか否かを指定します。 true: データのみ更新し、ファイルメタデータは更新しない false: データ及びファイルメタデータを更新する デフォルト値はfalseとなります。
return	boolean	-	true: 成功 false: 失敗	パラメータ異常の場合は例外となります。

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

ファイルインスタンスがハンドリングしているファイルディスクリプタに対してfcntl/ioctlコマンドを実行します。

コマンドについてはディストリビューションに関連した「Linux Programmer's Manual」の「fcntl(2)」もしくは「ioctl(2)」を参照してください。尚、コマンド仕様外の操作を行った場合、予期せぬ問題を引き起こす可能性がありますので注意願います。

Name	Type	M/O	Summary	Note
cmd	number	mandatory	fcntl/ioctlコマンド 設定範囲: 0x00000000～0xFFFFFFFF
arg	number, ArrayBuffer	optional	fcntl/ioctlコマンド引数 number : コマンド引数に直接数値を指定するコマンドを実行する場合に使用します。 設定範囲: 0x00000000～0xFFFFFFFF ArrayBuffer : コマンド引数にバッファポインタを必要とするコマンドを実行する場合に使用します。 いずれかの設定コマンドを実行した場合は、ArrayBufferに事前設定したデータが渡されます。取り扱い可能なバッファサイズは最大1024バイトまでとなります。指定したArrayBufferサイズがそれを超過している場合は、最大サイズで切り捨てられます。 いずれかの取得コマンドを実行した場合は、指定したArrayBufferのデータが上書き更新されます。コマンドによって書き込まれたデータサイズがArrayBufferサイズを超えた場合は、ArrayBufferサイズに切り捨てられます。尚、コマンドによって書き込まれるデータサイズが1024バイトを超えるコマンドは取り扱うことができません。
return	number	-	fcntl/ioctl戻り値 取り扱うコマンドによって仕様が異なります。 大抵の場合、成功時0、失敗時-1となります。	パラメータ異常の場合は例外となります。

下記は使用例となります。

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

ファイルをクローズし、ファイルリソースを解放します。

Name	Type	M/O	Summary	Note
return	undefined	-	-

---

オブジェクトの使用例

Sample 1

ファイル書き込みおよびファイル読み出しのサンプルです。
複数行の文字列をファイルに書き込み、1行ずつ読み出します。

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

ファイル書き込みおよびファイル読み出しのサンプルです。
バイナリをファイルに書き込み、読み出します。

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

ディレクトリおよびファイルの存在確認、情報取得、作成、コピー、リネーム、パーミッション変更のサンプルです。

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