diff mbox series

[v2] flock.2: add CIFS details

Message ID 20210303163755.31127-1-aaptel@suse.com (mailing list archive)
State New, archived
Headers show
Series [v2] flock.2: add CIFS details | expand

Commit Message

Aurélien Aptel March 3, 2021, 4:37 p.m. UTC
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 other SMB clients.

  Since Linux 5.5, flock() 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 over SMB. Another important side-effect
  is  that  the  locks are not advisory anymore: a write on a locked file
  will always fail with EACCESS.  This difference originates from the de-
  sign of locks in the SMB protocol, which provides mandatory locking se-
  mantics. The nobrl mount option can be used switch back to pre-5.5 ker-
  nel behavior.

Signed-off-by: Aurelien Aptel <aaptel@suse.com>
---
 man2/flock.2 | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

Comments

Tom Talpey March 3, 2021, 6:08 p.m. UTC | #1
Definitely better! Couple of suggestions:

On 3/3/2021 11:37 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 other SMB clients.
> 
>    Since Linux 5.5, flock() 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 over SMB. Another important side-effect
>    is  that  the  locks are not advisory anymore: a write on a locked file
>    will always fail with EACCESS.  This difference originates from the de-
>    sign of locks in the SMB protocol, which provides mandatory locking se-
>    mantics. The nobrl mount option can be used switch back to pre-5.5 ker-
>    nel behavior.
> 
> Signed-off-by: Aurelien Aptel <aaptel@suse.com>
> ---
>   man2/flock.2 | 21 +++++++++++++++++++++
>   1 file changed, 21 insertions(+)
> 
> diff --git a/man2/flock.2 b/man2/flock.2
> index 61d4b5396..7c4e7e8c9 100644
> --- a/man2/flock.2
> +++ b/man2/flock.2
> @@ -239,6 +239,27 @@ see the discussion of the
>   .I "local_lock"
>   option in
>   .BR nfs (5).
> +.SS CIFS details
> +In Linux kernels up to 5.4,
> +.BR flock ()
> +is not propagated over SMB. A file with such locks will not appear
> +locked for other SMB clients.

Other "remote" clients, right? It's not limited to SMB, if the server
is also managing other protocols which might support flock'ing.

> +.PP
> +Since Linux 5.5,
> +.BR flock ()
> +are emulated with SMB byte-range locks on the
> +entire file. Similarly to NFS, this means that
> +.BR fcntl (2)
> +and
> +.BR flock ()
> +locks interact with one another over SMB. Another important

There's a subtlety here. If the server implements these SMB byte-range
locks in certain ways, the locks may interact with other protocols too.
So constraining the statement to "over SMB" may be incomplete.

Wy not simply say "this means that fcntl() and flock() locks interact
with one another", and preserve the generality?

> +side-effect is that the locks are not advisory anymore: a write on a
> +locked file will always fail with
> +.BR EACCESS .
> +This difference originates from the design of locks in the SMB
> +protocol, which provides mandatory locking semantics. The
> +.BR nobrl
> +mount option can be used switch back to pre-5.5 kernel behavior.

Wait, the page just said that pre-5.5 was local only. Wouldn't it
be better to just say that "nobrl" turns off the entire behavior of
forwarding locks to the server, like before? Or are there other
side effects...

Tom.

>   .SH SEE ALSO
>   .BR flock (1),
>   .BR close (2),
>
diff mbox series

Patch

diff --git a/man2/flock.2 b/man2/flock.2
index 61d4b5396..7c4e7e8c9 100644
--- a/man2/flock.2
+++ b/man2/flock.2
@@ -239,6 +239,27 @@  see the discussion of the
 .I "local_lock"
 option in
 .BR nfs (5).
+.SS CIFS details
+In Linux kernels up to 5.4,
+.BR flock ()
+is not propagated over SMB. A file with such locks will not appear
+locked for other SMB clients.
+.PP
+Since Linux 5.5,
+.BR flock ()
+are emulated with SMB byte-range locks on the
+entire file. Similarly to NFS, this means that
+.BR fcntl (2)
+and
+.BR flock ()
+locks interact with one another over SMB. Another important
+side-effect is that the locks are not advisory anymore: a write on a
+locked file will always fail with
+.BR EACCESS .
+This difference originates from the design of locks in the SMB
+protocol, which provides mandatory locking semantics. The
+.BR nobrl
+mount option can be used switch back to pre-5.5 kernel behavior.
 .SH SEE ALSO
 .BR flock (1),
 .BR close (2),