The StoreObjectInfoFile is a binary file which is read and written by the Archive class (lib/common/Archive.cpp).

It contains information which the bbackupd client caches locally to avoid the need to repeatedly request it from the store. This includes the store directory listings of all directories which exist on the local disk as well, and are not excluded.

The StoreObjectInfoFile is deleted when a backup run starts, so that if bbackupd crashes during the run, it will not find an outdated cache and believe it to be correct. If the file does not exist at the start of a run, all the directory listings will be downloaded from the store during the run. The file is (re)created at the end of a successful run.

The file is not read while bbackupd is running. It is used to allow bbackupd to recover its cache after it is stopped and restarted. The cache is held in memory (as well) while bbackupd is running.

The existence of this documentation does not make the file an interface which will never change. The primary function of the file is internal to Box Backup, and developers should not rely on its format remaining the same. This documentation may well become outdated.

Data Types and Storage

The binary values in the file are always stored in network byte order for portability. Little-endian clients will need to convert them to host byte order when reading. Writing to the file, or relying on its presence or contents, is not recommended.

Storage sizes in bytes of each type supported by Archive:

NameSize on disk
bool 4 bytes (converted to "int" holding either 0 or -1)
int 4 bytes
int64_t 8 bytes
uint64_t 8 bytes
uint8_t 4 bytes (converted to "int")
string 4 bytes for length, followed by string data

Note: uint64_t and uint8_t are unsigned, the other integer types are signed.

Times are stored as uint64_t representing number of microseconds since the epoch (1st January 1980), i.e. a Unix timestamp with microsecond precision.

File Structure

The file has the following overall structure:

Item Format Value
Magic number int 0x7777525F
Magic string string BBACKUPD-STATE
Version int 2
Config timestamp uint64_t Last modified time of config file
Client store marker int64_t Current client store marker on the server when this state file was saved (at end of backup)
Last sync time uint64_t End of sync period (current time minus MinimumFileAge?) of last sync
Next sync time uint64_t Next sync planned start time
Number of locations int64_t Determines how many Location objects will follow
Locations n * Location See below
Number of mount points int64_t Determines how many mount points follow
Mount points n * string Mount points used by each location
Number of unused root dir entries int64_t Determines how many root dir entries follow
Unused root dir entries n * (int64_t, string) Object ID and name of each unused root dir entry
Time to delete unused root dir entries uint64_t


Item Format Value
Name string Name of location (directory name off the root of the store)
Path string Local path of the root of the location (Path value in configuration)
ID Map index int Index into list of mount points
Directory Marker int64_t Either 0x5449525F (noop) or 0x4449525F (recurse)
Directory Record Directory Only present if directory Marker is "recurse", see below for format
Exclude Files Marker int64_t Same as Directory Marker
Exclude Files Exclude List Only present if Exclude Files Marker is "recurse", see below for format
Exclude Dirs Marker int64_t Same as Directory Marker
Exclude Dirs Exclude List Only present if Exclude Dirs Marker is "recurse", see below for format


Item Format Value
Object ID uint64_t Object ID on the store
Name string name of directory (not including path)
Initial Sync Done bool No store directory if this is false
Sync Done bool Should have the same value as Initial Sync Done?
Checksum Length int64_t Number of bytes in the state checksum
Checksum Bytes n * int8_t Remember that int8_t is actually stored as a 32-bit value
Number of Pending Entries int64_t Number of directory entries not yet written to store (e.g. too new)
Pending Entries n * (string, uint64_t) Name and timestamp (when discovered) of each pending entry
Number of Subdirs int64_t
Subdirs n * (name, Directory) Recursive entries for subdirectories

Exclude List

Item Format Value
Number of definite entries int64_t Number of definite (non-regex) entries in exclude list
Definite Entries n * string Value of each entry
Number of definite entries int64_t Not present if compiled without regex support
Regex Entries n * string Value of each entry
AlwaysInclude? Marker int64_t Same as Directory Marker
AlwaysInclude? entries Exclude List Only present if the AlwaysInclude? marker is "recurse"
Last modified 10 years ago Last modified on Nov 8, 2008, 9:49:36 PM