On Fri, Mar 06, 2015 at 05:11:45PM +0100, Miklos Szeredi wrote: > On Thu, Jan 29, 2015 at 11:01:08AM +0100, Michael Kerrisk (man-pages) wrote: > > Hi Miklos, > > > > I just noticed that your RENAME_WHITEOUT flag went into Linux 3.18: > > commit 0d7a855526dd672e114aff2ac22b60fc6f155b08 > > commit 787fb6bc9682ec7c05fb5d9561b57100fbc1cc41 > > > > Would you be willing to write some text for the rename(2)/renameat2(2) > > man page that described this flag. In that text it would be great to > > have an explanation of what a whiteout is and why they are useful. > > Hi Michael, > > Sorry for the delay... > > RENAME_WHITEOUT is a special operation, that only makes sense for > overlay/union type filesystem implementations. Currently it is used > internally by the overlay filesystem. However, it is exposed to userspace by renameat2, and filesystem developers still need to know it's exact semantics documented so they can implement it. > Specifying RENAME_WHITEOUT will create a "whiteout" object at the source of > the rename at the same time as performing the rename. The whole operation is > still atomic, so if the rename succeeds then the whiteout will also have been > created. > > A "whiteout" is an object that has special meaning in union/overlay type file > system constructs, in these constructs multiple layers exists and only the top > one is ever modified. A whiteout on an upper layer will effectively hide the > matching file on the lower layer, making it appear if the file didn't exist. > > When a file that exists on the lower layer is renamed, the file is first > copied up (if not already on the upper layer) and then renamed on the upper, > read-write layer. At the same time the source file needs to be "whiteouted". > The whole operation needs to be done atomically. This doesn't explain exactly what the RENAME_WHITEOUT operation is supposed to do. It explains how overlayfs uses them, not the semantics and behaviour of RENAME_WHITEOUT. e.g. source restrictions, target restrictions, can you RENAME_WHITEOUT over another whiteout, etc. I've noticed these restrictions are very different from other rename operations, but I don't know whether that is ext4 implementation bugs or intentional because there is no documentation or regression tests in xfstests for it... Cheers, Dave. -- Dave Chinner david@xxxxxxxxxxxxx -- To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
