--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/record-format.txt	Wed Jan 16 22:39:43 2008 +0100
@@ -0,0 +1,74 @@
+Record Format
+-------------
+
+Syntax notes:
+- ( P )* means "zero or more of the P"
+- ( P )+ means "one or more of the P"
+- { P } means "zero or one of the P"
+  (ie P is optional and may be omitted)
+
+New version 2 records have the following format:
+	0x02
+	( flag-number flag-value )* NUL
+	password-crypt NUL
+	{ mailbox } NUL
+	( alias NUL )* NUL
+	personal-information NUL
+	hard-quota NUL
+	soft-quota NUL
+	message-size-limit NUL
+	message-count-limit NUL
+	creation-time NUL
+	expiry-time NUL
+
+flag-number and flag-value are single-byte values.  The flag numbers are
+the same as the attribute number defined in vdomain/vdomain.h.
+
+The maximum values for limits (quota, etc.) are expressed in the file as
+"-" and internally as UINT_MAX.  Records with an unknown creation time
+have the creation-time set to the UNIX epoch (midnight GMT January 1,
+1970).
+
+Old Record Formats
+------------------
+
+Version 1 records have the following format:
+	0x01
+	password-crypt NUL
+	{ mailbox } NUL
+	( alias NUL )* NUL
+	personal-information NUL
+	hard-quota NUL
+	soft-quota NUL
+	message-size-limit NUL
+	message-count-limit NUL
+	creation-time NUL
+	expiry-time NUL
+
+Old style records had the following format:
+	":" password-crypt ":" destination
+The destination was prefixed with '&' for a forward, and with either '.'
+or '/' for a mailbox.
+
+Proposed Record Format
+----------------------
+
+New version 3 records have the following format:
+	0x03
+	( flag-number flag-value )* NUL
+	password-crypt NUL
+	{ mailbox } NUL
+	( alias NUL )* NUL
+	personal-information NUL
+	hard-quota NUL
+	soft-quota NUL
+	message-size-limit NUL
+	message-count-limit NUL
+	creation-time NUL
+	expiry-time NUL
+	last-modified-time NUL
+
+flag-number and flag-value are single-byte values.  The flag numbers are
+the same as the attribute number defined in vdomain/vdomain.h.  The flag
+value is either ASCII '0' for false/off or ASCII '1' for true/on.
+