doc/README.cnid

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