Man page - fuse(4)

Packages contains this manual

Package: manpages
apt-get install manpages

Manuals in package:

Documentations in package:

manpages

Available languages:

en fr ru ro

Manual

fuse

NOM
SYNOPSIS
DESCRIPTION
Protocole de base
Messages échangées
ERREURS
STANDARDS
NOTES
VOIR AUSSI
TRADUCTION

NOM

fuse — périphérique FUSE (Filesystem in Userspace)

SYNOPSIS

#include <linux/fuse.h>

DESCRIPTION

Ce périphérique est l’interface principale entre le pilote du système de fichiers FUSE et un processus en espace utilisateur voulant fournir le système de fichiers (référé dans le reste de cette page de manuel comme démon du système de fichiers ). Cette page de manuel est destinée à ceux qui veulent comprendre l’interface du noyau elle-même. Ceux mettant en œuvre un système de fichiers FUSE peuvent utiliser une bibliothèque en espace utilisateur telle que libfuse qui permet de faire abstraction de l’interface de bas niveau.

En substance, FUSE est un protocole client-serveur simple, dans lequel le noyau Linux est le client et le démon le serveur. Après l’obtention d’un descripteur de fichier pour ce périphérique, le démon peut lire ( read (2)) les requêtes de ce descripteur de fichier et est présumé écrire ( write (2)) en retour les réponses. Il est important de noter que ce descripteur de fichier est associé à un système de fichiers FUSE unique. En particulier, l’ouverture d’une seconde copie de ce périphérique ne permet pas l’accès aux ressources crées à travers le premier descripteur de fichier (et vice versa).

Protocole de base

Chaque message lu par le démon commence par un en-tête décrit par la structure suivante :

struct fuse_in_header {
uint32_t len; /* Taille totale des données,
incluant cet en-tête */
uint32_t opcode; /* Le type d’opération (voir ci-après) */
uint64_t unique; /* Un identifiant unique pour cette requête */
uint64_t nodeid; /* ID de l’objet de système de fichiers
qui est manipulé */
uint32_t uid; /* UID du processus requérant */
uint32_t gid; /* GID du processus requérant */
uint32_t pid; /* PID du processus requérant */
uint32_t padding;
};

L’en-tête est suivi d’une partie de données de taille variable (pouvant être vide) spécifique à l’opération demandée (l’opération demandée est indiquée par opcode ).

Le démon doit alors traiter la requête et, si applicable, envoyer une réponse (presque toutes les opérations demandent une réponse — si ce n’est le cas, cela est documenté ci-après) en réalisant un write (2) pour le descripteur de fichier. Toutes les réponses doivent débuter par l’en-tête suivant :

struct fuse_out_header {
uint32_t len; /* Taille totale des données écrites
sur le descripteur de fichier */
int32_t error; /* Toute erreur produite (0 si aucune) */
uint64_t unique; /* La valeur de la requête correspondante */
};

Cet en-tête est aussi suivi par des données (potentiellement absentes) de taille variable dépendant de la requête exécutée. Cependant, si la réponse est une réponse d’erreur (c’est-à-dire, error est définie), alors plus aucunes données de charge utile ne seront envoyées, indépendamment de la requête.

Messages échangées

Cette section devrait contenir la documentation de chacun des messages du protocole. Cette page de manuel est actuellement incomplète, aussi tous les messages ne sont pas documentés. Pour chaque message, la structure envoyée par le noyau est fournie en premier, suivie par une description des sémantiques du message.
FUSE_INIT

struct fuse_init_in {
uint32_t major;
uint32_t minor;
uint32_t max_readahead; /* Depuis la version 7.6 du protocole */
uint32_t flags; /* Depuis la version 7.6 du protocole */
};

C’est la première requête envoyée par le noyau au démon. Elle est utilisée pour négocier la version de protocole et les autres paramètres de système de fichiers. Il est à remarquer que la version de protocole peut affecter la disposition de n’importe quelle structure dans le protocole (y compris celle-ci). Le démon doit par conséquent se souvenir de la version négociée et des drapeaux de chaque session. Au moment de l’écriture de cette page de manuel, la version de protocole la plus récente prise en charge par le noyau est la version 7.26 .

