libatalk/cnid/db3/README

   1 the catalog database keeps track of three mappings:
   2     CNID     -> dev/ino and did/name
   3     dev/ino  -> CNID
   4     did/name -> CNID
   5
   6 dev/ino is used to keep track of magically moved files. did/name is
   7 for quick lookups of CNIDs.
   8
   9 NOTE: the database will append a nul byte to the end of name. in
  10 addition, name should be given as it appears on disk. this allows the
  11 creation of cnid updating/cleaning programs that don't have to deal
  12 with knowing what the particular codepage is.
  13
  14 here's the ritual:
  15         1) open a volume. call cnid_open.
  16         2) every time you need a CNID, call cnid_add(). it will
  17            automatically look for an existing cnid and add a new one
  18            if one isn't already there. you can pass a hint if you
  19            want. the only use this has right now is to enable
  20            consistency between AFP and HFS. in the future, it would
  21            allow people to write conversion utilities that
  22            pre-instantiate a database without needing to re-assign
  23            CNIDs.
  24         3) if you want to just look for a CNID without automatically
  25            adding one in, you have two choices:
  26              a) cnid_resolve takes a CNID, returns name, and
  27                 over-writes the CNID given with the parent DID. this
  28                 is good for FPResolveID.
  29              b) cnid_lookup returns a CNID corresponding to the
  30                 dev/ino,did/name keys. it will auto-update the catalog
  31                 database if there's a discrepancy.
  32                 NOTE: cnid_add calls this before adding a new CNID.
  33         4) when you delete a file or directory, you need to call
  34            cnid_delete with the CNID for that file/directory.
  35         5) call cnid_close when closing the volume.