ceph-dencoder: man page

Signed-off-by: Sage Weil <sage@newdream.net>

3 files changed, 292 insertions, 1 deletions

diff --git a/doc/man/8/ceph-dencoder.rst b/doc/man/8/ceph-dencoder.rst
new file mode 100644
index 00000000000..00677a92541
--- /dev/null
+++ b/doc/man/8/ceph-dencoder.rst
@@ -0,0 +1,127 @@
+==============================================
+ ceph-dencoder -- ceph encoder/decoder utility
+==============================================
+
+.. program:: ceph-dencoder
+
+Synopsis
+========
+
+| **ceph-dencoder** [commands...]
+
+
+Description
+===========
+
+**ceph-dencoder** is a utility to encode, decode, and dump ceph data
+structures.  It is used for debugging and for testing inter-version
+compatibility.
+
+**ceph-dencoder** takes a simple list of commands and performs them
+in order.
+
+Commands
+========
+
+.. option:: version
+
+   Print the version string for the **ceph-dencoder** binary.
+
+.. option:: import <file>
+
+   Read a binary blob of encoded data from the given file.  It will be
+   placed in an in-memory buffer.
+
+.. option:: export <file>
+
+   Write the contents of the current in-memory buffer to the given
+   file.
+
+.. option:: list_types
+
+   List the data types known to this build of **ceph-dencoder**.
+
+.. option:: type <name>
+
+   Select the given type for future ``encode`` or ``decode`` operations.
+
+.. option:: decode
+
+   Decode the contents of the in-memory buffer into an instance of the
+   previously selected type.  If there is an error, report it.
+
+.. option:: encode
+
+   Encode the contents of the in-memory instance of the previously
+   selected type to the in-memory buffer.
+
+.. option:: dump_json
+
+   Print a JSON-formatted description of the in-memory object.
+
+.. option:: count_tests
+
+   Print the number of built-in test instances of the previosly
+   selected type that **ceph-dencoder** is able to generate.
+
+.. option:: select_test <n>
+
+   Select the given build-in test instance as a the in-memory instance
+   of the type.
+
+.. option:: get_features
+
+   Print the decimal value of the feature set supported by this version
+   of **ceph-dencoder**.  Each bit represents a feature.  These correspond to
+   CEPH_FEATURE_* defines in src/include/ceph_features.h.
+
+.. option:: set_features <f>
+
+   Set the feature bits provided to ``encode`` to *f*.  This allows
+   you to encode objects such that they can be understood by old
+   versions of the software (for those types that support it).
+
+Example
+=======
+
+Say you want to examine an attribute on an object stored by ``ceph-osd``.  You can do::
+
+    $ cd /mnt/osd.12/current/2.b_head
+    $ attr -l foo_bar_head_EFE6384B
+    Attribute "ceph.snapset" has a 31 byte value for foo_bar_head_EFE6384B
+    Attribute "ceph._" has a 195 byte value for foo_bar_head_EFE6384B
+    $ attr foo_bar_head_EFE6384B -g ceph._ -q > /tmp/a
+    $ ceph-dencoder type object_info_t import /tmp/a decode dump_json
+    { "oid": { "oid": "foo",
+          "key": "bar",
+          "snapid": -2,
+          "hash": 4024842315,
+          "max": 0},
+      "locator": { "pool": 2,
+          "preferred": -1,
+          "key": "bar"},
+      "category": "",
+      "version": "9'1",
+      "prior_version": "0'0",
+      "last_reqid": "client.4116.0:1",
+      "size": 1681,
+      "mtime": "2012-02-21 08:58:23.666639",
+      "lost": 0,
+      "wrlock_by": "unknown.0.0:0",
+      "snaps": [],
+      "truncate_seq": 0,
+      "truncate_size": 0,
+      "watchers": {}}
+
+Availability
+============
+
+**ceph-dencoder** is part of the Ceph distributed file system. Please
+refer to the Ceph wiki at http://ceph.newdream.net/wiki for more
+information.
+
+
+See also
+========
+
+:doc:`ceph <ceph>`\(8)
diff --git a/man/Makefile.am b/man/Makefile.am
index 033f9fc8ccc..81606ff24b7 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -22,4 +22,5 @@ dist_man_MANS = \
 	rbd.8 \
 	ceph-clsinfo.8 \
 	ceph-debugpack.8 \
