Re: [PATCH v4] flock.2: add CIFS details

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

On 3/4/21 10:50 AM, Aurélien Aptel wrote:
> From: Aurelien Aptel <aaptel@suse.com>
> 
> Similarly to NFS, CIFS flock() locks behave differently than the
> standard. Document those differences.
> 
> Here is the rendered text:
> 
> CIFS details
>    In  Linux kernels up to 5.4, flock() is not propagated over SMB. A file
>    with such locks will not appear locked for remote clients.
> 
>    Since Linux 5.5, flock() locks are emulated with SMB  byte-range  locks
>    on  the  entire  file.  Similarly  to NFS, this means that fcntl(2) and
>    flock() locks interact with one another. Another important  side-effect
>    is  that  the  locks are not advisory anymore: a write on a locked file
>    will always fail with EACCES.   This difference originates from the de-
>    sign of locks in the SMB protocol, which provides mandatory locking se-
>    mantics. The nobrl mount option (see mount.cifs(8)) turns off  fnctl(2)
>    and  flock() lock propagation to remote clients and makes flock() locks
>    advisory again.
> 
> Signed-off-by: Aurelien Aptel <aaptel@suse.com>
> Reviewed-By: Tom Talpey <tom@talpey.com>
> ---
[...]
> +This difference originates from the design of locks in the SMB
> +protocol, which provides mandatory locking semantics. The
> +.I nobrl

I agree with Tom.  It's much easier to read if you just say that 'nobrl' 
torns off the non-locale behaviour, and acts as 5.4 and earlier kernels. 
  Unless there's any subtlety that makes it different.  Is there any?

BTW, you should use "semantic newlines":

$ man 7 man-pages |sed -n '/semantic newlines/,/^$/p'
    Use semantic newlines
        In the source of a manual page,  new  sentences  should  be
        started  on new lines, and long sentences should split into
        lines at clause breaks (commas, semicolons, colons, and  so
        on).   This  convention,  sometimes known as "semantic new-
        lines", makes it easier to see the effect of patches, which
        often  operate at the level of individual sentences or sen-
        tence clauses.


Thanks,

Alex

> +mount option (see
> +.BR mount.cifs (8))
> +turns off
> +.BR fnctl (2)
> +and
> +.BR flock ()
> +lock propagation to remote clients and makes
> +.BR flock ()
> +locks advisory again.
>   .SH SEE ALSO
>   .BR flock (1),
>   .BR close (2),
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/