diff mbox series

[v3] flock.2: add CIFS details

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

Commit Message

Aurélien Aptel March 3, 2021, 7:03 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 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 EACCESS.  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>
---
 man2/flock.2 | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

Comments

Tom Talpey March 3, 2021, 8:23 p.m. UTC | #1
It looks great, and sorry to be a pest, but I just noticed - it's
EACCES (not EACCESS).

Reviewed-By: Tom Talpey <tom@talpey.com>

On 3/3/2021 2:03 PM, 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 EACCESS.  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>
> ---
>   man2/flock.2 | 29 +++++++++++++++++++++++++++++
>   1 file changed, 29 insertions(+)
> 
> diff --git a/man2/flock.2 b/man2/flock.2
> index 61d4b5396..4b6e5cc24 100644
> --- a/man2/flock.2
> +++ b/man2/flock.2
> @@ -239,6 +239,35 @@ 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: a write on a locked file will
> +always fail with
> +.BR EACCESS .

EACCES

> +This difference originates from the design of locks in the SMB
> +protocol, which provides mandatory locking semantics. The
> +.I nobrl
> +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),
>
Aurélien Aptel March 4, 2021, 9:48 a.m. UTC | #2
Tom Talpey <tom@talpey.com> writes:
> It looks great, and sorry to be a pest, but I just noticed - it's
> EACCES (not EACCESS).

No worries, thanks for the review.

Cheers,
diff mbox series

Patch

diff --git a/man2/flock.2 b/man2/flock.2
index 61d4b5396..4b6e5cc24 100644
--- a/man2/flock.2
+++ b/man2/flock.2
@@ -239,6 +239,35 @@  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: 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
+.I nobrl
+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),