README.md
1# GO-FUSE
2
3[](https://travis-ci.org/hanwen/go-fuse)
4[](https://godoc.org/github.com/hanwen/go-fuse)
5
6Go native bindings for the FUSE kernel module.
7
8You should import and use
9[github.com/hanwen/go-fuse/fs](https://godoc.org/github.com/hanwen/go-fuse/fs)
10library. It follows the wire protocol closely, but provides
11convenient abstractions for building both node and path based file
12systems
13
14Older, deprecated APIs are available at
15[github.com/hanwen/go-fuse/fuse/pathfs](https://godoc.org/github.com/hanwen/go-fuse/fuse/pathfs)
16and
17[github.com/hanwen/go-fuse/fuse/nodefs](https://godoc.org/github.com/hanwen/go-fuse/fuse/nodefs).
18
19## Comparison with other FUSE libraries
20
21The FUSE library gained a new, cleaned-up API during a rewrite
22completed in 2019. Find extensive documentation
23[here](https://godoc.org/github.com/hanwen/go-fuse/).
24
25Further highlights of this library is
26
27* Comprehensive and up to date protocol support (up to 7.12.28).
28
29* Performance that is competitive with libfuse.
30
31
32## Examples
33
34* `example/hello/main.go` contains a 60-line "hello world" filesystem
35
36* `zipfs/zipfs.go` contains a small and simple read-only filesystem for
37 zip and tar files. The corresponding command is in example/zipfs/
38 For example,
39
40 ```shell
41 mkdir /tmp/mountpoint
42 example/zipfs/zipfs /tmp/mountpoint file.zip &
43 ls /tmp/mountpoint
44 fusermount -u /tmp/mountpoint
45 ````
46
47* `zipfs/multizipfs.go` shows how to use in-process mounts to
48 combine multiple Go-FUSE filesystems into a larger filesystem.
49
50* `fuse/loopback.go` mounts another piece of the filesystem.
51 Functionally, it is similar to a symlink. A binary to run is in
52 example/loopback/ . For example
53
54 ```shell
55 mkdir /tmp/mountpoint
56 example/loopback/loopback -debug /tmp/mountpoint /some/other/directory &
57 ls /tmp/mountpoint
58 fusermount -u /tmp/mountpoint
59 ```
60
61## macOS Support
62
63go-fuse works somewhat on OSX. Known limitations:
64
65* All of the limitations of OSXFUSE, including lack of support for
66 NOTIFY.
67
68* OSX issues STATFS calls continuously (leading to performance
69 concerns).
70
71* OSX has trouble with concurrent reads from the FUSE device, leading
72 to performance concerns.
73
74* Tests are expected to pass; report any failure as a bug!
75
76## Credits
77
78* Inspired by Taru Karttunen's package, https://bitbucket.org/taruti/go-extra.
79
80* Originally based on Ivan Krasin's https://github.com/krasin/go-fuse-zip
81
82## Bugs
83
84Yes, probably. Report them through
85https://github.com/hanwen/go-fuse/issues
86
87## Disclaimer
88
89This is not an official Google product.
90
91## Known Problems
92
93Grep source code for TODO. Major topics:
94
95* Missing support for `CUSE`, `BMAP`, `IOCTL`
96
97## License
98
99Like Go, this library is distributed under the new BSD license. See
100accompanying LICENSE file.
101
102--------
103
104## Appendix I. Go-FUSE log format
105
106To increase signal/noise ratio Go-FUSE uses abbreviations in its debug log
107output. Here is how to read it:
108
109- `iX` means `inode X`;
110- `gX` means `generation X`;
111- `tA` and `tE` means timeout for attributes and directory entry correspondingly;
112- `[<off> +<size>)` means data range from `<off>` inclusive till `<off>+<size>` exclusive;
113- `Xb` means `X bytes`.
114
115Every line is prefixed with either `rx <unique>` or `tx <unique>` to denote
116whether it was for kernel request, which Go-FUSE received, or reply, which
117Go-FUSE sent back to kernel.
118
119Example debug log output:
120
121```
122rx 2: LOOKUP i1 [".wcfs"] 6b
123tx 2: OK, {i3 g2 tE=1s tA=1s {M040755 SZ=0 L=0 1000:1000 B0*0 i0:3 A 0.000000 M 0.000000 C 0.000000}}
124rx 3: LOOKUP i3 ["zurl"] 5b
125tx 3: OK, {i4 g3 tE=1s tA=1s {M0100644 SZ=33 L=1 1000:1000 B0*0 i0:4 A 0.000000 M 0.000000 C 0.000000}}
126rx 4: OPEN i4 {O_RDONLY,0x8000}
127tx 4: 38=function not implemented, {Fh 0 }
128rx 5: READ i4 {Fh 0 [0 +4096) L 0 RDONLY,0x8000}
129tx 5: OK, 33b data "file:///"...
130rx 6: GETATTR i4 {Fh 0}
131tx 6: OK, {tA=1s {M0100644 SZ=33 L=1 1000:1000 B0*0 i0:4 A 0.000000 M 0.000000 C 0.000000}}
132rx 7: FLUSH i4 {Fh 0}
133tx 7: OK
134rx 8: LOOKUP i1 ["head"] 5b
135tx 8: OK, {i5 g4 tE=1s tA=1s {M040755 SZ=0 L=0 1000:1000 B0*0 i0:5 A 0.000000 M 0.000000 C 0.000000}}
136rx 9: LOOKUP i5 ["bigfile"] 8b
137tx 9: OK, {i6 g5 tE=1s tA=1s {M040755 SZ=0 L=0 1000:1000 B0*0 i0:6 A 0.000000 M 0.000000 C 0.000000}}
138rx 10: FLUSH i4 {Fh 0}
139tx 10: OK
140rx 11: GETATTR i1 {Fh 0}
141tx 11: OK, {tA=1s {M040755 SZ=0 L=1 1000:1000 B0*0 i0:1 A 0.000000 M 0.000000 C 0.000000}}
142```
143
){kind=link}
){kind=link}