Do not attempt to clean the same segment multiple times.

[cumulus.git] / doc / format.txt

diff --git a/doc/format.txt b/doc/format.txt
index 78f32c3..5072981 100644 (file)
--- a/doc/format.txt
+++ b/doc/format.txt
@@ -1,5 +1,6 @@
                        Backup Format Description
                   for an LFS-Inspired Backup Solution
+                      Version: "LBS Snapshot v0.6"
 
 NOTE: This format specification is not yet complete.  Right now the code
 provides the best documentation of the format.
@@ -115,12 +116,28 @@ is invalid to select using the slice syntax a range of bytes that does
 not fall within the original object.  The slice specification should be
 appended to an object name, for example:
     a704eeae-97f2-4f30-91a4-d4473956366b/000001ad[264+1000]
-selects only bytes 264..1263 from the original object.
+selects only bytes 264..1263 from the original object.  As an
+abbreviation, the slice syntax
+    [<length>]
+is shorthand for
+    [0+<length>]
 
 Both a checksum and a slice can be used.  In this case, the checksum is
 given first, followed by the slice.  The checksum is computed over the
 original object contents, before slicing.
 
+Special Objects
+---------------
+
+In addition to the standard syntax for objects described above, the
+special name "zero" may be used instead of segment/sequence number.
+This represents an object consisting entirely of zeroes.  The zero
+object must have a slice specification appended to indicate the size of
+the object.  For example
+    zero[1024]
+represents a block consisting of 1024 null bytes.  A checksum should not
+be given.  The slice syntax should use the abbreviated length-only form.
+
 
 FILE METADATA LISTING
 =====================
@@ -166,7 +183,8 @@ for each field is specified in the field listing that follows.
         and those starting with 0x are intepreted as hexadecimal.
 
 Common fields (required in all stanzas):
-    name [encoded string]: Full path of the file archived.
+    path [encoded string]: Full path of the file archived.  Note: In
+        previous versions (<= 0.2) the name of this field was "name".
     user [special]: The user ID of the file, as an integer, optionally
         followed by a space and the corresponding username, as an
         escaped string enclosed in parentheses.
@@ -176,14 +194,19 @@ Common fields (required in all stanzas):
     mode [integer]: Unix mode bits for the file.
     type [special]: A single character which indicates the type of file.
         The type indicators are meant to be consistent with the
-        characters used to indicate file type in a directory listing:
-            -   regular file
+        characters used with the -type option to find(1), and the file
+        type checks in test(1):
+            f   regular file
             b   block device
             c   character device
             d   directory
             l   symlink
             p   pipe
             s   socket
+        Note that previous versions used '-' to indicate a regular file.
+        This character should not be generated in any new snapshots, but
+        may be encountered in old snapshots (those with a format version
+        <= 0.2).
     mtime [integer]: Modification time of the file.
 
 Optional common fields:
@@ -199,6 +222,7 @@ Optional common fields:
         produced by the standard tool is <major>/<minor>/<inode> (where
         <major> and <minor> specify the device of the containing
         filesystem and <inode> is the inode number of the file).
+    ctime [integer]: Change time for the inode.
 
 Special fields used for regular files:
     checksum [string]: Checksum of the file contents.
@@ -211,6 +235,16 @@ Special fields used for regular files:
         references which should be parsed in the same manner as the data
         field.
 
+Special fields used for symbolic links:
+    target[encoded string]: The target of the symlink, as returned by
+        readlink(2).  Note: In old version of the format (<= 0.2), this
+        field was called "contents" instead of "target".
+
+Special fields used for block and character device files:
+    device[special]: The major and minor number of the device.  Encoded
+        as "major/minor", where major is the major device number encoded
+        into an integer, and minor is the minor device number.
+
 
 SNAPSHOT DESCRIPTOR
 ===================
@@ -230,8 +264,8 @@ is %Y%m%dT%H%M%S (20070806T092239 means 2007-08-06 09:22:39).
 
 The contents of the descriptor are a set of RFC 822-style headers (much
 like the metadata listing).  The fields which are defined are:
-    Format: The string "LBS Snapshot v0.2" which identifies this file as
-        an LBS backup descriptor.  The version number (v0.2) might
+    Format: The string "LBS Snapshot v0.6" which identifies this file as
+        an LBS backup descriptor.  The version number (v0.6) might
         change if there are changes to the format.  It is expected that
         at some point, once the format is stabilized, the version
         identifier will be changed to v1.0.