Wim Lewis > Mac-Finder-DSStore-0.96 > Mac::Finder::DSStore



Annotate this POD

View/Report Bugs
Module Version: 0.96   Source   Latest Release: Mac-Finder-DSStore-1.00


Mac::Finder::DSStore - Read and write Macintosh Finder DS_Store files


Mac::Finder::DSStore provides a handful of functions for reading and writing the desktop database files created by the Macintosh Finder.


Many functions take a $store argument which is the opened file as an instance of Mac::Finder::DSStore::BuddyAllocator, or a $block argument which is a specific block of the file as an instance of Mac::Finder::DSStore::BuddyAllocator::Block.

@records = &Mac::Finder::DSStore::getDSDBEntries($store[, $callback])

Retrieves the "superblock" pointed to by the DSDB entry in the store's table of contents, and traverses the B-tree it points to, returning a list of the records in the tree. Alternately, you can supply a callback which will be invoked for each record, and getDSDBEntries will return an empty list.

&Mac::Finder::DSStore::putDSDBEntries($store, $arrayref)

$arrayref must contain a correctly ordered list of Mac::Finder::DSStore::Entry objects. They will be evenly organized into a B-tree structure and written to the $store. If there is an existing tree of records in the file already, it will be deallocated.

This function does not flush the allocator's information back to the file.

&Mac::Finder::DSStore::writeDSDBEntries($file, @entries)

A convenience function which sorts a list of entries and writes them to the specified file using putDSDBEntries, then flushes the allocator's data structures to disk. $file may be a filename or an open file handle. The store object is returned, but you don't need to do anything else with it.

&Mac::Finder::DSStore::makeEntries($filename, [ what => value ... ])

makeEntries encapsulates some information about the format of individual records in the DS_Store file. It returns a list of records constructed with the given filename and with the information specified in the rest of its args. Most args come in pairs, a name and a value, so makeEntries kind of looks like it takes a hash. Some names take no value and some could take several. Some produce more than one record as a result.

See the output of the examples/dsstore_dump.pl script for an example of how to use this, and check the source code for a list of the formats it accepts.

This function might change in the future.

Mac::Finder::DSStore::Entry ^

This class holds the individual records from the database. Each record contains a filename (in some cases, "." to refer to the containing directory), a 4-character record type, and a value. The value is one of a few concrete types, according to the record type.

$entry = ...::Entry->new($filename, $typecode)

Creates a new entry with no value. The concrete type is inferred from the record type code.


Gets the filename of an entry.


Gets the record type of this entry, as a four-character string, indicating what aspect of the file the entry describes.


Gets or sets the value of an entry.

If the concrete type is blob or type, the value is interpreted as a byte string; if it is ustr, as a character string. If the concrete type is long, shor, or bool, then the value should be an integer.


Returns -1, 0, or 1 depending on the relative ordering of the two entries, according to (a guess at) the record ordering used by the store's B-tree.


See Mac::Finder::DSStore::Format for more detailed information on the record types found in a DS_Store file.

See Mac::Finder::DSStore::BuddyAllocator for the low-level organization of the DS_Store file.


Copyright 2008 by Wim Lewis <wiml@hhhh.org>.

Some information is from Mark Mentovai via the Mozilla project. Thanks also to Martin Baker for bug reports.

syntax highlighting: