From ed230379e7af9312206b591c900ef09cb2fd1302 Mon Sep 17 00:00:00 2001
From: Jakob Unterwurzacher
Date: Sun, 8 Sep 2019 15:50:05 +0200
Subject: Expand statfs man page a little and include in build.bash

---
 Documentation/MANPAGE-STATFS.md | 64 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 58 insertions(+), 6 deletions(-)

(limited to 'Documentation')

diff --git a/Documentation/MANPAGE-STATFS.md b/Documentation/MANPAGE-STATFS.md
index 1d77802..c519f4b 100644
--- a/Documentation/MANPAGE-STATFS.md
+++ b/Documentation/MANPAGE-STATFS.md
@@ -5,26 +5,78 @@
 NAME
 ====
 
-statfs - dump the statfs information for PATH to console in JSON format
+statfs - dump the statfs(2) information for PATH to console in JSON format.
 
 SYNOPSIS
 ========
 
-#### Examine encrypted file/directory
 statfs PATH
 
 DESCRIPTION
 ===========
 
-There are no options to this command.
+The statfs(2) system call returns information about a mounted filesystem
+in a `statfs_t` structure. This tool dumps this information in JSON format.
+It is developed as part of gocryptfs and written in Go.
+
+The `statfs_t` structure is architecture-dependent. On amd64 it looks like this:
+
+```
+type Statfs_t struct {
+	Type   int64
+	Bsize  int64
+	Blocks uint64
+	Bfree  uint64
+	Bavail uint64
+	Files  uint64
+	Ffree  uint64
+	Fsid   struct {
+		Val [2]int32
+	}
+	Namelen int64
+	Frsize  int64
+	Flags   int64
+	Spare   [4]int64
+}
+```
+
+See the statfs(2) man page for the meaning of these fields, and note
+that the field names here are acc. to the Go `golang.org/x/sys/unix`
+naming convention, and slightly different than in C.
 
 EXAMPLES
 ========
 
-Examine a directory entry:
+Get the statfs(2) information for /tmp:
 
-	statfs myfs/mCXnISiv7nEmyc0glGuhTQ
+```
+$ statfs /tmp
+{
+	"Type": 16914836,
+	"Bsize": 4096,
+	"Blocks": 3067428,
+	"Bfree": 3067411,
+	"Bavail": 3067411,
+	"Files": 3067428,
+	"Ffree": 3067381,
+	"Fsid": {
+		"Val": [
+			0,
+			0
+		]
+	},
+	"Namelen": 255,
+	"Frsize": 4096,
+	"Flags": 38,
+	"Spare": [
+		0,
+		0,
+		0,
+		0
+	]
+}
+```
 
 SEE ALSO
 ========
-gocryptfs(1) gocryptfs-xray(1)
+statfs(2) gocryptfs(1)
-- 
cgit v1.2.3