1 files changed, 154 insertions, 0 deletions
diff --git a/src/hdb/README b/src/hdb/README
new file mode 100644
index 0000000..0db7269
--- /dev/null
+++ b/src/hdb/README
@@ -0,0 +1,154 @@
+/*************************************************************************
+ *
+ * HTCd - Copyright (C) 1998-2006 Henrik Rydberg
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+HDB/1.2 FILE FORMAT SPECIFICATION Sat Feb 24 18:38:25 MET 2001
+MT AND MP SAFE
+One single format utilizing memory maps, and which is designed to
+work safely between processes and within a multi-threading process.
+To accomplish this, there are two types of locking mechanisms -
+one inter-process lock in the file header, and one MT lock implemented
+the usual way.
+The format is robust within each thread, except for changes in the
+table structure, which generates fatal error_t errors.
+The format includes a finite (32) number of tables, which should not
+be a real problem. Besides, a possible change is to move the frame
+pointer to a position inside, so that additional header could be
+added if needed.
+FILEFORMAT in HDB/1.2
+BYTES 1.2          NAME         DESCRIPTION
+32                 IDENT        Identification header
+4                  LOCK         Inter-process lock
+4                  MINOR        Minor modification state number
+4                  MAJOR        Major modification state number
+4                  FATAL        Fatal modification state number
+4                  FILESIZE     Size of file
+4                  FILETOP      Size of used part
+4                  TABLES       Number of table name strings
+4                  INDEX        Which column is the order column.
+32                 COMPNAME     Comparison name
+32*32              TABLENAMES   Table names
+4                  FRAME        Start of record data
+*                  RECORDS      Record list
+  4                mem          amount of memory for this record
+  4                caps         the capacity of this record - 0 means deleted
+  mem-8            data         The data follows
+0                  ZEROS        The rest of the file is padded with zeros.
+The records are always staying where they land; a minor change means
+a change in-place, a major change means a change leading to an index
+update, which could be a deletion, an insertion. Those are updated at
+will, and not seen until wanted. A fatal change is a change in the
+table structure, i.e., an insertion or deletion of a table. Also a
+table name change counts as fatal. The filesize used to be (earlier
+versions) a state needing attention as well, but not anymore.
+--
+HDB/1.11 FILE FORMAT SPECIFICATION Mon Jan 29 03:51:41 MET 2001
+STATIC/DYNAMIC mapping
+The header field determines whether the mapping is dynamic or static,
+i.e., static mapping creates a shared mmap and edits the records
+directly, whereas the dynamic mapping creates a private map and
+stores the changes on save only.
+The format changed quite a lot after all...
+FILEFORMAT in HDB/1.11
+BYTES 1.11         NAME         DESCRIPTION
+32                 IDENT        Identification header
+4                  MODNUM       Modification number
+4                  LOCK         Soft lock
+4                  FILESIZE     Size of file
+4                  FILETOP      Size of used part
+4                  FIXED        Whether fixed mapping or not
+4                  TABLES       Number of table name strings
+4                  INDEX        Which column is the order column.
+32                 COMPNAME     Comparison name
+4                  RECORDS      Number of records in file.
+                   tables
+  4,*              name         table name
+  4,*              defaults     default string
+  4                caps         default sizes
+    [4],*          records      TABLES[RECORDS]
+Size info [4] always refers to the stringref-size, but the number of
+bytes actually written is as follows: for fixed maps, it is tabs[].caps,
+and for dynamic maps, it is capsize(), which is defined as (n=stringref-size)
+(4+n)&~3.
+--
+HDB/1.10 FILE FORMAT SPECIFICATION Thu Jan 25 00:42:49 MET 2001
+The HDB/1.0 format has been used widely in the software
+for our group (MST) during the last three years of so.
+The HDB/1.1 file format is binary compatible with 1.0,
+and merely consists of a formalization, along with a
+change in the internal manipulation scheme and a new
+hdb editor.
+FILE FORMAT IN 1.0 and 1.1
+BYTES 1.0/1.1      NAME         DESCRIPTION
+32/variable        HEAD         Identification header.
+                                Used to be exactly 32 bytes,
+                                but see no point in that.
+4                  TABLES       Number of table name strings
+  4                dim          bytes in string
+  *                data         string data
+4                  DEFAULTS     Number of default strings
+  4                dim          bytes in string
+  *                data         string data
+4                  ORDERBY      Which column is the order column.
+4                  dim          Number of bytes in compname.
+*                  data         string data
+4                  RECORDS      Number of records in file.
+  4                tables
+    4              dim
+    *              data
+0/variable         FOOTER       File ends. Simple Footer.
+ADDITIONAL CHANGES BETWEEN 1.0 and 1.1
+The major difference - and the rationale for 1.1 - is
+the possiblity to edit files directly, as in mmap.
+To be able to do this, there is a need to force a minimum
+size to each field. This is done by padding the data
+with trailing zeros. This is ok since only string data
+is stored in the fields, and never binary data. Just think
+of it; if it was binary data, it would not be replaced
+by something the same size anyways, so thats forbidden
+in the direct-editing mode. It makes no difference to
+the normal operation.
+The default sizes for new fields are taken from the defaults
+table, which again is completely compatible. The only
+difference is that the zeros are stored as well, and hence
+cannot be defined just by the default string, but need an editor
+that specifies the sizes.

diff --git a/src/hdb/README b/src/hdb/README new file mode 100644 index 0000000..0db7269 --- /dev/null +++ b/src/hdb/README
@@ -0,0 +1,154 @@
	1	/*************************************************************************
	2	*
	3	* HTCd - Copyright (C) 1998-2006 Henrik Rydberg
	4	*
	5	* This program is free software; you can redistribute it and/or modify
	6	* it under the terms of the GNU General Public License as published by
	7	* the Free Software Foundation; either version 2 of the License, or
	8	* (at your option) any later version.
	9	*
	10	* This program is distributed in the hope that it will be useful,
	11	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	12	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	13	* GNU General Public License for more details.
	14	*
	15	* You should have received a copy of the GNU General Public License
	16	* along with this program; if not, write to the Free Software
	17	* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
	18	*/
	19
	20	HDB/1.2 FILE FORMAT SPECIFICATION Sat Feb 24 18:38:25 MET 2001
	21
	22	MT AND MP SAFE
	23
	24	One single format utilizing memory maps, and which is designed to
	25	work safely between processes and within a multi-threading process.
	26	To accomplish this, there are two types of locking mechanisms -
	27	one inter-process lock in the file header, and one MT lock implemented
	28	the usual way.
	29
	30	The format is robust within each thread, except for changes in the
	31	table structure, which generates fatal error_t errors.
	32
	33	The format includes a finite (32) number of tables, which should not
	34	be a real problem. Besides, a possible change is to move the frame
	35	pointer to a position inside, so that additional header could be
	36	added if needed.
	37
	38	FILEFORMAT in HDB/1.2
	39
	40	BYTES 1.2 NAME DESCRIPTION
	41	32 IDENT Identification header
	42	4 LOCK Inter-process lock
	43	4 MINOR Minor modification state number
	44	4 MAJOR Major modification state number
	45	4 FATAL Fatal modification state number
	46	4 FILESIZE Size of file
	47	4 FILETOP Size of used part
	48	4 TABLES Number of table name strings
	49	4 INDEX Which column is the order column.
	50	32 COMPNAME Comparison name
	51	32*32 TABLENAMES Table names
	52	4 FRAME Start of record data
	53	* RECORDS Record list
	54	4 mem amount of memory for this record
	55	4 caps the capacity of this record - 0 means deleted
	56	mem-8 data The data follows
	57	0 ZEROS The rest of the file is padded with zeros.
	58
	59	The records are always staying where they land; a minor change means
	60	a change in-place, a major change means a change leading to an index
	61	update, which could be a deletion, an insertion. Those are updated at
	62	will, and not seen until wanted. A fatal change is a change in the
	63	table structure, i.e., an insertion or deletion of a table. Also a
	64	table name change counts as fatal. The filesize used to be (earlier
	65	versions) a state needing attention as well, but not anymore.
	66
	67	--
	68
	69	HDB/1.11 FILE FORMAT SPECIFICATION Mon Jan 29 03:51:41 MET 2001
	70
	71	STATIC/DYNAMIC mapping
	72
	73	The header field determines whether the mapping is dynamic or static,
	74	i.e., static mapping creates a shared mmap and edits the records
	75	directly, whereas the dynamic mapping creates a private map and
	76	stores the changes on save only.
	77
	78	The format changed quite a lot after all...
	79
	80	FILEFORMAT in HDB/1.11
	81
	82	BYTES 1.11 NAME DESCRIPTION
	83	32 IDENT Identification header
	84	4 MODNUM Modification number
	85	4 LOCK Soft lock
	86	4 FILESIZE Size of file
	87	4 FILETOP Size of used part
	88	4 FIXED Whether fixed mapping or not
	89	4 TABLES Number of table name strings
	90	4 INDEX Which column is the order column.
	91	32 COMPNAME Comparison name
	92	4 RECORDS Number of records in file.
	93	tables
	94	4,* name table name
	95	4,* defaults default string
	96	4 caps default sizes
	97	[4],* records TABLES[RECORDS]
	98
	99	Size info [4] always refers to the stringref-size, but the number of
	100	bytes actually written is as follows: for fixed maps, it is tabs[].caps,
	101	and for dynamic maps, it is capsize(), which is defined as (n=stringref-size)
	102	(4+n)&~3.
	103
	104	--
	105
	106	HDB/1.10 FILE FORMAT SPECIFICATION Thu Jan 25 00:42:49 MET 2001
	107
	108	The HDB/1.0 format has been used widely in the software
	109	for our group (MST) during the last three years of so.
	110	The HDB/1.1 file format is binary compatible with 1.0,
	111	and merely consists of a formalization, along with a
	112	change in the internal manipulation scheme and a new
	113	hdb editor.
	114
	115	FILE FORMAT IN 1.0 and 1.1
	116
	117	BYTES 1.0/1.1 NAME DESCRIPTION
	118	32/variable HEAD Identification header.
	119	Used to be exactly 32 bytes,
	120	but see no point in that.
	121	4 TABLES Number of table name strings
	122	4 dim bytes in string
	123	* data string data
	124	4 DEFAULTS Number of default strings
	125	4 dim bytes in string
	126	* data string data
	127	4 ORDERBY Which column is the order column.
	128	4 dim Number of bytes in compname.
	129	* data string data
	130	4 RECORDS Number of records in file.
	131	4 tables
	132	4 dim
	133	* data
	134	0/variable FOOTER File ends. Simple Footer.
	135
	136	ADDITIONAL CHANGES BETWEEN 1.0 and 1.1
	137
	138	The major difference - and the rationale for 1.1 - is
	139	the possiblity to edit files directly, as in mmap.
	140	To be able to do this, there is a need to force a minimum
	141	size to each field. This is done by padding the data
	142	with trailing zeros. This is ok since only string data
	143	is stored in the fields, and never binary data. Just think
	144	of it; if it was binary data, it would not be replaced
	145	by something the same size anyways, so thats forbidden
	146	in the direct-editing mode. It makes no difference to
	147	the normal operation.
	148
	149	The default sizes for new fields are taken from the defaults
	150	table, which again is completely compatible. The only
	151	difference is that the zeros are stored as well, and hence
	152	cannot be defined just by the default string, but need an editor
	153	that specifies the sizes.
	154