Provided by: manpages-fr_4.23.1-1_all 
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 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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⟩.