From creation to the first chunk
Creating a file is a metadata operation. The file stays metadata until something is written into it. This page describes what happens to a new object from the create call to its first chunk. The page covers what the Master Server records at creation and where the inode number comes from. The page also covers when a number is used again and what the first write adds that creation did not.
Creation writes an inode and a name
When a client creates a file, the Master Server checks the parent directory. The name must be free. The caller must be allowed to create entries in the parent directory. An inode quota on the path must have room (quota enforcement covers the tests). The Master Server then writes two records. One record is the inode. The inode includes the object's type, three timestamps, owner, group, permission bits, and policy. The other record is the edge: the name under the parent directory. Names: link, unlink, rename, and exchange covers what an edge is, and what hard links and renames do with it.
The policy is not chosen at this point. The policy is inherited. A new file or directory inherits the Storage Class, the trash retention, and the extra attributes from the parent directory. Any other kind of object inherits the extra attributes alone. A matching pattern overrides the inheritance in the same call. How policies are applied covers which fields are copied, which flags start clear, and how the winning pattern is chosen.
No Chunkserver takes part in any of this. A new file has length zero and no chunk table. There is no chunk anywhere that represents the empty file. A file that is never written never gets a chunk, so until the first write the file costs its metadata and nothing else. What metadata holds gives a figure for that cost. Symbolic links, FIFOs, sockets, and device nodes are created through the same path and stay that way permanently. These objects exist entirely in metadata and never have chunks. The policy page notes that a symbolic link is also the only object created without checking the patterns.
The Master Server gives a new object the lowest free inode number
The Master Server keeps a bitmap with one bit per inode number and gives a new object the lowest number whose bit is clear. Number 0 is reserved. Numbers are 32-bit values. Taking the lowest free number keeps the used range dense. A cluster that creates and deletes files fills the gaps that deletion left, rather than counting upward past every number it has ever used.
A deleted number returns after a delay
Deleting an object does not clear its bit. The number goes onto a list and is stamped with the time of the deletion. Once a minute the Master Server sweeps that list and releases the numbers whose stamp is older than INODE_REUSE_DELAY. The delay is one day unless you set it otherwise. Accepted values are from 300 to 3000000 seconds. A number whose file a client still holds open is set aside at the sweep and waits out the full delay again.
The delay exists because mounts cache. For a while after a deletion, a client can still resolve a cached name or attribute record to the old inode number. If the number were reused at once, that cached number would point at a different object. INODE_REUSE_DELAY must therefore stay longer than the timeout of every attribute, entry, and symbolic link cache on every mount. The default of one day is set well above the default timeouts of those caches.
The same window is the promise that an application gets from a (device, inode) pair. The pair names one object for as long as the object exists, and for INODE_REUSE_DELAY after its deletion. Some tools record inode numbers and compare them later, for example a backup program or a file indexer. Once the delay has passed, such a tool can find that the same number names a different file.
The first write creates the first chunk
A write is the first operation that involves a chunk. To store data, the mount asks the Master Server for the chunk that covers the part of the file being written. For a part that has no chunk yet, the Master Server creates a chunk. The Master Server extends the file's chunk table. The Master Server chooses a Chunkserver for each copy that the file's class requires at creation, and orders those servers to create the chunk. Allocation and space selection covers which servers qualify and how the choice is made. The new chunk starts at version 1 and is created locked for the writing client. Chunk versions and states covers what the version and the lock are for. The data itself never passes through the Master Server. The client sends the data to the first chosen Chunkserver. The write path describes how the data goes from there down the chain of copies.
The first write is therefore also the first operation that can run out of space. Creating the file succeeded without asking any disk for room. Creating the chunk cannot. When too few Chunkservers can take the chunk, fewer than the copies that the file's class requires at creation, the Master Server's answer tells the mount whether to wait the condition out or to fail the write. The mount retries or gives up accordingly. Allocation and space selection describes each answer and its retry schedule, up to the ENOSPC that the application finally sees.
Length, holes, and truncation covers how the file's length changes with writes, what a write far beyond the end leaves in between, and what truncation undoes.