fuse - Dateisystem im Benutzermodus (FUSE)-Gerät
SYNOPSIS
#include <linux/fuse.h>
DESCRIPTION
Dieses Gerät ist die primäre Schnittstelle zwischen dem FUSE-Dateisystemtreiber und einem Benutzerprozess, der das Dateisystem bereitstellen möchte (im Rest dieser Manpage als Dateisystem-Daemon bezeichnet). Diese Manpage richtet sich an diejenigen, die die Kernel-Schnittstelle verstehen möchten. Für die Implementierung eines FUSE-Dateisystems kann es sinnvoll sein, eine Benutzerbibliothek wie libfuse zu verwenden, die die Low-Level-Schnittstelle abstrahiert.
Im Kern ist FUSE ein einfaches Client-Server-Protokoll, bei dem der Linux-Kernel der Client und der Daemon der Server ist. Nachdem ein Dateideskriptor für dieses Gerät erhalten wurde, kann der Daemon Anfragen von diesem Dateideskriptor lesen (read(2)) und die Antworten (write(2)) an dieses Dateideskriptor zurückschreiben. Es ist wichtig zu beachten, dass ein Dateideskriptor einem eindeutigen FUSE-Dateisystem zugeordnet ist. Das Öffnen einer zweiten Kopie dieses Geräts ermöglicht keinen Zugriff auf Ressourcen, die über den ersten Dateideskriptor erstellt wurden (und umgekehrt).
Das grundlegende Protokoll
Jede Nachricht, die vom Daemon gelesen wird, beginnt mit einem Header, der durch die folgende Struktur beschrieben wird:
struct fuse_in_header {
uint32_t len; /* Gesamtgröße der Daten,
einschließlich dieses Headers */
uint32_t opcode; /* Art der Operation (siehe unten) */
uint64_t unique; /* Eine eindeutige Kennung für diese Anfrage */
uint64_t nodeid; /* ID des Dateisystemobjekts,
auf das die Operation angewendet wird */
uint32_t uid; /* UID des anfragenden Prozesses */
uint32_t gid; /* GID des anfragenden Prozesses */
uint32_t pid; /* PID des anfragenden Prozesses */
uint32_t padding;
};
Auf den Header folgt ein datenvariabler Teil (der leer sein kann), der für die angeforderte Operation spezifisch ist (die angeforderte Operation wird durch Opcode angegeben).
Der Daemon sollte dann die Anfrage verarbeiten und – falls zutreffend – eine Antwort senden, indem er in das Dateideskriptor schreibt (write(2)). Fast alle Operationen erfordern eine Antwort; falls nicht, ist dies unten dokumentiert.
Alle Antworten müssen mit dem folgenden Header beginnen:
struct fuse_out_header {
uint32_t len; /* Gesamtgröße der in das
Dateideskriptor geschriebenen Daten */
int32_t error; /* Ein aufgetretener Fehler (0, wenn keiner) */
uint64_t unique; /* Der Wert aus der
entsprechenden Anfrage */
};
Dieser Header wird ebenfalls von datenvariablen Daten begleitet (potenziell leer), je nach der ausgeführten Anfrage. Wenn die Antwort jedoch eine Fehlermeldung ist (d. h. error ist gesetzt), werden keine weiteren Nutzdaten gesendet, unabhängig von der Anfrage.
Ausgetauschte Nachrichten
Dieser Abschnitt sollte eine Dokumentation für jede der Nachrichten im Protokoll enthalten. Diese Handbuchseite ist derzeit unvollständig, daher werden nicht alle Nachrichten dokumentiert. Für jede Nachricht wird zuerst die vom Kernel gesendete Struktur angegeben, gefolgt von einer Beschreibung der Semantik der Nachricht.
FUSE_INIT
struct fuse_init_in {
uint32_t major;
uint32_t minor;
uint32_t max_readahead; /* Seit Protokoll v7.6 */
uint32_t flags; /* Seit Protokoll v7.6 */
};
Dies ist die erste Anfrage, die der Kernel an den Daemon sendet. Sie wird verwendet, um die Protokollversion und andere Dateisystemparameter auszuhandeln. Beachten Sie, dass die Protokollversion das Layout jeder Struktur im Protokoll beeinflussen kann (einschließlich dieser Struktur). Der Daemon muss sich daher die ausgehandelte Version und die Flags für jede Sitzung merken. Zum Zeitpunkt des Schreibens dieser Handbuchseite ist die höchste vom Kernel unterstützte Protokollversion 7.26.
Benutzer sollten sich bewusst sein, dass die Beschreibungen in dieser Handbuchseite für ältere oder neuere Protokollversionen unvollständig oder falsch sein können.
Die Antwort für diese Anfrage hat das folgende Format:
struct fuse_init_out {
uint32_t major;
uint32_t minor;
uint32_t max_readahead; /* Seit v7.6 */
uint32_t flags; /* Seit v7.6; einige Flags wurden später hinzugefügt */
uint16_t max_background; /* Seit v7.13 */
uint16_t congestion_threshold; /* Seit v7.13 */
uint32_t max_write; /* Seit v7.5 */
uint32_t time_gran; /* Seit v7.6 */
uint32_t unused[9];
};
Wenn die vom Kernel unterstützte Hauptversion größer ist als die vom Daemon unterstützte, besteht die Antwort nur aus uint32_t major (folgend auf den üblichen Header), wodurch die höchste vom Daemon unterstützte Hauptversion angezeigt wird. Der Kernel sendet dann eine neue FUSE_INIT-Anfrage, die der älteren Version entspricht. Im umgekehrten Fall sollte der Daemon stillschweigend auf die Hauptversion des Kernels zurückgreifen.
Die ausgehandelte Nebenversion wird als das Minimum der vom Daemon und vom Kernel bereitgestellten Nebenversionen betrachtet, und beide Parteien sollten das dem entsprechenden Protokoll zugeordnete Protokoll verwenden.
FUSE_GETATTR
struct fuse_getattr_in {
uint32_t getattr_flags;
uint32_t dummy;
uint64_t fh; /* Nur setzen, wenn
(getattr_flags & FUSE_GETATTR_FH)
};
Die angeforderte Operation ist die Berechnung der von stat(2) und ähnlichen Operationen für das gegebene Dateisystemobjekt zurückzugebenden Attribute. Das Objekt, für das die Attribute berechnet werden sollen, wird entweder durch header->nodeid oder, falls das Flag FUSE_GETATTR_FH gesetzt ist, durch den Dateihandle fh angegeben. Letzterer Fall der Operation ist analog zu fstat(2).
Aus Leistungsgründen können diese Attribute für einen bestimmten Zeitraum im Kernel zwischengespeichert werden. Solange die Cache-Timeout-Dauer nicht überschritten wurde, werden die Attribute aus dem Cache geliefert und verursachen keine zusätzlichen FUSE_GETATTR-Anfragen.
Die berechneten Attribute und der angeforderte Cache-Timeout sollten dann in der folgenden Struktur zurückgegeben werden:
struct fuse_attr_out {
/* Attribut-Cache-Dauer (Sekunden + Nanosekunden) */
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;
};
Wenn die default_permissions-Mount-Option nicht verwendet wird, kann diese Anforderung für die Berechtigungsprüfung verwendet werden. Es werden keine Antwortdaten erwartet, aber Fehler können wie gewohnt durch Setzen des Fehlerfelds im Antwort-Header angezeigt werden (insbesondere können Fehler aufgrund von Berechtigungsverweigerungen durch Rückgabe von -EACCES angezeigt werden).
FUSE_OPEN
FUSE_OPENDIR
struct fuse_open_in {
uint32_t flags; /* Die Flags, die an den open(2)-Aufruf übergeben wurden */
uint32_t unused;
};
Die angeforderte Operation ist das Öffnen des Knotens, der durch header->nodeid angegeben wird. Die genauen Semantiken davon hängen vom implementierten Dateisystem ab. Das Dateisystem sollte jedoch zumindest überprüfen, ob die angeforderten Flags für die angegebene Ressource gültig sind, und dann eine Antwort im folgenden Format senden:
struct fuse_open_out {
uint64_t fh;
uint32_t open_flags;
uint32_t padding;
};
Das Feld fh ist eine undurchsichtige Kennung, die der Kernel verwenden wird, um auf diese Ressource zu verweisen. Das Feld open_flags ist eine Bitmaske, die eine beliebige Anzahl von Flags enthält, die Eigenschaften dieser Dateihandle für den Kernel angeben:
FOPEN_DIRECT_IO Umgeht den Seiten-Cache für diese geöffnete Datei.
FOPEN_KEEP_CACHE Ungültigt den Daten-Cache beim Öffnen nicht.
FOPEN_NONSEEKABLE Die Datei ist nicht seekfähig.
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;
};
Die angeforderte Aktion ist das Lesen von bis zu size Bytes der Datei oder des Verzeichnisses, beginnend bei offset. Die Bytes sollten direkt nach dem üblichen Antwort-Header zurückgegeben werden.
FUSE_INTERRUPT
struct fuse_interrupt_in {
uint64_t unique;
};
Die angeforderte Aktion ist das Abbrechen der ausstehenden Operation, die durch unique angegeben wird. Diese Anforderung erfordert keine Antwort. Der Empfang dieser Nachricht bricht die angegebene Operation jedoch nicht automatisch ab. Der Kernel erwartet weiterhin eine Antwort auf diese Operation (z. B. ein EINTR-Fehler oder ein kurzes Lesen). Für eine bestimmte Operation wird höchstens eine FUSE_INTERRUPT-Anforderung ausgegeben. Nachdem diese Anforderung ausgegeben wurde, wartet der Kernel ununterbrochen auf den Abschluss der angegebenen Anforderung.
FUSE_LOOKUP
Direkt nach dem Header folgt ein Dateiname, der im Verzeichnis gesucht werden soll, das durch header->nodeid angegeben wird. Die erwartete Antwort hat das folgende Format:
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;
};
Die Kombination aus nodeid und generation muss für die gesamte Lebensdauer des Dateisystems eindeutig sein.
Die Interpretation der Timeouts und von attr entspricht der von FUSE_GETATTR.
FUSE_FLUSH
struct fuse_flush_in {
uint64_t fh;
uint32_t unused;
uint32_t padding;
uint64_t lock_owner;
};
Die angeforderte Aktion besteht darin, alle ausstehenden Änderungen für den angegebenen Dateideskriptor zu leeren. Es werden keine Antwortdaten erwartet. Es muss jedoch eine leere Antwortnachricht gesendet werden, sobald der Flush-Vorgang abgeschlossen ist.
FUSE_RELEASE
FUSE_RELEASEDIR
struct fuse_release_in {
uint64_t fh;
uint32_t flags;
uint32_t release_flags;
uint64_t lock_owner;
};
Dies sind die Umkehrungen von FUSE_OPEN bzw. FUSE_OPENDIR. Der Daemon kann jetzt
alle Ressourcen freigeben, die mit dem Dateideskriptor fh verbunden sind, da das Kernel nicht mehr darauf verweisen wird. Für diese Anfrage werden keine Antwortdaten benötigt, aber eine Antwort
muss gesendet werden, sobald die Anfrage vollständig verarbeitet wurde.
FUSE_STATFS
Diese Operation implementiert statfs(2) für dieses Dateisystem. Es gibt keine Eingabedaten, die mit dieser Anfrage verbunden sind. Die erwarteten Antwortdaten haben die folgende Struktur:
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;
};
Die Interpretation dieser Felder finden Sie in statfs(2).
FEHLER
E2BIG Wird von `read(2)`-Operationen zurückgegeben, wenn die Anfrage des Kernels für den bereitgestellten
Puffer zu groß ist und die Anfrage `FUSE_SETXATTR` war.
EINVAL Wird von `write(2)` zurückgegeben, wenn die Validierung der Antwort fehlgeschlagen ist. Nicht alle Fehler in den Antworten
werden durch diese Validierung erfasst. Allerdings werden grundlegende Fehler, wie z. B. kurze Antworten oder
ein inkorrekter eindeutiger Wert, erkannt.
EIO Wird von `read(2)`-Operationen zurückgegeben, wenn die Anfrage des Kernels für den bereitgestellten
Puffer zu groß ist.
Hinweis: Es gibt verschiedene Möglichkeiten, wie eine inkorrekte Verwendung dieser Schnittstellen dazu führen kann, dass Operationen an den Dateien und Verzeichnissen des bereitgestellten
Dateisystems mit EIO fehlschlagen. Zu den möglichen inkorrekten Verwendungen gehören:
Ändern des Modus und von `S_IFMT` für einen Inode, der dem Kernel zuvor gemeldet wurde; oder
Senden von Antworten an den Kernel, die kürzer sind, als der Kernel erwartet.
ENODEV Wird von `read(2)` und `write(2)` zurückgegeben, wenn das FUSE-Dateisystem ausgehängt wurde.
EPERM Wird von Operationen auf einem `/dev/fuse`-Dateideskriptor zurückgegeben, der nicht gemountet wurde.
STANDARDS
Linux.
HINWEISE
Die folgenden Nachrichten sind in dieser Handbuchseite noch nicht dokumentiert:
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
SIEHE AUCH
fusermount(1), mount.fuse(8)