Re: Documenting RENAME_WHITEOUT

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

On 03/06/2015 10:44 PM, Dave Chinner wrote:
> 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...

What Dave said!

Miklos, AFAICS, RENAME_WHITEOUT is user-space visible. Would you be 
willing to write some piece for the man page to explain things
from a user-space perspective?

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html