StoreObjectInfoFile

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:

Name	Size 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

Location

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

Directory

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"