Les utilisateurs doivent faire attention à ce que les descriptions dans cette page de manuel peuvent être incorrectes ou incomplètes pour les versions de protocole plus anciennes ou plus récentes.

La réponse à cette requête est du format suivant :

struct fuse_init_out {
uint32_t major;
uint32_t minor;
uint32_t max_readahead; /* Depuis la version 7.6 */
uint32_t flags; /* Depuis la version 7.6 ; quelques bits
de drapeaux ont été ajoutés après */
uint16_t max_background; /* Depuis la version 7.13 */
uint16_t congestion_threshold; /* Depuis la version 7.13 */
uint32_t max_write; /* Depuis la version 7.5 */
uint32_t time_gran; /* Depuis la version 7.6 */
uint32_t unused[9];
};

Si la version majeure prise en charge par le noyau est supérieure à celle prise en charge par le démon, la réponse sera constituée de seulement uint32_t major (suivi par l’en-tête habituel), indiquant la version majeure la plus élevée prise en charge par le démon. Le noyau produira alors une nouvelle requête FUSE_INIT se conformant à l’ancienne version. Dans le cas contraire, le démon reviendra silencieusement à la version majeure du noyau.

La version mineure négociée est considérée comme la version mineure minimale fournie par le démon et le noyau, et les deux parties doivent utiliser le protocole correspondant pour ladite version mineure.

FUSE_GETATTR

struct fuse_getattr_in {
uint32_t getattr_flags;
uint32_t dummy;
uint64_t fh; /* Défini seulement si
(getattr_flags & FUSE_GETATTR_FH)
};

L’opération requise est de déterminer les attributs que stat (2) doit renvoyer et les opérations similaires pour l’objet indiqué de système de fichiers. L’objet pour lequel les attributs doivent être déterminés est indiqué soit par header->nodeid ou, si le drapeau FUSE_GETATTR_FH est défini, par le gestionnaire de fichier fh . Le dernier cas d’opération est analogue à fstat (2).

Pour des raisons de performance, ces attributs peuvent être mis en cache dans le noyau pendant une durée indiquée. Tant que la temporisation du cache n’est pas dépassée, les attributs seront servis à partir du cache et ne provoqueront pas de requêtes FUSE_GETATTR supplémentaires.

Les attributs calculés et la temporisation de cache demandée doivent alors être renvoyés dans la structure suivante :

struct fuse_attr_out {
/* Temporisation de cache d’attributs (secondes + nanosecondes) */
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;
};

Si l’option default_permissions de montage n’est pas utilisée, cette requête peut être utilisée pour la vérification des permissions. Aucunes données de réponse ne sont attendues, mais les erreurs peuvent être indiquées comme d’habitude en réglant le champ error dans l’en-tête de réponse (en particulier, les erreurs de refus d’accès peuvent être indiquées en renvoyant -EACCES ).

FUSE_OPEN et FUSE_OPENDIR

struct fuse_open_in {
uint32_t flags; /* Les drapeaux qui étaient passés
à open(2) */
uint32_t unused;
};

L’opération demandée est d’ouvrir le nœud indiqué par header->nodeid . Les sémantiques exactes de ce que cela signifie dépendent du système de fichiers mis en œuvre. Cependant, à tout le moins, le système de fichiers doit valider que les drapeaux demandés sont valables pour la ressource indiquée et alors envoyer une réponse de format suivant :

struct fuse_open_out {
uint64_t fh;
uint32_t open_flags;
uint32_t padding;
};

Le champ fh est un identifiant opaque que le noyau utilise pour référer à cette ressource. Le champ open_flags est un masque de bits de n’importe quel nombre de drapeaux qui indiquent les propriétés de ce gestionnaire de fichier au noyau :

	FOPEN_DIRECT_IO		Contournement de ce cache de pages pour ce fichier ouvert.
	FOPEN_KEEP_CACHE		Ne pas invalider le cache de données lors de l’ouverture.
	FOPEN_NONSEEKABLE		Ce fichier ne peut être parcouru.

FUSE_READ et 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;
};

