Re: [PATCH] fcntl.2: document F_UNLCK F_OFD_GETLK extension

[Jeff Layton <jlayton@kernel.org>]

On Wed, 2023-06-21 at 20:22 +0500, Stas Sergeev wrote:
> F_UNLCK has the special meaning when used as a lock type on input.
> It returns the information about any lock found in the specified
> region on that particular file descriptor. Locks on other file
> descriptors are ignored by F_UNLCK.
> 
> Signed-off-by: Stas Sergeev <stsp2@yandex.ru>
> 
> CC: Jeff Layton <jlayton@kernel.org>
> CC: Chuck Lever <chuck.lever@oracle.com>
> CC: Alexander Viro <viro@zeniv.linux.org.uk>
> CC: Christian Brauner <brauner@kernel.org>
> CC: linux-fsdevel@vger.kernel.org
> CC: linux-kernel@vger.kernel.org
> CC: Shuah Khan <shuah@kernel.org>
> CC: linux-kselftest@vger.kernel.org
> CC: linux-api@vger.kernel.org
> 
> ---
>  man2/fcntl.2 | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/man2/fcntl.2 b/man2/fcntl.2
> index 7b5604e3a..e3e3e7b8c 100644
> --- a/man2/fcntl.2
> +++ b/man2/fcntl.2
> @@ -604,6 +604,13 @@ then details about one of these locks are returned via
>  .IR lock ,
>  as described above for
>  .BR F_GETLK .
> +.B F_UNLCK
> +has the special meaning when put into
> +.I l_type
> +as an input. It returns the information about any lock in the specified
> +range on that particular file descriptor. The locks on other file
> +descriptors are ignored by
> +.BR F_UNLCK .
>  .PP
>  In the current implementation,
>  .\" commit 57b65325fe34ec4c917bc4e555144b4a94d9e1f7


We need to be pedantic for manpages. A "file description" is the
representation of the open file in the kernel (basically, the "struct
file" in the kernel). A file _descriptor_ is the numeric identifier
returned by open() and similar functions.

The locks are owned by the file description, so that would be the better
term to use here. I think you want something like:

"When the l_type is set to F_UNLCK, returned locks are limited to ones
set on the given file description. Locks set on other file descriptions
are ignored on F_GETLK requests with the l_type set to F_UNLCK."

-- 
Jeff Layton <jlayton@kernel.org>