Merge remote-tracking branch 'origin/master' into t

* origin/master:
  zipfs: godoc comments for tarfs
  fs: more godoc
  pathfs: mark nodefs, pathfs as deprecated
  example: add doc comments to main programs
  Reinstate "gerrithub usage instructions."
  fuse/nodefs: return OK for OOB readdir(plus)

CONTRIBUTING

@@ -2,3 +2,21 @@
 Before sending a patch or Pull request, please fill out a Google CLA, using the following form:
 
   https://cla.developers.google.com/clas
+
+For complex changes, please use Gerrit:
+
+* Connect your github account with gerrithub, at
+
+  https://review.gerrithub.io/static/intro.html
+
+* The signup will setup your SSH keys from Github.
+
+* Create your change as a commit
+
+* Add an ID to the commit message:
+
+  echo "Change-Id: I"$(head -c 20 /dev/urandom | sha1sum | awk '{print $1}')
+
+* Push the change for review,
+
+  git push ssh://$USER@review.gerrithub.io:29418/hanwen/go-fuse HEAD:refs/for/master

example/hello/main.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// A Go mirror of libfuse's hello.c
-
+// This program is the analogon of libfuse's hello.c, a a program that
+// exposes a single file "file.txt" in the root directory.
 package main
 
 import (

example/loopback/main.go

@@ -2,9 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Mounts another directory as loopback for testing and benchmarking
-// purposes.
-
+// This is main program driver for the loopback filesystem from
+// github.com/hanwen/go-fuse/fs/, a filesystem that shunts operations
+// to an underlying file system.
 package main
 
 import (

example/multizip/main.go

@@ -2,6 +2,10 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// This is main program driver for MultiZipFs from
+// github.com/hanwen/go-fuse/zipfs, a filesystem for mounting multiple
+// read-only archives. It can be used by symlinking to an archive file
+// from the config/ subdirectory.
 package main
 
 import (

example/statfs/main.go

@@ -2,6 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// statfs is a main driver for the file system from
+// github.com/hanwen/go-fuse/benchmark, intended for benchmarking FUSE
+// libraries.
 package main
 
 import (

example/zipfs/main.go

@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// This is main program driver for github.com/hanwen/go-fuse/zipfs, a
+// filesystem for mounting read-only archives.
 package main
 
 import (

fs/api.go

@@ -33,7 +33,6 @@
 // initialized by calling NewInode or NewPersistentInode before being
 // manipulated further, eg.
 //
-//
 //  type myNode struct {
 //     Inode
 //  }
@@ -83,6 +82,9 @@ import (
 
 // InodeEmbedder is an interface for structs that embed Inode.
 //
+// InodeEmbedder objects usually should implement some of the NodeXxxx
+// interfaces, to provide user-defined file system behaviors.
+//
 // In general, if an InodeEmbedder does not implement specific
 // filesystem methods, the filesystem will react as if it is a
 // read-only filesystem with a predefined tree structure. See
@@ -358,10 +360,17 @@ type NodeRenamer interface {
 	Rename(ctx context.Context, name string, newParent InodeEmbedder, newName string, flags uint32) syscall.Errno
 }
 
-// FileHandle is a resource identifier for opened files.  FileHandles
-// are useful in two cases: First, if the underlying storage systems
-// needs a handle for reading/writing. See the function
-// `NewLoopbackFile` for an example. Second, it is useful for
+// FileHandle is a resource identifier for opened files. Usually, a
+// FileHandle should implement some of the FileXxxx interfaces.
+//
+// All of the FileXxxx operations can also be implemented at the
+// InodeEmbedder level, for example, one can implement NodeReader
+// instead of FileReader.
+//
+// FileHandles are useful in two cases: First, if the underlying
+// storage systems needs a handle for reading/writing. This is the
+// case with Unix system calls, which need a file descriptor (See also
+// the function `NewLoopbackFile`). Second, it is useful for
 // implementing files whose contents are not tied to an inode. For
 // example, a file like `/proc/interrupts` has no fixed content, but
 // changes on each open call. This means that each file handle must

fs/inmemory_example_test.go

@@ -55,19 +55,24 @@ func (root *inMemoryFS) OnAdd(ctx context.Context) {
 			p = ch
 		}
 
+		// Make a file out of the content bytes. This type
+		// provides the open/read/flush methods.
+		embedder := &fs.MemRegularFile{
+			Data: []byte(content),
+		}
+
 		// Create the file. The Inode must be persistent,
 		// because its life time is not under control of the
 		// kernel.
-		child := p.NewPersistentInode(ctx, &fs.MemRegularFile{
-			Data: []byte(content),
-		}, fs.StableAttr{})
+		child := p.NewPersistentInode(ctx, embedder, fs.StableAttr{})
 
 		// And add it
 		p.AddChild(base, child, true)
 	}
 }
 
-// This demonstrates how to build a file system in memory.
+// This demonstrates how to build a file system in memory. The
+// read/write logic for the file is provided by the MemRegularFile type.
 func Example() {
 	// This is where we'll mount the FS
 	mntDir, _ := ioutil.TempDir("", "")

fs/loopback.go

@@ -372,7 +372,8 @@ func (n *loopbackNode) Setattr(ctx context.Context, f FileHandle, in *fuse.SetAt
 }
 
 // NewLoopback returns a root node for a loopback file system whose
-// root is at the given root.
+// root is at the given root. This node implements all NodeXxxxer
+// operations available.
 func NewLoopbackRoot(root string) (InodeEmbedder, error) {
 	var st syscall.Stat_t
 	err := syscall.Stat(root, &st)

fs/mem.go

@@ -13,7 +13,6 @@ import (
 
 // MemRegularFile is a filesystem node that holds a read-only data
 // slice in memory.
-
 type MemRegularFile struct {
 	Inode
 	Data []byte

fuse/nodefs/api.go

@@ -2,6 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// This package is deprecated. New projects should use the package
+// "github.com/hanwen/go-fuse/fs" instead.
+//
 // The nodefs package offers a high level API that resembles the
 // kernel's idea of what an FS looks like.  File systems can have
 // multiple hard-links to one file, for example. It is also suited if

fuse/nodefs/dir.go

@@ -40,8 +40,12 @@ func (d *connectorDir) ReadDir(cancel <-chan struct{}, input *fuse.ReadIn, out *
 	}
 
 	if input.Offset > uint64(len(d.stream)) {	// XXX ">" -> ">="
-		// This shouldn't happen, but let's not crash.
-		return fuse.EINVAL
+		// See https://github.com/hanwen/go-fuse/issues/297
+		// This can happen for FUSE exported over NFS.  This
+		// seems incorrect, (maybe the kernel is using offsets
+		// from other opendir/readdir calls), it is harmless to reinforce that
+		// we have reached EOF.
+		return fuse.OK
 	}
 
 	todo := d.stream[input.Offset:]
@@ -75,8 +79,8 @@ func (d *connectorDir) ReadDirPlus(cancel <-chan struct{}, input *fuse.ReadIn, o
 	}
 
 	if input.Offset > uint64(len(d.stream)) {	// XXX >=
-		// This shouldn't happen, but let's not crash.
-		return fuse.EINVAL
+		// See comment in Readdir
+		return fuse.OK
 	}
 	todo := d.stream[input.Offset:]
 	for _, e := range todo {

fuse/pathfs/api.go

@@ -2,6 +2,10 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// This package is deprecated. New projects should use the package
+// "github.com/hanwen/go-fuse/fs" instead.
+//
+// Package pathfs provides a file system API expressed in filenames.
 package pathfs
 
 import (

zipfs/tarfs.go

@@ -23,6 +23,7 @@ import (
 
 // TODO - handle symlinks.
 
+// HeaderToFileInfo fills a fuse.Attr struct from a tar.Header.
 func HeaderToFileInfo(out *fuse.Attr, h *tar.Header) {
 	out.Mode = uint32(h.Mode)
 	out.Size = uint64(h.Size)
@@ -36,6 +37,9 @@ type tarRoot struct {
 	rc io.ReadCloser
 }
 
+// tarRoot implements NodeOnAdder
+var _ = (fs.NodeOnAdder)((*tarRoot)(nil))
+
 func (r *tarRoot) OnAdd(ctx context.Context) {
 	tr := tar.NewReader(r.rc)
 	defer r.rc.Close()
@@ -134,6 +138,9 @@ func (rc *readCloser) Close() error {
 	return rc.close()
 }
 
+// NewTarCompressedTree creates the tree of a tar file as a FUSE
+// InodeEmbedder. The inode can either be mounted as the root of a
+// FUSE mount, or added as a child to some other FUSE tree.
 func NewTarCompressedTree(name string, format string) (fs.InodeEmbedder, error) {
 	f, err := os.Open(name)
 	if err != nil {