L’action demandée est de lire jusqu’à size d’octets du fichier ou du répertoire, en commençant à offset . Les octets sont renvoyés directement en suivant l’en-tête de réponse habituel.

FUSE_INTERRUPT

struct fuse_interrupt_in {
uint64_t unique;
};

L’action demandée est d’annuler l’opération en attente indiquée par unique . Cette requête ne demande aucune réponse. Cependant, la réception de ce message n’annule pas par lui-même l’opération indiquée. Le noyau attendra toujours une réponse à ladite opération (par exemple, une erreur EINTR ou une lecture courte). Au plus une requête FUSE_INTERRUPT sera faite pour une opération donnée. Après l’émission de ladite opération, le noyau attendra de façon ininterrompue pour l’achèvement de la requête indiquée.

FUSE_LOOKUP

Directement à la suite de l’en-tête est un nom de fichier à rechercher dans le répertoire indiqué par header->nodeid . La réponse attendue est de la forme :

struct fuse_entry_out {
uint64_t nodeid; /* Id d’inœud */
uint64_t generation; /* Génération d’inœud */
uint64_t entry_valid;
uint64_t attr_valid;
uint32_t entry_valid_nsec;
uint32_t attr_valid_nsec;
struct fuse_attr attr;
};

La combinaison de nodeid et generation doit être unique pour toute la durée de vie du système de fichiers.

L’interprétation des temporisations et de attr est comme pour FUSE_GETATTR .

FUSE_FLUSH

struct fuse_flush_in {
uint64_t fh;
uint32_t unused;
uint32_t padding;
uint64_t lock_owner;
};

L’action demandée est de vider toute modification en attente dans le gestionnaire de fichiers indiqué. Aucune donnée de réponse n’est attendue. Cependant, un message de réponse vide doit toujours être émis une fois que l’opération de vidage est terminée.

FUSE_RELEASE et FUSE_RELEASEDIR

struct fuse_release_in {
uint64_t fh;
uint32_t flags;
uint32_t release_flags;
uint64_t lock_owner;
};

Ce sont les opposés de FUSE_OPEN et FUSE_OPENDIR respectivement. Le démon peut désormais libérer toute ressource associée avec le gestionnaire de fichier fh , car le noyau ne se référera plus à celui-ci. Il n’y a aucune donnée de réponse associée à la requête, mais une réponse doit toujours être fournie une fois que la requête a été complètement traitée.

FUSE_STATFS

L’opération met en œuvre statfs (2) pour ce système de fichiers. Il n’y a aucune donnée d’entrée associée à cette requête. Les données de réponse attendues ont la structure suivante :

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;
};

Pour l’interprétation de ces champs, consulter statfs (2).

ERREURS

	E2BIG		Renvoyé par les opérations read (2) quand la requête du noyau est trop grande pour le tampon fourni et que la requête était FUSE_SETXATTR .
	EINVAL		Renvoyé par write (2) si la validation de la réponse échoue. Toutes les erreurs dans les réponses ne seront pas capturées par cette validation. Cependant les fautes basiques, telles que les réponses courtes ou une valeur unique incorrecte, sont détectées.
	EIO		Renvoyé par les opérations read (2) quand la requête du noyau est trop grande pour le tampon fourni.

Remarque : il existe diverses façons par lesquelles l’utilisation incorrecte de ces interfaces peut faire que les opérations sur les fichiers et les répertoires indiqués du système de fichiers échouent avec EIO . Parmi les utilisations incorrectes possibles :

	-		la modification de mode & S_IFMT pour un inœud ayant été rapportée auparavant au noyau ;
	-		la fourniture de réponses au noyau plus courtes que ce que le noyau attendait.
	ENODEV

Renvoyé par read (2) et write (2) si le système de fichiers FUSE a été démonté.

EPERM

Renvoyé par les opérations sur un descripteur de fichier /dev/fuse n’ayant pas été monté.

STANDARDS

Linux.

NOTES

Les messages suivants ne sont pas encore documentés dans cette page de manuel :

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

VOIR AUSSI

fusermount (1), mount.fuse (8)

TRADUCTION

La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Jean-Paul Guillonneau <guillonneau.jeanpaul@free.fr>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n’y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à debian-l10n-french@lists.debian.org .