fuse(4) Device Drivers Manual fuse(4) NOM fuse -- peripherique FUSE (Filesystem in Userspace) SYNOPSIS #include DESCRIPTION Ce peripherique est l'interface principale entre le pilote du systeme de fichiers FUSE et un processus en espace utilisateur voulant fournir le systeme de fichiers (refere dans le reste de cette page de manuel comme demon du systeme de fichiers). Cette page de manuel est destinee a ceux qui veulent comprendre l'interface du noyau elle-meme. Ceux mettant en oeuvre un systeme de fichiers FUSE peuvent utiliser une bibliotheque 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 demon le serveur. Apres l'obtention d'un descripteur de fichier pour ce peripherique, le demon peut lire (read(2)) les requetes de ce descripteur de fichier et est presume ecrire (write(2)) en retour les reponses. Il est important de noter que ce descripteur de fichier est associe a un systeme de fichiers FUSE unique. En particulier, l'ouverture d'une seconde copie de ce peripherique ne permet pas l'acces aux ressources crees a travers le premier descripteur de fichier (et vice versa). Protocole de base Chaque message lu par le demon commence par un en-tete decrit par la structure suivante : struct fuse_in_header { uint32_t len; /* Taille totale des donnees, incluant cet en-tete */ uint32_t opcode; /* Le type d'operation (voir ci-apres) */ uint64_t unique; /* Un identifiant unique pour cette requete */ uint64_t nodeid; /* ID de l'objet de systeme de fichiers qui est manipule */ uint32_t uid; /* UID du processus requerant */ uint32_t gid; /* GID du processus requerant */ uint32_t pid; /* PID du processus requerant */ uint32_t padding; }; L'en-tete est suivi d'une partie de donnees de taille variable (pouvant etre vide) specifique a l'operation demandee (l'operation demandee est indiquee par opcode). Le demon doit alors traiter la requete et, si applicable, envoyer une reponse (presque toutes les operations demandent une reponse -- si ce n'est le cas, cela est documente ci-apres) en realisant un write(2) pour le descripteur de fichier. Toutes les reponses doivent debuter par l'en-tete suivant : struct fuse_out_header { uint32_t len; /* Taille totale des donnees ecrites sur le descripteur de fichier */ int32_t error; /* Toute erreur produite (0 si aucune) */ uint64_t unique; /* La valeur de la requete correspondante */ }; Cet en-tete est aussi suivi par des donnees (potentiellement absentes) de taille variable dependant de la requete executee. Cependant, si la reponse est une reponse d'erreur (c'est-a-dire, error est definie), alors plus aucunes donnees de charge utile ne seront envoyees, independamment de la requete. Messages echangees Cette section devrait contenir la documentation de chacun des messages du protocole. Cette page de manuel est actuellement incomplete, aussi tous les messages ne sont pas documentes. Pour chaque message, la structure envoyee par le noyau est fournie en premier, suivie par une description des semantiques 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 premiere requete envoyee par le noyau au demon. Elle est utilisee pour negocier la version de protocole et les autres parametres de systeme de fichiers. Il est a remarquer que la version de protocole peut affecter la disposition de n'importe quelle structure dans le protocole (y compris celle-ci). Le demon doit par consequent se souvenir de la version negociee et des drapeaux de chaque session. Au moment de l'ecriture de cette page de manuel, la version de protocole la plus recente prise en charge par le noyau est la version 7.26. Les utilisateurs doivent faire attention a ce que les descriptions dans cette page de manuel peuvent etre incorrectes ou incompletes pour les versions de protocole plus anciennes ou plus recentes. La reponse a cette requete 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 ete ajoutes apres */ 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 superieure a celle prise en charge par le demon, la reponse sera constituee de seulement uint32_t major (suivi par l'en-tete habituel), indiquant la version majeure la plus elevee prise en charge par le demon. Le noyau produira alors une nouvelle requete FUSE_INIT se conformant a l'ancienne version. Dans le cas contraire, le demon reviendra silencieusement a la version majeure du noyau. La version mineure negociee est consideree comme la version mineure minimale fournie par le demon 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; /* Defini seulement si (getattr_flags & FUSE_GETATTR_FH) }; L'operation requise est de determiner les attributs que stat(2) doit renvoyer et les operations similaires pour l'objet indique de systeme de fichiers. L'objet pour lequel les attributs doivent etre determines est indique soit par header->nodeid ou, si le drapeau FUSE_GETATTR_FH est defini, par le gestionnaire de fichier fh. Le dernier cas d'operation est analogue a fstat(2). Pour des raisons de performance, ces attributs peuvent etre mis en cache dans le noyau pendant une duree indiquee. Tant que la temporisation du cache n'est pas depassee, les attributs seront servis a partir du cache et ne provoqueront pas de requetes FUSE_GETATTR supplementaires. Les attributs calcules et la temporisation de cache demandee doivent alors etre renvoyes 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 utilisee, cette requete peut etre utilisee pour la verification des permissions. Aucunes donnees de reponse ne sont attendues, mais les erreurs peuvent etre indiquees comme d'habitude en reglant le champ error dans l'en-tete de reponse (en particulier, les erreurs de refus d'acces peuvent etre indiquees en renvoyant -EACCES). FUSE_OPEN et FUSE_OPENDIR struct fuse_open_in { uint32_t flags; /* Les drapeaux qui etaient passes a open(2) */ uint32_t unused; }; L'operation demandee est d'ouvrir le noeud indique par header->nodeid. Les semantiques exactes de ce que cela signifie dependent du systeme de fichiers mis en oeuvre. Cependant, a tout le moins, le systeme de fichiers doit valider que les drapeaux demandes sont valables pour la ressource indiquee et alors envoyer une reponse 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 referer a cette ressource. Le champ open_flags est un masque de bits de n'importe quel nombre de drapeaux qui indiquent les proprietes 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 donnees lors de l'ouverture. FOPEN_NONSEEKABLE Ce fichier ne peut etre 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 demandee est de lire jusqu'a size d'octets du fichier ou du repertoire, en commencant a offset. Les octets sont renvoyes directement en suivant l'en-tete de reponse habituel. FUSE_INTERRUPT struct fuse_interrupt_in { uint64_t unique; }; L'action demandee est d'annuler l'operation en attente indiquee par unique. Cette requete ne demande aucune reponse. Cependant, la reception de ce message n'annule pas par lui-meme l'operation indiquee. Le noyau attendra toujours une reponse a ladite operation (par exemple, une erreur EINTR ou une lecture courte). Au plus une requete FUSE_INTERRUPT sera faite pour une operation donnee. Apres l'emission de ladite operation, le noyau attendra de facon ininterrompue pour l'achevement de la requete indiquee. FUSE_LOOKUP Directement a la suite de l'en-tete est un nom de fichier a rechercher dans le repertoire indique par header->nodeid. La reponse attendue est de la forme : struct fuse_entry_out { uint64_t nodeid; /* Id d'inoeud */ uint64_t generation; /* Generation d'inoeud */ 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 etre unique pour toute la duree de vie du systeme de fichiers. L'interpretation 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 demandee est de vider toute modification en attente dans le gestionnaire de fichiers indique. Aucune donnee de reponse n'est attendue. Cependant, un message de reponse vide doit toujours etre emis une fois que l'operation de vidage est terminee. 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 opposes de FUSE_OPEN et FUSE_OPENDIR respectivement. Le demon peut desormais liberer toute ressource associee avec le gestionnaire de fichier fh, car le noyau ne se referera plus a celui-ci. Il n'y a aucune donnee de reponse associee a la requete, mais une reponse doit toujours etre fournie une fois que la requete a ete completement traitee. FUSE_STATFS L'operation met en oeuvre statfs(2) pour ce systeme de fichiers. Il n'y a aucune donnee d'entree associee a cette requete. Les donnees de reponse 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'interpretation de ces champs, consulter statfs(2). ERREURS E2BIG Renvoye par les operations read(2) quand la requete du noyau est trop grande pour le tampon fourni et que la requete etait FUSE_SETXATTR. EINVAL Renvoye par write(2) si la validation de la reponse echoue. Toutes les erreurs dans les reponses ne seront pas capturees par cette validation. Cependant les fautes basiques, telles que les reponses courtes ou une valeur unique incorrecte, sont detectees. EIO Renvoye par les operations read(2) quand la requete du noyau est trop grande pour le tampon fourni. Remarque : il existe diverses facons par lesquelles l'utilisation incorrecte de ces interfaces peut faire que les operations sur les fichiers et les repertoires indiques du systeme de fichiers echouent avec EIO. Parmi les utilisations incorrectes possibles : - la modification de mode & S_IFMT pour un inoeud ayant ete rapportee auparavant au noyau ; - la fourniture de reponses au noyau plus courtes que ce que le noyau attendait. ENODEV Renvoye par read(2) et write(2) si le systeme de fichiers FUSE a ete demonte. EPERM Renvoye par les operations sur un descripteur de fichier /dev/fuse n'ayant pas ete monte. STANDARDS Linux. NOTES Les messages suivants ne sont pas encore documentes 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 francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Paul Guillonneau Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 fuse(4)