Hi Greg,
On 04/03/2014 02:57 PM, Greg Troxel wrote:
>
> "Michael Kerrisk (man-pages)" <mtk.manpages@xxxxxxxxx> writes:
>
>> I think the only reasonable solution is to better document existing
>> behavior and what the programmer should do. With that in mind, I've
>> drafted the following text for the msync(2) man page:
>>
>> NOTES
>> According to POSIX, exactly one of MS_SYNC and MS_ASYNC must be
>> specified in flags. However, Linux permits a call to msync()
>> that specifies neither of these flags, with semantics that are
>> (currently) equivalent to specifying MS_ASYNC. (Since Linux
>> 2.6.19, MS_ASYNC is in fact a no-op, since the kernel properly
>> tracks dirty pages and flushes them to storage as necessary.)
>> Notwithstanding the Linux behavior, portable, future-proof appli‐
>> cations should ensure that they specify exactly one of MS_SYNC
>> and MS_ASYNC in flags.
>>
>> Comments on this draft welcome.
>
> I think it's a step backwards to document unspecified behavior. If
> anything, the man page should make it clear that providing neither flag
> results in undefined behavior and will lead to failure on systems on
> than Linux. While I can see the point of not changing the previous
> behavior to protect buggy code, there's no need to document it in the
> man page and further enshrine it.
The Linux behavior is what it is. For the reasons I mentioned already,
it's unlikely to change. And, when the man pages omit to explain what
Linux actually does, there will one day come a request to actually
document the behavior. So, I don't think it's quite enough to say the
behavior is undefined. On the other hand, it does not hurt to further
expand the portability warning. I made the text now:
NOTES
According to POSIX, either MS_SYNC or MS_ASYNC must be specified
in flags, and indeed failure to include one of these flags will
cause msync() to fail on some systems. However, Linux permits a
call to msync() that specifies neither of these flags, with
semantics that are (currently) equivalent to specifying MS_ASYNC.
(Since Linux 2.6.19, MS_ASYNC is in fact a no-op, since the ker‐
nel properly tracks dirty pages and flushes them to storage as
necessary.) Notwithstanding the Linux behavior, portable,
future-proof applications should ensure that they specify either
MS_SYNC or MS_ASYNC in flags.
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@xxxxxxxxx. For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@xxxxxxxxx";> email@xxxxxxxxx </a>