BCOS Native File System Attributes Application Note

BCOS Native File System Attributes Application Note
Version 1.0
(Preliminary Draft, Temporary)

Contents

1                Overview
2                User IDs
2.1                Fixed User IDs
3                Group IDs
3.1                Fixed Group IDs
4                Timestamps
5                File and Directory Names
6                File and Directory Permissions
6.1                General Flags
6.2                Group Read Flags for Directories
6.3                Group Write Flags for Directories
6.4                Group Read Flags for Files
6.5                Group Execute Flags for Files
7                Common Operations
7.1                Changing Directory And File Attributes
7.2                Reading Directory Contents
7.3                Reading Files
7.4                Creating A Directory
7.5                Creating A File
7.6                Modifying A File
7.7                Executing A File

Tables

Table 2.1      Fixed User ID Assignments
Table 3.1      Fixed Group ID Assignments
Table 5.1      Disallowed Characters In File And Directory Names
Table 6.1      General Flags

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.

2   User IDs

Every file and every directory is owned by either a user or a software developer. User IDs are 32-bit values, where users are assigned User IDs in the range 0x00000000 to 0x7FFFFFFF and software developers are assigned User IDs in the range from 0x80000000 to 0xFFFFFFFF. Some User IDs have a fixed meaning (see Section 2.1: Fixed User IDs), while the remaining User IDs are assigned dynamically by the operating system or by administrators.

2.1   Fixed User IDs

Some Used IDs are given fixed meanings. These Used IDs are described in Table 2.1: Fixed User ID Assignments.

User ID

Description

0x00000000

Anonymous/Guest

0x00000001

Head Administrator (cluster owner)

0x80000000

Operating System (boot code and kernel)

Table 2.1 - Fixed User ID Assignments

3 Group IDs

Users (but not software developers) may be given membership to groups, and all users that are members of a group may be allowed access to files and directories as a group. Group IDs are 8-bit values, allowing up to 256 separate groups to be defined. Some Group IDs have a fixed meaning (see Section 3.1: Fixed Group IDs), while the remaining Group IDs are assigned dynamically by administrators.

3.1 Fixed Group IDs

Some Group IDs are given fixed meanings. These Group IDs are described in Table 3.1: Fixed Group ID Assignments.

Group ID

Description

0x00

Administration

0x01

Maintenance

Table 3.1 - Fixed Group ID Assignments

4 Timestamps

Timestamps are 128-bit values, where the highest 96-bits contain the number of 1/4294967296^ths of a second and the value 0x800000000000000000000000 corresponds to midnight on January the 1^st 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 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 1^st 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.

5 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://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 0x0080 and 0x009F (inclusive), any characters deemed as white space by Unicode, and any of the characters listed in Table 5.1: Disallowed Characters In File And Directory Names.

Code

Character

Description

0x22

Double quote

0x2A

Asterix

0x3A

Colon

0x3C

Less than sign

0x3E

Greater than sign

0x3F

Question mark

0x5C

Backward slash

0x7F

DEL

Delete

Table 5.1 - Disallowed Characters In File And Directory Names

The forward slash character ('/', code 0x2F) must be used as a directory separator only.

6 File and Directory Permissions

6.1 General Flags

This field contains 16 flags. These flags are described in Table 6.1: General Flags.

Bit/s

Description

Owner read permission

Owner write permission (for directories) or owner execute permission (for files)

Group read enable, set if any bit in the Group Read Flags is set

Group write or group execute enable, set if any bit in the Group Write Flags (for files) or Group Execute Flags (for directories) is set

Anonymous read permission

Anonymous write permission (for directories) or Anonymous execute permission (for files)

Deleted

7 to 13

Reserved (currently unused)

Reserved for internal use (accessed flag)

Reserved for internal use (dirty flag)

Table 6.1 - General Flags

6.2   Group Read Flags for Directories

This field is a 256-bit bitfield, where each bit corresponds to a Group ID. If the bit for a group is set then users that are a member of the group are allowed to read from the directory.

6.3   Group Write Flags for Directories

This field is a 256-bit bitfield, where each bit corresponds to a Group ID. If the bit for a group is set then users that are a member of the group are allowed to write to the directory.

6.4   Group Read Flags for Files

This field is a 256-bit bitfield, where each bit corresponds to a Group ID. If the bit for a group is set then users that are a member of the group are allowed to read the file.

6.5   Group Execute Flags for Files

This field is a 256-bit bitfield, where each bit corresponds to a Group ID. If the bit for a group is set then users that are a member of the group are allowed to execute the file.

7   Common Operations

The following chapter describes the permissions necessary for a user or software developer to perform certain operations on files and directories. For this chapter, the word "user" will be used to describe anyone who has a User ID (either an actual user or a piece of software).

7.1   Changing Directory And File Attributes

The attributes for directories and files may only be changed by the owner of the file or directory.

Attributes include the General Flags, the Owner User ID, the Group Read Flags, the Group Write Flags or Group Execute Flags, and the Directory Name or File Name.

7.2   Reading Directory Contents

A user is able to read a directory's contents if:

•

the deleted flag in the General Flags is clear, and

•	the anonymous read permission bit in the General Flags is set, or
•	a bit in the Group Read Flags is set for any group that the user is a member of, or
•	the owner read permission flag in the General Flags is set and the user is the directory owner

7.3 Reading Files

A user is able to read a file if:

•

the deleted flag in the General Flags is clear, and

•	the anonymous read permission bit in the General Flags is set, or
•	a bit in the Group Read Flags is set for any group that the user is a member of, or
•	the owner read permission flag in the General Flags is set and the user is the file owner

7.4 Creating A Directory

A user is able to create a new directory contents if:

•

the parent directory exists and the deleted flag in the parent directory's General Flags is clear, and

•	the anonymous write permission bit in the parent directory's General Flags is set, or
•	a bit in the parent directory's Group Write Flags is set for any group that the user is a member of, or
•	the owner read permission flag in the parent directory's General Flags is set and the user is the parent directory's owner

7.5 Creating A File

A user is able to create a new file if:

•

the parent directory exists and the deleted flag in the parent directory's General Flags is clear, and

•	the anonymous write permission bit in the parent directory's General Flags is set, or
•	a bit in the parent directory's Group Write Flags is set for any group that the user is a member of, or
•	the owner read permission flag in the parent directory's General Flags is set and the user is the parent directory's owner

7.6 Modifying A File

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 (see Section 7.5: Creating A File).

This is comparable to reading an existing file and then creating a new file with a slightly different (but very similar) 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 existing files in that directory.

This also means that there's no point having any Group Write Flags for files; and no point having another timestamp to keep track of when the file or directory was last modified.

7.7 Executing A File

A user is able to execute a file if:

•

the deleted flag in the General Flags is clear, and

•	the anonymous execute permission bit in the General Flags is set, or
•	a bit in the Group Execute Flags is set for any group that the user is a member of, or
•	the owner execute permission flag in the General Flags is set and the user is the file owner

Generated on Sat Aug 1 16:05:47 2009