Lots more ReadDir brain dumping.

file_system.go

@@ -104,6 +104,14 @@ type GenerationNumber uint64
 // This corresponds to fuse_file_info::fh.
 type HandleID uint64
 
+// XXX: Comments for all
+type Dirent struct {
+	Inode  InodeID
+	Offset DirOffset
+	Name   string
+	Type   DirentType
+}
+
 ////////////////////////////////////////////////////////////////////////
 // Requests and responses
 ////////////////////////////////////////////////////////////////////////
@@ -254,7 +262,42 @@ type ReadDirRequest struct {
 	//     last, which may be truncated by the page boundary), parse_dirfile
 	//     updates dir_context::pos with fuse_dirent::off.
 	//
-	OpaqueOffset uint64
+	// It is affected by the Posix directory stream interfaces in the following
+	// manner:
+	//
+	//  *  (http://goo.gl/fQhbyn, http://goo.gl/ns1kDF) opendir initially causes
+	//     filepos to be set to zero.
+	//
+	//  *  (http://goo.gl/ezNKyR, http://goo.gl/xOmDv0) readdir allows the user
+	//     to iterate through the directory one entry at a time. As each entry is
+	//     consumed, its d_off field is stored in __dirstream::filepos.
+	//
+	//  *  (http://goo.gl/WEOXG8, http://goo.gl/rjSXl3) telldir allows the user
+	//     to obtain the d_off field from the most recently returned entry.
+	//
+	//  *  (http://goo.gl/WG3nDZ, http://goo.gl/Lp0U6W) seekdir allows the user
+	//     to seek backward to an offset previously returned by telldir. It
+	//     stores the new offset in filepos, and calls llseek to update the
+	//     kernel's struct file.
+	//
+	//  *  (http://goo.gl/gONQhz, http://goo.gl/VlrQkc) rewinddir allows the user
+	//     to go back to the beginning of the directory, obtaining a fresh view.
+	//     It updates filepos and calls llseek to update the kernel's struct
+	//     file.
+	//
+	// Unfortunately, FUSE offers no way to intercept seeks
+	// (http://goo.gl/H6gEXa), so there is no way to cause seekdir or rewinddir
+	// to fail. Additionally, there is no way to distinguish an explicit
+	// rewinddir followed by readdir from the initial readdir, or a rewinddir
+	// from a seekdir to the value returned by telldir just after opendir.
+	//
+	// Luckily, Posix is vague about what the user will see if they seek
+	// backwards, and requires the user not to seek to an old offset after a
+	// rewind. The only requirement on freshness is that rewinddir results in
+	// something that looks like a newly-opened directory. So FUSE file systems
+	// may e.g. cache an entire fresh listing for each ReadDir with a zero
+	// offset, and return array offsets into that cached listing.
+	Offset DirOffset
 
 	// The maximum number of bytes to return in ReadDirResponse.Data.
 	Size uint64
@@ -263,26 +306,17 @@ type ReadDirRequest struct {
 type ReadDirResponse struct {
 	// A buffer consisting of a sequence of FUSE directory entries in the format
 	// generated by fuse_add_direntry (http://goo.gl/qCcHCV), which is consumed
-	// by parse_dirfile (http://goo.gl/2WUmD2). Use TODO to generate this data.
+	// by parse_dirfile (http://goo.gl/2WUmD2). Use fuseutil.AppendDirent to
+	// generate this data.
 	//
 	// The buffer must not exceed the length specified in ReadDirRequest.Size. It
 	// is okay for the final entry to be truncated; parse_dirfile copes with this
 	// by ignoring the partial record.
-
-	// XXX: Fields
-	//
-	// In Linux this corresponds to dirent::d_off, and in OS X it corresponds to
-	// dirent::d_seekoff. In the glibc implementation of the Posix interface
-	// discussed below, it corresponds to __dirstream::filepos
-	// (http://goo.gl/x15ISb).
-	//
-	// Warning: this field is not necessarily a count of bytes. It makes the most
-	// sense when looking at the Posix interface for reading directories:
-	//
-	//  *  (http://goo.gl/fQhbyn, http://goo.gl/ns1kDF) opendir initially causes
-	//     filepos to be set to zero.
 	//
-	// This field makes most
+	// Each entry returned exposes a directory offset to the user that may later
+	// show up in ReadDirRequest.Offset. See notes on that field for more
+	// information.
+	Data []byte
 }
 
 type ReleaseHandleRequest struct {