fuse(4) Device Drivers Manual fuse(4) NUME fuse - dispozitiv cu sistem de fiiere in spaiul utilizatorului (,,Filesystem in Userspace": FUSE) SINOPSIS #include DESCRIERE Acest dispozitiv este interfaa principala dintre controlorul sistemului de fiiere FUSE i un proces din spaiul utilizatorului care dorete sa furnizeze sistemul de fiiere (denumit in restul acestei pagini de manual demon de sistem de fiiere). Aceasta pagina de manual este destinata celor interesai sa ineleaga interfaa nucleului in sine. Cei care implementeaza un sistem de fiiere FUSE pot dori sa utilizeze o biblioteca din spaiul utilizatorului, cum ar fi libfuse, care abstractizeaza interfaa de nivel scazut. In esena sa, FUSE este un protocol client-server simplu, in care nucleul Linux este clientul, iar demonul este serverul. Dupa obinerea unui descriptor de fiier pentru acest dispozitiv, demonul poate read(2) cereri de la acel descriptor de fiier i se ateapta sa write(2) inapoi raspunsurile sale. Este important de reinut ca un descriptor de fiier este asociat cu un sistem de fiiere FUSE unic. In special, deschiderea unei a doua copii a acestui dispozitiv, nu va permite accesul la resursele create prin intermediul primului descriptor de fiier (i viceversa). Protocolul de baza Fiecare mesaj citit de daemon incepe cu un antet descris de urmatoarea structura: struct fuse_in_header { uint32_t len; /* Dimensiunea totala a datelor, inclusiv acest antet */ uint32_t opcode; /* Tipul de operaie (a se vedea mai jos) */ uint64_t unique; /* Un identificator unic pentru aceasta cerere */ uint64_t nodeid; /* ID-ul obiectului sistemului de fiiere asupra caruia se opereaza */ uint32_t uid; /* UID-ul procesului solicitant */ uint32_t gid; /* GID-ul procesului solicitant */ uint32_t pid; /* PID-ul procesului solicitant */ uint32_t padding; }; Antetul este urmat de o poriune de date de dimensiune variabila (care poate fi goala) specifica operaiei solicitate (operaia solicitata este indicata prin opcode). Demonul ar trebui apoi sa proceseze cererea i, daca este cazul, sa trimita un raspuns (aproape toate operaiile necesita un raspuns; daca nu, acest lucru este documentat mai jos), prin efectuarea unui write(2) catre descriptorul de fiier. Toate raspunsurile trebuie sa inceapa cu urmatorul antet: struct fuse_out_header { uint32_t len; /* Dimensiunea totala a datelor scrise in descriptorul de fiier */ int32_t error; /* Orice eroare aparuta (0 daca nu exista) */ uint64_t unique; /* Valoarea din cererea corespondenta */ }; Acest antet este urmat, de asemenea, de date de dimensiune variabila (potenial goale) in funcie de cererea executata. Cu toate acestea, daca raspunsul este un raspuns de eroare (i anume, error este configurata), atunci nu trebuie trimise alte date utile, independent de cerere. Mesaje schimbate Aceasta seciune ar trebui sa conina documentaia pentru fiecare dintre mesajele din protocol. Aceasta pagina de manual este in prezent incompleta, astfel incat nu toate mesajele sunt documentate. Pentru fiecare mesaj, este prezentata mai intai structura trimisa de nucleu, urmata de o descriere a semanticii mesajului. FUSE_INIT struct fuse_init_in { uint32_t major; uint32_t minor; uint32_t max_readahead; /* Incepand cu protocolul v7.6 */ uint32_t flags; /* Incepand cu protocolul v7.6 */ }; Aceasta este prima solicitare trimisa de nucleu catre demon. Aceasta este utilizata pentru a negocia versiunea protocolului i ali parametri ai sistemului de fiiere. Reinei ca versiunea protocolului poate afecta aspectul oricarei structuri din protocol (inclusiv aceasta structura). Prin urmare, demonul trebuie sa memoreze versiunea i fanioanele negociate pentru fiecare sesiune. La momentul redactarii acestei pagini de manual, cea mai mare versiune de protocol a nucleului acceptata este 7.26. Utilizatorii trebuie sa fie contieni de faptul ca descrierile din aceasta pagina de manual pot fi incomplete sau incorecte pentru versiunile de protocol mai vechi sau mai recente. Raspunsul pentru aceasta cerere are urmatorul format: struct fuse_init_out { uint32_t major; uint32_t minor; uint32_t max_readahead; /* Incepand cu v7.6 */ uint32_t flags; /* Incepand cu v7.6; unii bii de fanioane au fost introdui tarziu */ uint16_t max_background; /* Incepand cu v7.13 */ uint16_t congestion_threshold; /* Incepand cu v7.13 */ uint32_t max_write; /* Incepand cu v7.5 */ uint32_t time_gran; /* Incepand cu v7.6 */ uint32_t unused[9]; }; In cazul in care versiunea majora admisa de nucleu este mai mare decat cea admisa de demon, raspunsul va consta doar din uint32_t major (dupa antetul obinuit), indicand cea mai mare versiune majora admisa de demon. Nucleul va emite apoi o noua cerere FUSE_INIT conforma cu versiunea mai veche. In cazul invers, demonul ar trebui sa revina in linite la versiunea majora a nucleului. Versiunea minora negociata este considerata a fi cea mai mica dintre versiunile minore furnizate de demon i de nucleu i ambele pari trebuie sa utilizeze protocolul corespunzator versiunii minore respective. FUSE_GETATTR struct fuse_getattr_in { uint32_t getattr_flags; uint32_t dummy; uint64_t fh; /* Definit doar daca (getattr_flags & FUSE_GETATTR_FH) }; Operaia solicitata consta in calcularea atributelor care urmeaza sa fie returnate de stat(2) i alte operaii similare pentru obiectul sistemului de fiiere dat. Obiectul pentru care ar trebui calculate atributele este indicat fie prin header->nodeid, fie, in cazul in care fanionul FUSE_GETATTR_FH este activat, prin gestionarul de fiier fh. Acest din urma caz de operare este analog cu fstat(2). Din motive de performana, aceste atribute pot fi stocate in memoria cache a nucleului pentru o anumita perioada de timp. Atat timp cat timpul de ateptare in cache nu a fost depait, atributele vor fi servite din cache i nu vor cauza cereri suplimentare FUSE_GETATTR. Atributele calculate i timpul de ateptare in cache solicitat ar trebui apoi returnate in urmatoarea structura: struct fuse_attr_out { /* Durata cache-ului de atribute (secunde + nanosecunde) */ 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; }; Daca opiunile de montare default_permissions nu sunt utilizate, aceasta cerere poate fi utilizata pentru verificarea permisiunilor. Nu se ateapta date de raspuns, dar erorile pot fi indicate ca de obicei prin definirea campului error din antetul raspunsului (in special, erorile de acces refuzat pot fi indicate prin returnarea -EACCES). FUSE_OPEN FUSE_OPENDIR struct fuse_open_in { uint32_t flags; /* Fanioanele care au fost transmise catre open(2) */ uint32_t unused; }; Operaia solicitata este de a deschide nodul indicat de header->nodeid. Semantica exacta a ceea ce inseamna acest lucru va depinde de sistemul de fiiere implementat Cu toate acestea, cel puin sistemul de fiiere ar trebui sa valideze ca fanioanele solicitate sunt valabile pentru resursa indicata i apoi sa trimita un raspuns cu urmatorul format: struct fuse_open_out { uint64_t fh; uint32_t open_flags; uint32_t padding; }; Campul fh este un identificator opac pe care nucleul il va utiliza pentru a se referi la aceasta resursa. Campul open_flags este o masca de bii a oricarui numar de fanioane care indica proprietaile acestui gestionar de fiier pentru nucleu: FOPEN_DIRECT_IO Ocolete cache-ul paginii pentru acest fiier deschis. FOPEN_KEEP_CACHE Nu se invalideaza memoria cache de date la deschidere. FOPEN_NONSEEKABLE Fiierul nu poate fi explorat. 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; }; Aciunea solicitata este de a citi pana la size octei din fiier sau director, incepand de la offset. Octeii ar trebui sa fie returnai direct dupa antetul de raspuns obinuit. FUSE_INTERRUPT struct fuse_interrupt_in { uint64_t unique; }; Aciunea solicitata este de a anula operaia in ateptare indicata de unique. Aceasta cerere nu necesita raspuns. Cu toate acestea, primirea acestui mesaj nu anuleaza de la sine operaia indicata. Nucleul va atepta in continuare un raspuns la operaia respectiva (de exemplu, o eroare EINTR sau o citire scurta). Pentru o operaie data va fi emisa cel mult o cerere FUSE_INTERRUPT. Dupa emiterea operaiei respective, nucleul va atepta neintrerupt finalizarea cererii indicate. FUSE_LOOKUP Imediat dupa antet urmeaza un nume de fiier care trebuie cautat in directorul indicat de header->nodeid. Raspunsul ateptat este de forma: struct fuse_entry_out { uint64_t nodeid; /* ID-ul nodului-i */ uint64_t generation; /* Generarea nodului-i */ uint64_t entry_valid; uint64_t attr_valid; uint32_t entry_valid_nsec; uint32_t attr_valid_nsec; struct fuse_attr attr; }; Combinaia de nodeid i generation trebuie sa fie unica pe durata de viaa a sistemului de fiiere. Interpretarea timpilor de ateptare i a attr este aceeai ca pentru FUSE_GETATTR. FUSE_FLUSH struct fuse_flush_in { uint64_t fh; uint32_t unused; uint32_t padding; uint64_t lock_owner; }; Aciunea solicitata este de a terge orice modificari in ateptare pentru gestionarul fiierului indicat. Nu sunt ateptate date de raspuns. Cu toate acestea, un mesaj de raspuns gol trebuie sa fie emis dupa finalizarea operaiei de golire. FUSE_RELEASE FUSE_RELEASEDIR struct fuse_release_in { uint64_t fh; uint32_t flags; uint32_t release_flags; uint64_t lock_owner; }; Acestea sunt inversul lui FUSE_OPEN i respectiv FUSE_OPENDIR. Daemonul poate elibera acum orice resurse asociate cu gestionarul fiierului fh, deoarece nucleul nu se va mai referi la acesta. Nu exista date de raspuns asociate cu aceasta cerere, dar un raspuns trebuie sa fie emis dupa ce cererea a fost complet procesata. FUSE_STATFS Aceasta operaie implementeaza statfs(2) pentru acest sistem de fiiere. Nu exista date de intrare asociate cu aceasta cerere. Datele de raspuns ateptate au urmatoarea structura: 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; }; Pentru interpretarea acestor campuri, a se vedea statfs(2). ERORI-IEIRE E2BIG Returnata din operaiile read(2) atunci cand solicitarea nucleului este prea mare pentru memoria tampon furnizata i solicitarea a fost FUSE_SETXATTR. EINVAL Returnata de la write(2) daca validarea raspunsului a euat. Nu toate erorile din raspunsuri vor fi detectate de aceasta validare. Cu toate acestea, greelile de baza, cum ar fi raspunsurile scurte sau o valoare unique incorecta, sunt detectate. EIO Returnata de operaiile read(2) atunci cand solicitarea nucleului este prea mare pentru memoria tampon furnizata. Nota: Exista diverse moduri in care utilizarea incorecta a acestor interfee poate cauza eecul operaiilor asupra fiierelor i directoarelor din sistemul de fiiere furnizat cu EIO. Printre posibilele utilizari incorecte se numara: o schimbarea mode & S_IFMT pentru un nod-i care a fost raportat anterior catre nucleu; sau o furnizarea de raspunsuri catre nucleu care sunt mai scurte decat cele ateptate de acesta. ENODEV Returnata de read(2) i write(2) daca sistemul de fiiere FUSE a fost demontat. EPERM Returnata in urma operaiilor pe un descriptor de fiier /dev/fuse care nu a fost montat. STANDARDE Linux. NOTE Urmatoarele mesaje nu sunt inca documentate in aceasta pagina de manual: 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 CONSULTAI I fusermount(1), mount.fuse(8) TRADUCERE Traducerea in limba romana a acestui manual a fost facuta de Remus- Gabriel Chelu Aceasta traducere este documentaie gratuita; citii Licena publica generala GNU Versiunea 3 sau o versiune ulterioara cu privire la condiii privind drepturile de autor. NU se asuma NICIO RESPONSABILITATE. Daca gasii erori in traducerea acestui manual, va rugam sa trimitei un e-mail la . Pagini de manual de Linux 6.12 17 noiembrie 2024 fuse(4)