fuse - ユーザー空間ファイルシステム (FUSE) デバイス
概要
#include <linux/fuse.h>
説明
このデバイスは、FUSE ファイルシステムドライバと、ファイルシステムを提供しようとするユーザー空間プロセス（このマニュアルの残りの部分では「ファイルシステムデーモン」と呼びます）間の主要なインターフェースです。このマニュアルページは、カーネルインターフェースを理解することに関心のあるユーザーを対象としています。FUSE ファイルシステムを実装するユーザーは、libfuse などのユーザー空間ライブラリを使用して、低レベルのインターフェースを抽象化することを検討できます。
FUSE の中核は、Linux カーネルがクライアントで、デーモンがサーバーである単純なクライアント-サーバープロトコルです。このデバイスのファイル記述子を取得した後、デーモンはファイル記述子からリクエストを読み取り (read(2)) 、それに対応する応答を書き込む (write(2)) ことが予想されます。ファイル記述子は、一意の FUSE ファイルシステムに関連付けられていることに注意することが重要です。特に、このデバイスの 2 番目のコピーを開いても、最初のファイル記述子を通じて作成されたリソースにアクセスすることはできません (逆も同様です)。
基本プロトコル
デーモンによって読み取られるすべてのメッセージは、次の構造で始まるヘッダーから始まります。
struct fuse_in_header {
uint32_t len; /* データ全体のサイズ。
このヘッダーも含む */
uint32_t opcode; /* 操作の種類（以下を参照） */
uint64_t unique; /* このリクエストの一意の識別子 */
uint64_t nodeid; /* 処理中のファイルシステムオブジェクトの ID */
uint32_t uid; /* リクエストを行うプロセスの UID */
uint32_t gid; /* リクエストを行うプロセスの GID */
uint32_t pid; /* リクエストを行うプロセスの PID */
uint32_t padding;
};
ヘッダーの後に、リクエストされた操作（opcode で示される）に固有の可変サイズのデータ部分が続きます。
次に、デーモンはリクエストを処理し、必要に応じて応答を送信します（ほとんどの操作には応答が必要であり、そうでない場合は以下に記載されています）。応答は、ファイル記述子に書き込むことによって送信されます。すべての応答は、次のヘッダーで始まる必要があります。
struct fuse_out_header {
uint32_t len; /* ファイル記述子に書き込まれるデータの合計サイズ */
int32_t error; /* 発生したエラー（エラーがない場合は 0） */
uint64_t unique; /* 該当するリクエストからの値 */
};
このヘッダーの後にも、実行されたリクエストに応じて、(場合によっては空の) 可変サイズのデータが続きます。ただし、応答がエラー応答である場合 (つまり、error が設定されている場合)、リクエストに関係なく、それ以上のペイロードデータは送信しないでください。
交換されたメッセージ
このセクションには、プロトコルの各メッセージのドキュメントが含まれている必要があります。このマニュアルページは現在不完全であるため、すべてのメッセージがドキュメント化されているわけではありません。各メッセージについて、最初にカーネルによって送信される構造体が与えられ、次にメッセージのセマンティクスの説明が続きます。
FUSE_INIT
struct fuse_init_in {
uint32_t major;
uint32_t minor;
uint32_t max_readahead; /* プロトコル v7.6 以降 */
uint32_t flags; /* プロトコル v7.6 以降 */
};
これは、カーネルからデーモンに送信される最初の要求です。これは、プロトコルのバージョンとその他のファイルシステムパラメータをネゴシエートするために使用されます。プロトコルのバージョンは、プロトコル内の任意の構造のレイアウト（この構造を含む）に影響を与える可能性があることに注意してください。したがって、デーモンは、各セッションのネゴシエートされたバージョンとフラグを記憶する必要があります。このマニュアルページが作成された時点で、カーネルがサポートする最も高いプロトコルバージョンは 7.26 です。
ユーザーは、このマニュアルページの説明が、古いバージョンまたは新しいバージョンのプロトコルでは不完全であるか、または正しくない可能性があることに注意する必要があります。
この要求に対する応答は、次の形式になります。
struct fuse_init_out {
uint32_t major;
uint32_t minor;
uint32_t max_readahead; /* v7.6 以降 */
uint32_t flags; /* v7.6 以降。一部のフラグビットは 後に追加されました \*/
uint16_t max_background; /* v7.13 以降 */
uint16_t congestion_threshold; /* v7.13 以降 */
uint32_t max_write; /* v7.5 以降 */
uint32_t time_gran; /* v7.6 以降 */
uint32_t unused[9];
};
カーネルによってサポートされるメジャーバージョンが、デーモンによってサポートされるメジャーバージョンよりも大きい場合、応答は uint32_t major のみで構成されます（通常のヘッダーに続いて）。これにより、デーモンがサポートする最大のメジャーバージョンが示されます。次に、カーネルは、古いバージョンに準拠した新しい FUSE_INIT 要求を発行します。逆の場合、デーモンはカーネルのメジャーバージョンに静かにフォールバックする必要があります。
ネゴシエートされたマイナーバージョンは、デーモンとカーネルによって提供されるマイナーバージョンの最小値と見なされ、両方のパーティは、前記マイナーバージョンに対応するプロトコルを使用する必要があります。
FUSE_GETATTR
struct fuse_getattr_in {
uint32_t getattr_flags;
uint32_t dummy;
uint64_t fh; /* 次の場合にのみ設定されます。
(getattr_flags & FUSE_GETATTR_FH)
};
要求される操作は、stat(2) などの操作によって返される属性を計算することです。属性を計算する対象のファイルシステムオブジェクトは、header->nodeid によって示されるか、または FUSE_GETATTR_FH フラグが設定されている場合は、ファイルハンドル fh によって示されます。後者の操作は、fstat(2) と似ています。
パフォーマンス上の理由から、これらの属性はカーネルに特定の期間キャッシュできます。キャッシュのタイムアウトが超過していない場合、属性はキャッシュから提供され、追加の FUSE_GETATTR 要求は行われません。
計算された属性と要求されたキャッシュのタイムアウトは、次の構造で返される必要があります。
struct fuse_attr_out {
/* 属性キャッシュの有効期間（秒 + ナノ秒） */
uint64_t attr_valid;
uint32_t attr_valid_nsec;
uint32_t dummy;
struct fuse_attr {
uint64_t ino;
uint64_t size;
uint64_t blocks;
uint64_t atime;
uint64_t mtime;
uint64_t ctime;
uint32_t atimensec;
uint32_t mtimensec;
uint32_t ctimensec;
uint32_t mode;
uint32_t nlink;
uint32_t uid;
uint32_t gid;
uint32_t rdev;
uint32_t blksize;
uint32_t padding;
} attr;
};
FUSE_ACCESS
struct fuse_access_in {
uint32_t mask;
uint32_t padding;
};
default_permissions マウントオプションが使用されていない場合、このリクエストは権限チェックに使用できます。返信データは必要ありませんが、エラーは、返信ヘッダーのエラーフィールドを設定することで通常どおり示すことができます（特に、アクセス拒否エラーは、-EACCESを返すことで示すことができます）。
FUSE_OPEN
FUSE_OPENDIR
struct fuse_open_in {
uint32_t flags; /* open(2)に渡されたフラグ */
uint32_t unused;
};
要求された操作は、ヘッダー->nodeidで示されたノードを開くことです。正確な意味は、実装されているファイルシステムによって異なります。ただし、少なくともファイルシステムは、要求されたフラグが示されたリソースに対して有効であることを検証し、次に次の形式で返信を送信する必要があります。
struct fuse_open_out {
uint64_t fh;
uint32_t open_flags;
uint32_t padding;
};
fhフィールドは、カーネルがこのリソースを参照するために使用する不透明な識別子です。open_flagsフィールドは、カーネルにこのファイルハンドルに関する特性を示すフラグの任意の数のビットマスクです。
FOPEN_DIRECT_IO ページキャッシュをこのオープンファイルに対してバイパスします。
FOPEN_KEEP_CACHE オープン時にデータキャッシュを無効にしません。
FOPEN_NONSEEKABLE ファイルはシークできません。
FUSE_READ
FUSE_READDIR
struct fuse_read_in {
uint64_t fh;
uint64_t offset;
uint32_t size;
uint32_t read_flags;
uint64_t lock_owner;
uint32_t flags;
uint32_t padding;
};
要求されたアクションは、オフセットから始まり、最大サイズバイトのファイルまたはディレクトリを読み取ることです。バイトは、通常どおりの返信ヘッダーの直後に返される必要があります。
FUSE_INTERRUPT
struct fuse_interrupt_in {
uint64_t unique;
};
要求されたアクションは、uniqueによって示される保留中の操作をキャンセルすることです。このリクエストには応答は必要ありません。ただし、このメッセージを受信しただけでは、示された操作はそれ自体ではキャンセルされません。カーネルは、依然として、この操作への応答を期待します（例：EINTRエラーまたは短い読み取り）。一度FUSE_INTERRUPTリクエストが発行された後、カーネルは、示されたリクエストの完了を中断なしで待ちます。
FUSE_LOOKUP
ヘッダー->nodeidで示されたディレクトリで、次のファイル名が検索されます。予期される応答は次のとおりです。
struct fuse_entry_out {
uint64_t nodeid; /* inode ID */
uint64_t generation; /* inode generation */
uint64_t entry_valid;
uint64_t attr_valid;
uint32_t entry_valid_nsec;
uint32_t attr_valid_nsec;
struct fuse_attr attr;
};
nodeidとgenerationの組み合わせは、ファイルシステムのライフタイムを通じて一意でなければなりません。
timeoutとattrの解釈は、FUSE_GETATTRの場合と同じです。
FUSE_FLUSH
struct fuse_flush_in {
uint64_t fh;
uint32_t unused;
uint32_t padding;
uint64_t lock_owner;
};
要求されるアクションは、指定されたファイルハンドルに対する保留中の変更をフラッシュすることです。応答データは期待されません。ただし、フラッシュ操作が完了したら、空の応答メッセージを送信する必要があります。
FUSE_RELEASE
FUSE_RELEASEDIR
struct fuse_release_in {
uint64_t fh;
uint32_t flags;
uint32_t release_flags;
uint64_t lock_owner;
};
これらは、それぞれFUSE_OPENおよびFUSE_OPENDIRの逆の操作です。デーモンは、カーネルがこれ以上ファイルハンドルfhを参照しないため、fhに関連付けられたリソースをすべて解放できます。この要求には関連する応答データはありませんが、要求が完全に処理された後でも応答を送信する必要があります。
FUSE_STATFS
この操作は、このファイルシステムに対するstatfs(2)を実装します。この要求には入力データは関連付けられていません。期待される応答データは、次の構造体です。
struct fuse_kstatfs {
uint64_t blocks;
uint64_t bfree;
uint64_t bavail;
uint64_t files;
uint64_t ffree;
uint32_t bsize;
uint32_t namelen;
uint32_t frsize;
uint32_t padding;
uint32_t spare[6];
};
struct fuse_statfs_out {
struct fuse_kstatfs st;
};
これらのフィールドの解釈については、statfs(2)を参照してください。
エラー
E2BIG read(2)操作から、カーネルのリクエストが提供されたバッファに対して大きすぎる場合に返されます。また、リクエストがFUSE\_SETXATTRの場合にも返されます。
EINVAL write(2)から、応答の検証に失敗した場合に返されます。応答の誤りすべてがこの検証によって検出されるわけではありません。ただし、短い応答や、一意の値が正しくないなど、基本的な誤りは検出されます。
EIO read(2)操作から、カーネルのリクエストが提供されたバッファに対して大きすぎる場合に返されます。
注：これらのインターフェースの誤った使用方法は、提供されたファイルシステムのファイルとディレクトリに対する操作がEIOで失敗する原因となる可能性があります。誤った使用方法の例としては、次のものがあります。
カーネルに以前に報告されたinodeのモードとS\_IFMTを変更する。または
カーネルが期待するよりも短い応答をカーネルに送信する。
ENODEV read(2)およびwrite(2)から、FUSEファイルシステムがアンマウントされた場合に返されます。
EPERM /dev/fuseファイル記述子がマウントされていない場合に、操作から返されます。
標準
Linux。
注意
次のメッセージは、このマニュアルページではまだドキュメント化されていません。
FUSE_BATCH_FORGET
FUSE_BMAP
FUSE_CREATE
FUSE_DESTROY
FUSE_FALLOCATE
FUSE_FORGET
FUSE_FSYNC
FUSE_FSYNCDIR
FUSE_GETLK
FUSE_GETXATTR
FUSE_IOCTL
FUSE_LINK
FUSE_LISTXATTR
FUSE_LSEEK
FUSE_MKDIR
FUSE_MKNOD
FUSE_NOTIFY_REPLY
FUSE_POLL
FUSE_READDIRPLUS
FUSE_READLINK
FUSE_REMOVEXATTR
FUSE_RENAME
FUSE_RENAME2
FUSE_RMDIR
FUSE_SETATTR
FUSE_SETLK
FUSE_SETLKW
FUSE_SYMLINK
FUSE_UNLINK
FUSE_WRITE
関連項目
fusermount(1), mount.fuse(8)