From: jmarcus Date: Sat, 4 Jan 2003 22:14:03 +0000 (+0000) Subject: Add a README.cnid which talks about what CNID is, and what it means to X-Git-Tag: netatalk-2-0-alpha1~292 X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?p=netatalk.git;a=commitdiff_plain;h=b5e1b86dbb6a88b186c43b0589a41bf4e59ecf9f 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 e962801c..f06a80e9 100644 --- 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 index 00000000..e0dc5c01 --- /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 . His developer notes can be found +below. It was later picked up and modernized by Uwe Hees +. Then, Joe Marcus Clarke +started fixing bugs and adding additional features. The Concurrent +Datastore support was added by Dan Wilga . +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.