◇ gasfs: GORRY's archive and slice file system
  Hiroaki GOTO as GORRY / http://GORRY.hauN.org/
  Version 20210205a

========================================================================
1. 概要
========================================================================

gasfsは、いくつかのスライスから構成されるアーカイブをストレージとする
ファイルシステムです。「多くのファイルをパッキングして収録したいが、
１ファイルではサイズが大きすぎるため分割したい」ときに使用します。

========================================================================
2. mkgasfs
========================================================================

mkgasfsは、アーカイブへ収録するファイル群の情報を記述した「gfiファイル」を
読み込み、それに基づいてアーカイブを作成します。
mkgasfsのヘルプを表示するには、「mkgasfs --help」を実行します。

1. 入力の指定

   「mkgasfs [input.gfi]」を実行すると、指定したgfiファイルを読んで
   アーカイブを作成します。
   gfiファイルには、アーカイブに収録するファイル群を列挙します。

2. オプション
   mkgasfsは、以下のオプションを解釈します。

   --output [filename]
     出力するアーカイブのファイル名を[filename]とします。
     実際には、スライス番号と拡張子"_000.gfs"～"_255.gfs"が付加された
     ファイルを出力します。
     このオプションを指定しない場合、入力に指定したgfiファイルの
     ベース名部分を出力するアーカイブのファイル名とします。

   --basedir [dir]
     アーカイブに収録するファイル群が存在するディレクトリを指定します。
     このオプションが存在しない場合、カレントディレクトリに入力ファイル
     群があるものとして扱います。
     ここで指定するディレクトリ名は、入力gfiファイルや、アーカイブの出力
     先には影響を与えません。

   --list [list.gfi]
     アーカイブの作成が終わったあと、実際に収録したファイル群に基づいた
     gfiファイルを出力します。この出力ファイルは、そのまま次回のmkgasfs
     実行時の入力に使用することができます。

   --verbose
     詳細な状況出力を行います。

========================================================================
3. exgasfs
========================================================================

exgasfsは、アーカイブに収録されたファイル群を抽出します。
exgasfsのヘルプを表示するには、「mkgasfs --help」を実行します。

1. 入力の指定

   「mkgasfs [input]」を実行すると、アーカイブのデータベースファイル
   [input_000.gfs]を読み込み、アーカイブ中に収録されたファイル群を
   認識します。
   「mkgasfs [input] [filter1] [filter2] ...」のように、[filter]を
   指定すると、ファイル群のうち[filter]と前方一致するパス名のファイル
   のみを対象とします。[filter]をひとつも指定しない場合、全てのファイルを
   対象とします。

2. オプション
   mkgasfsは、以下のオプションを解釈します。

   --extract [dir]
     抽出したファイルを[dir]へ出力します。このオプションが指定されない
     場合、ファイルの抽出は行われません。

   --slice [num]
     指定した番号のスライスのみを対象とします。
     このオプションが指定されない場合、全てのスライスを対象とします。

   --list [list.gfi]
     アーカイブの抽出が終わったあと、実際に抽出したファイル群に基づいた
     gfiファイルを出力します。この出力ファイルは、そのまま次回のmkgasfs
     実行時の入力に使用することができます。

   --skipcheckcrc
     アーカイブ抽出時のCRCエラーチェックを行いません。結果として、
     CRCエラーが発見された場合でも、処理を中断しません。
     データベースファイルのCRCエラーチェックは常に行われます。

   --verbose
     詳細な状況出力を行います。

========================================================================
4. gfiファイルについて
========================================================================

gfiファイルは、mkgasfsに対して入力する「アーカイブへ収録するファイル群」を
列挙したものです。以下のフォーマットで記述します。

--------

# グローバル情報
[Global]
# このアーカイブのスライス数を指定
Slices=4
# １スライスの最大サイズ（MB単位）
MaxSliceSize=512

# 入力パスリスト
[Input]
PathList=[[[[
# アーカイブへの収録候補とするファイルの情報を、１行につき１つ記述する。
# 空行や、"#"で始まる行はスキップされる。
# ここに列挙された候補から、以下のルールでスライスへ収録する。
# ・スライス側で収録対象と指定されているファイルを、そのスライスへ固定で割り当てる。
# ・固定割り当て中にそのスライスの容量に達したら、その時点で中止する。
# ・すべての収録対象の割り当てが終わったら、まだ割り当てが決まっていない
#   ファイルに対し、先頭のスライスから順に収録容量に達するまで動的に割り当てる。
# ・動的割り当て中に全スライスの容量に達したら、その時点で中止する。
	*.*

# アーカイブの情報を終了
]]]]