-	cephfs.8
+	cephfs.8 \
+	ceph-dencoder.8
diff --git a/man/ceph-dencoder.8 b/man/ceph-dencoder.8
new file mode 100644
index 00000000000..3752bc6752d
--- /dev/null
+++ b/man/ceph-dencoder.8
@@ -0,0 +1,163 @@
+.TH "CEPH-DENCODER" "8" "February 21, 2012" "dev" "Ceph"
+.SH NAME
+ceph-dencoder \- ceph encoder/decoder utility
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.\" Man page generated from reStructeredText.
+.
+.SH SYNOPSIS
+.nf
+\fBceph\-dencoder\fP [commands...]
+.fi
+.sp
+.SH DESCRIPTION
+.sp
+\fBceph\-dencoder\fP is a utility to encode, decode, and dump ceph data
+structures.  It is used for debugging and for testing inter\-version
+compatibility.
+.sp
+\fBceph\-dencoder\fP takes a simple list of commands and performs them
+in order.
+.SH COMMANDS
+.INDENT 0.0
+.TP
+.B version
+Print the version string for the \fBceph\-dencoder\fP binary.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B import <file>
+Read a binary blob of encoded data from the given file.  It will be
+placed in an in\-memory buffer.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B export <file>
+Write the contents of the current in\-memory buffer to the given
+file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B list_types
+List the data types known to this build of \fBceph\-dencoder\fP.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B type <name>
+Select the given type for future \fBencode\fP or \fBdecode\fP operations.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B decode
+Decode the contents of the in\-memory buffer into an instance of the
+previously selected type.  If there is an error, report it.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B encode
+Encode the contents of the in\-memory instance of the previously
+selected type to the in\-memory buffer.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dump_json
+Print a JSON\-formatted description of the in\-memory object.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B count_tests
+Print the number of built\-in test instances of the previosly
+selected type that \fBceph\-dencoder\fP is able to generate.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B select_test <n>
+Select the given build\-in test instance as a the in\-memory instance
+of the type.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B get_features
+Print the decimal value of the feature set supported by this version
+of \fBceph\-dencoder\fP.  Each bit represents a feature.  These correspond to
+CEPH_FEATURE_* defines in src/include/ceph_features.h.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B set_features <f>
+Set the feature bits provided to \fBencode\fP to \fIf\fP.  This allows
+you to encode objects such that they can be understood by old
+versions of the software (for those types that support it).
+.UNINDENT
+.SH EXAMPLE
+.sp
+Say you want to examine an attribute on an object stored by \fBceph\-osd\fP.  You can do:
+.sp
+.nf
+.ft C
+$ cd /mnt/osd.12/current/2.b_head
+$ attr \-l foo_bar_head_EFE6384B
+Attribute "ceph.snapset" has a 31 byte value for foo_bar_head_EFE6384B
+Attribute "ceph._" has a 195 byte value for foo_bar_head_EFE6384B
+$ attr foo_bar_head_EFE6384B \-g ceph._ \-q > /tmp/a
+$ ceph\-dencoder type object_info_t import /tmp/a decode dump_json
+{ "oid": { "oid": "foo",
+      "key": "bar",
+      "snapid": \-2,
+      "hash": 4024842315,
+      "max": 0},
+  "locator": { "pool": 2,
+      "preferred": \-1,
+      "key": "bar"},
+  "category": "",
+  "version": "9\(aq1",
+  "prior_version": "0\(aq0",
+  "last_reqid": "client.4116.0:1",
+  "size": 1681,
+  "mtime": "2012\-02\-21 08:58:23.666639",
+  "lost": 0,
+  "wrlock_by": "unknown.0.0:0",
+  "snaps": [],
+  "truncate_seq": 0,
+  "truncate_size": 0,
+  "watchers": {}}
+.ft P
+.fi
+.SH AVAILABILITY
+.sp
+\fBceph\-dencoder\fP is part of the Ceph distributed file system. Please
+refer to the Ceph wiki at \fI\%http://ceph.newdream.net/wiki\fP for more
+information.
+.SH SEE ALSO
+.sp
+\fBceph\fP(8)
+.SH COPYRIGHT
+2011, New Dream Network
+.\" Generated by docutils manpage writer.
+.\" 
+.