BCOS Home » The BCOS Project » BCOS Specifications » BCOS Application Notes

BCOS Native File System Attributes Application Note

Preliminary Draft, Temporary

Project Map


Chapter 1: Overview

This Application Note is intended to explain the use of Directory and File attributes used by Native File Systems. It is expected that this document will be superceded by later specifications, and exists only as a reference for developers until it is superceded.

Chapter 2: Timestamps

Timestamps are 128-bit values, where the highest 96-bits contain the number of 1/4294967296ths of a second and the value 0x800000000000000000000000 corresponds to midnight on January the 1st in the year 2000 (UTC). The lowest 32-bits contain the node ID corresponding to the computer that created the file or directory. This ensures that if 2 different computers within the cluster create the same file at the same time, the resulting timestamps are still unique. The virtual file system layer on each node in each computer is responsible for ensuring that files with the same name are not created at the same time.

This provides (slightly better than) 232.831 pico-second precision and enough range to represent times 292 billion years before and after midnight on January the 1st in the year 2000 (UTC).

Note: The timestamp 0x00000000000000000000000000000000 has special meaning, and implies that the timestamp is unknown. Files and directories with unknown timestamps are treated as being older than the oldest possible file or directory.

Chapter 3: File and Directory Names

File and Directory names are always fully qualified names (they always include the path - for e.g. the name "foo/bar", and never the name "foo" in the implied directory "bar"). This means that in general the concept of a current directory does not exist; however it's possible for a process or thread to maintain it's own "current directory" as a string that's prepended to file names and directory names during file I/O operations.

All name strings use UTF-8 format, according to the Unicode Specification published by the Unicode Consortium (http://http://www.unicode.org/).

Some characters are not allowed within a file name or directory name. These characters include all characters with codes equal to or below 0x20, all characters with codes between 0x007F and 0x009F (inclusive), any characters deemed as white space by Unicode, and any of the characters listed in Table 3-1. Invalid Characters In File And Directory Names.

Table 3-1. Invalid Characters In File And Directory Names
0x3A:Colon (used for specifying a sub-file)
0x3B;Semicolon (used for name seperator in lists)
0x40@At sign (used for specifying a specific version of a file)

The forward slash character ('/', code 0x2F) must be used as a directory separator only. The underscore character may be used as "faux whitespace" for display purposes.

Chapter 4: General Flags

There are 16 "general flags" that control access permissions. These flags are described in Table 4-1. General Flags.

Table 4-1. General Flags
1 to 13Reserved (currently unused)
14Reserved for internal use (accessed flag)
15Reserved for internal use (dirty flag)

Chapter 5: File Owner Subject ID

Subject IDs are described by BCOS Security Model Application Note, Section 2.1. Subject IDs.

Chapter 6: Operation Permission Table

The permission table contains a 32-bit entry for each operation that could be performed on a file or directory; where each entry is an opaque "operation permission" as described by BCOS Security Model Application Note, Section 2.4. Operation Permissions. The operations are described in Table 6-1. Operation Table.

Table 6-1. Operation Table
Operation NumberOperation NameOperation Description
0ReadReading file contents (including sub-files) and reading directory contents
1Execute, CreateExecuting a file (for files only) and creating new files or directories (for directories only)
2RenameChanging a file's name and changing a directory's name
3DeleteDeleting a file and deleting a directory

Note that because the operating system uses file versioning, there is no such thing as modifying a file. Instead a new version of the file is created. This is comparable to reading an existing file and then creating a new file with a slightly different name on most other operating systems. For example, on most other operating systems a user can read the file "foo-v1.0" and create a new file "foo-v1.1" without having permission to write to the original file "foo-v1.0". This means that (in general) if a user has permission to create a new file in a directory, then they have permission to create new versions of all files they are able to read in that directory.

Generated at 03:08:42 on the 22nd of April, 2017 (UTC)