# 必ずスライス"001"に入れる内容
[001]
PathList=[[[[
# スライスへの収録対象とするファイルの情報を、１行につき１つ記述する。
# 空行や、"#"で始まる行はスキップされる。

# 収録対象とするファイルのパス名をそのまま記述する。
# 行頭／行末はタブやスペースを含んでもスキップされる。
	file1.txt

# ディレクトリ名を含んでもよい。階層構造もそのまま記録される。
	subdir/file2.txt

# ワイルドカードを含んでもよい。
	*.dat
	*.bin

# ディレクトリ名を書くと、そのディレクトリ下の全ファイルが収録対象となる。
# そのディレクトリにサブディレクトリがある場合、それも収録対象となる。
	dir1/

# "****"というパス名を与えると、このスライスへの収録対象に指定されていない
# ファイル群をこのスライスに追加することを禁止する。
	****

# スライスへの情報を終了
]]]]

# 必ずスライス"002"に入れる内容
[002]
PathList=[[[[
	Baz/Foo/*.*
]]]]

# 必ずスライス"003"に入れる内容
[003]
PathList=[[[[
	dir3/
]]]]

# 以上で指定されなかったファイルは、空いているスライスに入る

#[EOF]

--------

mkgasfsは、以下の順序でアーカイブ作業を行います。

   a. [Input]セクションで指定されるパスリストを読み込みます。

   b. 読み込んだファイル群のうち、各スライスのセクションのパスリストに
      列挙されたファイル群を、各スライスに収録します。

   c. どのスライスのセクションのパスリストにも含まれなかったファイル群を、
      最初のスライスに収録します。最初のスライスが最大容量に達した場合、
      収録先は次のスライスへ移動します。

   d. 全てのファイル群の収録先スライスが決定したら、実際にスライスを
      拡張子"_001.gfs"～"_255.gfs"で出力していきます。全てのスライスを
      出力したら、データベースを拡張子"_000.gfs"で出力します。

mkgasfsは、「入力gfiファイル・スライスファイル・それに収録されるファイル
群」の更新時刻を認識します。これらのうちでスライスファイルの更新時刻が
最も新しい（更新の必要がない）場合、そのスライスファイルの更新はスキップ
されます。
更新時刻を無視してスライスファイルを出力したい場合は、--forceオプションを
指定することができます。

mkgasfsの実行時に「--list」オプションを付加すると、実際に収録した全ての
ファイルの情報を持ったgfiファイルを書き出すことができます。
同様に、exgasfsの実行時に「--list」オプションを付加すると、抽出した
全てのファイルの情報を持ったgfiファイルを書き出すことができます。

========================================================================
5. アーカイブ形式について
========================================================================

mkgasfsは、".gfs"という拡張子を持ったファイルをアーカイブとして扱います。
通し番号"_000"はアーカイブのデータベース、"_001"～"_255"はアーカイブの
中身を分割した「スライス」となります。

データベースには、以下のように情報が記録されます。

1. ヘッダ
   データベースファイルの先頭には、0x20バイトのヘッダ情報が記録されます。

     +00  "G"
     +01  "F"
     +02  "S"
     +03  "3"
     +04  アーカイブのスライス数（1～255）
     +05  ファイルエントリ数（第1バイト）
     +06  ファイルエントリ数（第2バイト）
     +07  ファイルエントリ数（第3バイト）
     +08  データベースの実データサイズ（第1バイト）
     +09  データベースの実データサイズ（第2バイト）
     +0a  データベースの実データサイズ（第3バイト）
     +0b  データベースの実データサイズ（第4バイト）
     +0c  最大スライスサイズ（メガバイト単位）（第1バイト）
     +0d  最大スライスサイズ（メガバイト単位）（第2バイト）
     +0e  最大スライスサイズ（メガバイト単位）（第3バイト）
     +0f  最大スライスサイズ（メガバイト単位）（第4バイト）
     +10  CRC（第1バイト）
     +11  CRC（第2バイト）
     +12  CRC（第3バイト）
     +13  CRC（第4バイト）
     +14  タイムスタンプ（第1バイト）
     +15  タイムスタンプ（第2バイト）
     +16  タイムスタンプ（第3バイト）
     +17  タイムスタンプ（第4バイト）
     +18  タイムスタンプ（第5バイト）
     +19  タイムスタンプ（第6バイト）
     +1a  タイムスタンプ（第7バイト）
     +1b  予約(0で固定)
     +1c  パディング（合計0x20バイト, 0で固定）

   約1600万ファイルの収録が可能です。
   データベースの実データサイズは、「ファイルサイズ-ヘッダサイズ(32)」を示します。
   CRCは、「ヘッダ以降末尾バイトまでのCRC」を示します。
   タイムスタンプは、「2021/04/07 18:45:01」なら"20 21 04 07 18 45 01"の
   HEXバイト列になります。時刻はGMTで扱われます。

2. サブヘッダ
   ヘッダに続いて、各スライスのサブヘッダと同一のデータがスライス数だけ
   記録されます。

     +00  "g"
     +01  "F"
     +02  "S"
     +03  "3"
     +04  アーカイブのスライス数（1～255）
     +05  ファイル数（第1バイト）
     +06  ファイル数（第2バイト）
     +07  ファイル数（第3バイト）
     +08  スライスの実データサイズ（第1バイト）
     +09  スライスの実データサイズ（第2バイト）
     +0a  スライスの実データサイズ（第3バイト）
     +0b  スライスの実データサイズ（第4バイト）
     +0c  スライスの実データサイズ（第5バイト）
     +0d  スライスの実データサイズ（第6バイト）
     +0e  スライスの実データサイズ（第7バイト）
     +0f  スライスの実データサイズ（第8バイト）
     +10  CRC（第1バイト）
     +11  CRC（第2バイト）
     +12  CRC（第3バイト）
     +13  CRC（第4バイト）
     +14  タイムスタンプ（第1バイト）
     +15  タイムスタンプ（第2バイト）
     +16  タイムスタンプ（第3バイト）
     +17  タイムスタンプ（第4バイト）
     +18  タイムスタンプ（第5バイト）
     +19  タイムスタンプ（第6バイト）
     +1a  タイムスタンプ（第7バイト）
     +1b  予約(0で固定)
     +1c  パディング（合計0x20バイト, 0で固定）

   各スライスファイルの先頭には、このサブヘッダが付属します。
   スライスファイルをキャッシュする場合、「サブヘッダが同一である場合は
   スライスファイルの内容が同一である」ことが保証されます。
   スライスの実データサイズは、「ファイルサイズ-サブヘッダサイズ(32)」を示します。
   CRCは、「サブヘッダ以降末尾バイトまでのCRC」を示します。
   タイムスタンプは、「2021/04/07 18:45:01」なら"20 21 04 07 18 45 01"の
   HEXバイト列になります。時刻はGMTで扱われます。

3. ファイルエントリ
   サブヘッダに続いて、16バイトのファイル情報が、ファイルエントリ数の分だけ
   記録されます。

     +00  収録スライス番号（1～255）
     +01  パス名へのオフセット（第1バイト）
     +02  パス名へのオフセット（第2バイト）
     +03  パス名へのオフセット（第3バイト）
     +04  ファイル実体へのオフセット（第1バイト）
     +05  ファイル実体へのオフセット（第2バイト）
     +06  ファイル実体へのオフセット（第3バイト）
     +07  ファイル実体へのオフセット（第4バイト）
     +08  ファイル実体へのオフセット（第5バイト）
     +09  ファイル実体へのオフセット（第6バイト）
     +10  ファイル実体のサイズ（第1バイト）
     +11  ファイル実体のサイズ（第2バイト）
     +12  ファイル実体のサイズ（第3バイト）
     +13  ファイル実体のサイズ（第4バイト）
     +14  ファイル実体のサイズ（第5バイト）
     +15  ファイル実体のサイズ（第6バイト）

   「パス名へのオフセット」は、パス名情報先頭からの位置となります。
   「最初のパス名」へのオフセット値が0となります。

   「ファイル実体へのオフセット」は、スライスのサブヘッダ終了後からの位置と
   なります。「各スライスの最初にあるファイル実体」へのオフセット値が0と
   なります。

4. ファイルエントリ
   ファイル情報に続いて、"\0"を終端文字とした各ファイルのパス名が、
   ファイルエントリ数の分だけ記録されます。収録文字コードは次項を
   ご覧ください。

========================================================================
5. 文字コードについて
========================================================================

mkgasfs/exgasfsは、実行環境のロケールに基づいた文字コードでの処理が
行われます。環境変数LANGに以下を指定することで、gfiファイルを解釈する
時の文字コードや、「アーカイブのデータベース」に記録される文字コードが
以下のように規定されます。

  - 無指定、または"ja-JP"
    Shift-JIS

  - ".utf8"
    UTF-8

========================================================================
6. 著作権表記
========================================================================

本プロダクトは、「Apache License Version 2.0」で配布されます。
このライセンスに基づいての使用・再配布が許可されます。

「Apache License Version 2.0」のライセンス条文は、以下からお読みいただ
けます。

- http://www.apache.org/licenses/LICENSE-2.0.txt （オリジナル）
- http://sourceforge.jp/projects/opensource/wiki/licenses%2FApache_License_2.0
  （日本語参考訳）

========================================================================
7. 連絡先
========================================================================

後藤 浩昭 / GORRY
http://GORRY.hauN.org/
twitter/gorry5

========================================================================
[EOF]