[v5] flock.2: add CIFS details

Commit Message

Aurélien Aptel March 22, 2021, 2:30 p.m. UTC

From: Aurelien Aptel <[e-mail]>

CIFS flock() locks behave differently than the standard. Give overview
of 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: any IO on a locked file
  will always fail with EACCES when done from a separate file descriptor.
  This  difference  originates from the design of locks in the SMB proto-
  col, which provides mandatory locking semantics.

  Remote and mandatory locking semantics  may  vary  with  SMB  protocol,
  mount options and server type.  See mount.cifs(8) for additional infor-
  mation.

Signed-off-by: Aurelien Aptel <[e-mail]>
---
 man2/flock.2 | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

Comments

Aurélien Aptel April 9, 2021, 12:13 p.m. UTC | #1

Friendly ping to the man page maintainers

Cheers,

Alejandro Colomar April 11, 2021, 7:12 p.m. UTC | #2

Hello Aurélien,

On 4/9/21 2:13 PM, Aurélien Aptel wrote:
> 
> Friendly ping to the man page maintainers
> 
> Cheers,
> 

Sorry for the delay and thanks for the ping!
Patch applied.

Cheers,

Alex

Patch

diff --git a/man2/flock.2 b/man2/flock.2
index 328377365..61822c9bc 100644
--- a/man2/flock.2
+++ b/man2/flock.2
@@ -239,6 +239,31 @@  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 remote clients.
+.PP
+Since Linux 5.5,
+.BR flock ()
+locks 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.
+Another important side-effect is that the locks are not advisory anymore:
+any IO on a locked file will always fail with
+.BR EACCES
+when done from a separate file descriptor.
+This difference originates from the design of locks in the SMB protocol,
+which provides mandatory locking semantics.
+.PP
+Remote and mandatory locking semantics may vary with SMB protocol, mount options and server type.
+See
+.BR mount.cifs (8)
+for additional information.
 .SH SEE ALSO
 .BR flock (1),
 .BR close (2),