Add a README.cnid which talks about what CNID is, and what it means to

Netatalk.  It also includes Adrian's old developer notes for a rough
understanding of the whole process.

diff --git a/doc/FAQ b/doc/FAQ
index e962801c8e7940c3cc5e5cac6e7f4b0a7c1e15c8..f06a80e932daab8bf3ad8e350d11e93e1237552e 100644 (file)
--- a/doc/FAQ
+++ b/doc/FAQ
@@ -1,5 +1,5 @@
 Netatalk Frequently Asked Questions
-($Id: FAQ,v 1.10 2003-01-04 21:41:48 jmarcus Exp $)
+($Id: FAQ,v 1.11 2003-01-04 22:14:03 jmarcus Exp $)
 
 -----------------------------------------------------------------------------
 
@@ -213,9 +213,7 @@ A:  Compile with the --with-did=last flag set. This activates a different
       --with-bdb=PATH         specify path to Berkeley DB installation
       --with-did=[scheme]     set DID scheme (cnid,last) 
     
-    (For more information on CNID, see the README.cnid file [may not exist yet], 
-    into which I just copied wholesale Joe's comments on what he did with 
-    cnid and lastdid.)
+    (For more information on CNID, see the README.cnid file.)
     
     --with-did=last reverted things back to the old 1.4b2 directory ID
     calculation algorithm.  This also solved the problem of the syslog

diff --git a/doc/README.cnid b/doc/README.cnid
new file mode 100644 (file)
index 0000000..e0dc5c0
--- /dev/null
+++ b/doc/README.cnid
@@ -0,0 +1,69 @@
+CNID stands for Catalog Node IDs which are unique identifiers AFP assigns 
+to each file and directory.  CNID in Netatalk speak refers to a persistent
+DID calculation scheme backed by Berkeley DB.  CNIDs are 32-bits wide, and
+must be unique for the life of a volume.  CNID numbering starts at 17.  IDs
+before 17 are reserved.  When all the IDs have been consumed on a given
+volume, that volume is full, and no more files or directories can be added.
+
+The CNID scheme in Netatalk attempts to assign unique IDs to each file and
+directory, then keep those IDs persistent across mounts of the volume.  This
+way, cross-volume aliases will work, and users are less likely to encounter
+duplicate CNID errors.  Prior to Netatalk 1.6.0, the CNID calculation
+scheme was not persistent, and IDs were assigned based on the UNIX device and
+inode number of a given file or directory.  This was fine for the most part,
+but due to limitations, not all available CNIDs could be used.  As well, 
+these IDs could change independently from Netatalk, and thus were not
+persistent.  As of Netatalk 1.6.0, the CNID scheme is now the default.
+On top of that, Netatalk uses the Concurrent Datastore method to avoid
+the need for database locking and transactions.
+
+As stated above, CNID requires Berkeley DB.  Currently, Netatalk supports 
+BDB 3.0.17, 3.2.9, 3.3.11, 4.0.14, and 4.1.25.  The recommended version is 
+3.3.11 as that is the version on which most testing has been done.  
+
+CNID has seen many contributors over the years.  It was first conceived by
+Adrian Sun <asun@zoology.washington.edu>.  His developer notes can be found
+below.  It was later picked up and modernized by Uwe Hees
+<uwe.hees@rz-online.de>.  Then, Joe Marcus Clarke <marcus@marcuscom.com>
+started fixing bugs and adding additional features.  The Concurrent
+Datastore support was added by Dan Wilga <dwilga@mtholyoke.edu>.  
+The CNID code is currently maintained by Joe Marcus Clarke.
+
+Here are Adrian Sun's developer notes on CNID including the data flow
+through the CNID calculation, storage and retrieval process.
+
+the catalog database keeps track of three mappings:
+    CNID     -> dev/ino and did/name
+    dev/ino  -> CNID
+    did/name -> CNID
+
+dev/ino is used to keep track of magically moved files. did/name is
+for quick lookups of CNIDs. 
+
+NOTE: the database will append a nul byte to the end of name. in
+addition, name should be given as it appears on disk. this allows the
+creation of cnid updating/cleaning programs that don't have to deal
+with knowing what the particular codepage is.
+
+here's the ritual:
+       1) open a volume. call cnid_open.
+       2) every time you need a CNID, call cnid_add(). it will
+          automatically look for an existing cnid and add a new one
+          if one isn't already there. you can pass a hint if you
+          want. the only use this has right now is to enable
+          consistency between AFP and HFS. in the future, it would
+          allow people to write conversion utilities that
+          pre-instantiate a database without needing to re-assign
+          CNIDs.
+       3) if you want to just look for a CNID without automatically
+          adding one in, you have two choices:
+            a) cnid_resolve takes a CNID, returns name, and
+               over-writes the CNID given with the parent DID. this
+               is good for FPResolveID.
+             b) cnid_lookup returns a CNID corresponding to the
+               dev/ino,did/name keys. it will auto-update the catalog
+               database if there's a discrepancy. 
+               NOTE: cnid_add calls this before adding a new CNID. 
+       4) when you delete a file or directory, you need to call
+          cnid_delete with the CNID for that file/directory.
+       5) call cnid_close when closing the volume.