Linux Manual Pages development
 help / color / mirror / Atom feed
* [PATCH v1 0/3] man/man2const: Document fcntls F_DUPFD_QUERY, F_CREATED_QUERY
@ 2026-10-12 21:08 Yannick Le Pennec
  2026-10-12 21:08 ` [PATCH v1 1/3] man/man2const/F_DUPFD_QUERY.2const: Add page Yannick Le Pennec
                   ` (3 more replies)
  0 siblings, 4 replies; 7+ messages in thread
From: Yannick Le Pennec @ 2026-10-12 21:08 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: linux-man, Yannick Le Pennec

Linux 6.10 and 6.12 added two new fcntl(2) operations, respectively:

  F_DUPFD_QUERY
    since linux 6.10  c62b758bae6a ("fcntl: add F_DUPFD_QUERY fcntl()")
    since glibc 2.41  28f8cee64a32 ("Add F_DUPFD_QUERY from Linux 6.10 to
                                    bits/fcntl-linux.h")
    Checks whether two fds point to the same open file description.

  F_CREATED_QUERY
    since linux 6.12  820a185896b7 ("fcntl: add F_CREATED_QUERY")
    since glibc 2.41  322e9d4e4430 ("Add F_CREATED_QUERY from Linux 6.12 to
                                    bits/fcntl-linux.h")
    Checks whether a file was created by a call to open(2) with O_CREAT.

This patch series documents both operations individually, with usage examples,
then adds a new category in fcntl.2 that references them.
I hesitated somewhat on whether F_DUPFD_QUERY should belong in the
'Duplicating a file descriptor' section of fcntl.2, or whether it should go with
F_CREATED_QUERY in a separate 'Open file description queries' section, this
series proposes the latter.

Link: <https://lore.kernel.org/dri-devel/CAHk-=wixO-fmQYgbGic-BQVUd9RQhwGsF4bGk8ufWDKnRS1v_A@mail.gmail.com/>
Link: <https://lore.kernel.org/all/20240724-work-fcntl-v1-1-e8153a2f1991@kernel.org/>
Link: <https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=28f8cee64a3223636d15c78f69432503d8ef1c22>
Link: <https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=322e9d4e443084336ea41a8e7bf72456ab273b73>

Yannick Le Pennec (3):
  man/man2const/F_DUPFD_QUERY.2const: Add page
  man/man2const/F_CREATED_QUERY.2const: Add page
  man/man2/fcntl.2: Add section

 man/man2/fcntl.2                     |   5 ++
 man/man2const/F_CREATED_QUERY.2const | 107 +++++++++++++++++++++++++++
 man/man2const/F_DUPFD_QUERY.2const   | 105 ++++++++++++++++++++++++++
 3 files changed, 217 insertions(+)
 create mode 100644 man/man2const/F_CREATED_QUERY.2const
 create mode 100644 man/man2const/F_DUPFD_QUERY.2const

Range-diff against v0:
-:  ---------- > 1:  8fc8c6255e man/man2const/F_DUPFD_QUERY.2const: Add page
-:  ---------- > 2:  a29379d2a6 man/man2const/F_CREATED_QUERY.2const: Add page
-:  ---------- > 3:  fcc62e822a man/man2/fcntl.2: Add section
-- 
2.55.0


^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH v1 1/3] man/man2const/F_DUPFD_QUERY.2const: Add page
  2026-10-12 21:08 [PATCH v1 0/3] man/man2const: Document fcntls F_DUPFD_QUERY, F_CREATED_QUERY Yannick Le Pennec
@ 2026-10-12 21:08 ` Yannick Le Pennec
  2026-10-24 11:13   ` Alejandro Colomar
  2026-10-12 21:08 ` [PATCH v1 2/3] man/man2const/F_CREATED_QUERY.2const: " Yannick Le Pennec
                   ` (2 subsequent siblings)
  3 siblings, 1 reply; 7+ messages in thread
From: Yannick Le Pennec @ 2026-10-12 21:08 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: linux-man, Yannick Le Pennec

Linux 6.10 adds a new fcntl(2) operation, F_DUPFD_QUERY, which glibc exposes
since 2.41. This commit documents it, with example usage.

In essence, F_DUPFD_QUERY takes two file descriptors and determines whether they
refer to the same open file description (by comparing the pointers to the
underlying struct file). Two file descriptors can refer to the same open file
description if one was obtained by dup(2)ing the other, for example.

Previously, this comparison could be done through the kcmp system call with
KCMP_FILE (see kcmp(2)), but not only that interface is much broader, glibc
does not presently provide a wrapper for it.

See-also: linux.git c62b758bae6a ("fcntl: add F_DUPFD_QUERY fcntl()")
See-also: glibc.git 28f8cee64a32 ("Add F_DUPFD_QUERY from Linux 6.10 to
                                  bits/fcntl-linux.h")
Link: <https://lore.kernel.org/dri-devel/CAHk-=wixO-fmQYgbGic-BQVUd9RQhwGsF4bGk8ufWDKnRS1v_A@mail.gmail.com/>
Link: <https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=28f8cee64a3223636d15c78f69432503d8ef1c22>
Signed-off-by: Yannick Le Pennec <yannick.lepennec@live.fr>
---
 man/man2const/F_DUPFD_QUERY.2const | 105 +++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 man/man2const/F_DUPFD_QUERY.2const

diff --git a/man/man2const/F_DUPFD_QUERY.2const b/man/man2const/F_DUPFD_QUERY.2const
new file mode 100644
index 0000000000..0a07f3968a
--- /dev/null
+++ b/man/man2const/F_DUPFD_QUERY.2const
@@ -0,0 +1,105 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH F_DUPFD_QUERY 2const 2026-10-11 "Linux man-pages (unreleased)"
+.SH NAME
+F_DUPFD_QUERY
+\-
+determine whether two file descriptors refer to the same open file description
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #define _GNU_SOURCE
+.B #include <fcntl.h>
+.P
+.BI "int fcntl(int " fd ", F_DUPFD_QUERY, int " other );
+.fi
+.SH DESCRIPTION
+Determine whether file descriptors
+.I fd
+and
+.I other
+refer to the same open file description (see
+.BR open (2)).
+.SH RETURN VALUE
+On success, if both
+.I fd
+and
+.I other
+refer to the same open file description, 1 is returned.
+Otherwise, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+See
+.BR fcntl (2).
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.10.
+.SH NOTES
+On Linux, this
+.BR fcntl ()
+.BR F_DUPFD_QUERY
+operation is a narrower, more efficient spelling of the following
+.BR kcmp (2)
+invocation:
+.P
+.in +4n
+.EX
+int   ret;
+pid_t pid;
+
+pid = getpid();
+ret = syscall(SYS_kcmp, pid, pid, KCMP_FILE, fd, other);
+
+if (ret == 0) {
+	/* fd and other refer to the same file */
+}
+.EE
+.in
+.SH EXAMPLES
+The following program checks whether standard output and standard error streams
+refer to the same open file description (typically, the user's terminal).
+Example output:
+.P
+.in +4n
+.EX
+.RB $ " ./a.out"
+stdout and stderr are the same file
+.RB $ " ./a.out 2> /dev/null"
+stdout and stderr are different files
+.EE
+.in
+.SS Program source
+.\" SRC BEGIN (dupfd_query.c)
+.EX
+#define _GNU_SOURCE
+#include <err.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+\&
+int
+main(void) {
+	int ret;
+
+	ret = fcntl(STDOUT_FILENO, F_DUPFD_QUERY, STDERR_FILENO);
+	if (ret == -1)
+		err(EXIT_FAILURE, "fcntl");
+
+	printf("stdout and stderr are %s\[rs]n",
+	       ret ? "the same file" : "different files");
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR dup (2),
+.BR fcntl (2),
+.BR kcmp (2),
+.BR open (2)
-- 
2.55.0


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* [PATCH v1 2/3] man/man2const/F_CREATED_QUERY.2const: Add page
  2026-10-12 21:08 [PATCH v1 0/3] man/man2const: Document fcntls F_DUPFD_QUERY, F_CREATED_QUERY Yannick Le Pennec
  2026-10-12 21:08 ` [PATCH v1 1/3] man/man2const/F_DUPFD_QUERY.2const: Add page Yannick Le Pennec
@ 2026-10-12 21:08 ` Yannick Le Pennec
  2026-10-12 21:08 ` [PATCH v1 3/3] man/man2/fcntl.2: Add section Yannick Le Pennec
  2026-10-24 10:55 ` [PATCH v1 0/3] man/man2const: Document fcntls F_DUPFD_QUERY, F_CREATED_QUERY Alejandro Colomar
  3 siblings, 0 replies; 7+ messages in thread
From: Yannick Le Pennec @ 2026-10-12 21:08 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: linux-man, Yannick Le Pennec

Linux 6.12 adds a new fcntl(2) operation, F_CREATED_QUERY, which glibc exposes
since 2.41. This commit documents it, with example usage.

When a file is open(2)ed with the O_CREAT flag, it is potentially created (if it
does not already exist), in which case the open file description has the flag
FMODE_CREATED set. The F_CREATED_QUERY operation gives userspace a way of
retrieving the value of that flag to determine whether the open call resulted or
not in the file being created.

Previously you had to jump through a variety of questionable hoops to achieve
something similar (see the kernel.org discussion in the link below).

See-also: linux.git 820a185896b7 ("fcntl: add F_CREATED_QUERY")
See-also: glibc.git 322e9d4e4430 ("Add F_CREATED_QUERY from Linux 6.12 to
                                   bits/fcntl-linux.h")
Link: <https://lore.kernel.org/all/20240724-work-fcntl-v1-1-e8153a2f1991@kernel.org/>
Link: <https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=322e9d4e443084336ea41a8e7bf72456ab273b73>
Signed-off-by: Yannick Le Pennec <yannick.lepennec@live.fr>
---
 man/man2const/F_CREATED_QUERY.2const | 107 +++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 man/man2const/F_CREATED_QUERY.2const

diff --git a/man/man2const/F_CREATED_QUERY.2const b/man/man2const/F_CREATED_QUERY.2const
new file mode 100644
index 0000000000..fe6a0fe536
--- /dev/null
+++ b/man/man2const/F_CREATED_QUERY.2const
@@ -0,0 +1,107 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH F_CREATED_QUERY 2const 2026-10-11 "Linux man-pages (unreleased)"
+.SH NAME
+F_CREATED_QUERY
+\-
+determine whether a file was created
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #define _GNU_SOURCE
+.B #include <fcntl.h>
+.P
+.BI "int fcntl(int " fd ", F_CREATED_QUERY);
+.fi
+.SH DESCRIPTION
+A call to
+.BR open( "..., " O_CREAT " | ..." )
+may optionally create a file, if the specified file does not already exist (see
+.BR open (2)
+for details).
+If the file was created, the
+.BR fcntl ()
+.B F_CREATED_QUERY
+operation on the resulting
+.I fd
+returns 1.
+Note that this is a property of the
+.IR "open file description" ,
+rather than the file descriptor, and therefore carries across any
+.BR dup (2)ed
+file descriptors.
+.SH RETURN VALUE
+On success, if
+.I fd
+refers to a file that was created by
+.BR open (2),
+1 is returned.
+Otherwise, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+See
+.BR fcntl (2).
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.12.
+.SH EXAMPLES
+The following program repeatedly attempts to open the file supplied in its first
+command-line argument, potentially creating it, prints whether that file was
+actually created, and exits if it wasn't.
+Example output:
+.P
+.in +4n
+.EX
+.RB $ " ./a.out some-path"
+F_CREATED_QUERY: 1 (file was created)
+F_CREATED_QUERY: 0 (file exists)
+.EE
+.in
+.SS Program source
+.\" SRC BEGIN (created_query.c)
+.EX
+#define _GNU_SOURCE
+#include <err.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+\&
+int
+main(int argc, char *argv[]) {
+	int fd;
+	int ret;
+
+	if (argc != 2) {
+		fprintf(stderr, "Usage: %s path\[rs]n", argv[0]);
+		exit(EXIT_FAILURE);
+	}
+
+	do {
+		fd = open(argv[1], O_CREAT | O_RDONLY, 0644);
+		if (fd == -1)
+			err(EXIT_FAILURE, "open");
+
+		ret = fcntl(fd, F_CREATED_QUERY);
+		if (ret == -1)
+			err(EXIT_FAILURE, "fcntl");
+
+		printf("F_CREATED_QUERY: %d (file %s)\[rs]n", ret,
+		       ret ? "was created" : "exists");
+
+		close(fd);
+	} while (ret != 0);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR creat (2),
+.BR fcntl (2),
+.BR open (2)
-- 
2.55.0


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* [PATCH v1 3/3] man/man2/fcntl.2: Add section
  2026-10-12 21:08 [PATCH v1 0/3] man/man2const: Document fcntls F_DUPFD_QUERY, F_CREATED_QUERY Yannick Le Pennec
  2026-10-12 21:08 ` [PATCH v1 1/3] man/man2const/F_DUPFD_QUERY.2const: Add page Yannick Le Pennec
  2026-10-12 21:08 ` [PATCH v1 2/3] man/man2const/F_CREATED_QUERY.2const: " Yannick Le Pennec
@ 2026-10-12 21:08 ` Yannick Le Pennec
  2026-10-24 11:18   ` Alejandro Colomar
  2026-10-24 10:55 ` [PATCH v1 0/3] man/man2const: Document fcntls F_DUPFD_QUERY, F_CREATED_QUERY Alejandro Colomar
  3 siblings, 1 reply; 7+ messages in thread
From: Yannick Le Pennec @ 2026-10-12 21:08 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: linux-man, Yannick Le Pennec

Add a new fcntl.2 section, 'Open file description queries', listing
F_DUPFD_QUERY and F_CREATED_QUERY.

Signed-off-by: Yannick Le Pennec <yannick.lepennec@live.fr>
---
 man/man2/fcntl.2 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2
index 446411a06e..521a4ddd09 100644
--- a/man/man2/fcntl.2
+++ b/man/man2/fcntl.2
@@ -112,6 +112,11 @@ indicating that the kernel does not recognize this value.
 .BR F_GET_FILE_RW_HINT (2const)
 .TQ
 .BR F_SET_FILE_RW_HINT (2const)
+.SS Open file description queries
+.TP
+.BR F_DUPFD_QUERY (2const)
+.TQ
+.BR F_CREATED_QUERY (2const)
 .SH RETURN VALUE
 For a successful call, the return value depends on the operation.
 .P
-- 
2.55.0


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH v1 0/3] man/man2const: Document fcntls F_DUPFD_QUERY, F_CREATED_QUERY
  2026-10-12 21:08 [PATCH v1 0/3] man/man2const: Document fcntls F_DUPFD_QUERY, F_CREATED_QUERY Yannick Le Pennec
                   ` (2 preceding siblings ...)
  2026-10-12 21:08 ` [PATCH v1 3/3] man/man2/fcntl.2: Add section Yannick Le Pennec
@ 2026-10-24 10:55 ` Alejandro Colomar
  3 siblings, 0 replies; 7+ messages in thread
From: Alejandro Colomar @ 2026-10-24 10:55 UTC (permalink / raw)
  To: Yannick Le Pennec; +Cc: linux-man

[-- Attachment #1: Type: text/plain, Size: 2571 bytes --]

Hi Yannick,

> Date: 2026-10-12 23:08:13+0200
> From: Yannick Le Pennec <yannick.lepennec@live.fr>
>
> Linux 6.10 and 6.12 added two new fcntl(2) operations, respectively:
> 
>   F_DUPFD_QUERY
>     since linux 6.10  c62b758bae6a ("fcntl: add F_DUPFD_QUERY fcntl()")
>     since glibc 2.41  28f8cee64a32 ("Add F_DUPFD_QUERY from Linux 6.10 to
>                                     bits/fcntl-linux.h")
>     Checks whether two fds point to the same open file description.
> 
>   F_CREATED_QUERY
>     since linux 6.12  820a185896b7 ("fcntl: add F_CREATED_QUERY")
>     since glibc 2.41  322e9d4e4430 ("Add F_CREATED_QUERY from Linux 6.12 to
>                                     bits/fcntl-linux.h")
>     Checks whether a file was created by a call to open(2) with O_CREAT.
> 
> This patch series documents both operations individually, with usage examples,
> then adds a new category in fcntl.2 that references them.
> I hesitated somewhat on whether F_DUPFD_QUERY should belong in the
> 'Duplicating a file descriptor' section of fcntl.2, or whether it should go with
> F_CREATED_QUERY in a separate 'Open file description queries' section, this
> series proposes the latter.

I agree with the proposal, since it doesn't duplicate an fd.  Thanks!


Have a lovely day!
Alex

> 
> Link: <https://lore.kernel.org/dri-devel/CAHk-=wixO-fmQYgbGic-BQVUd9RQhwGsF4bGk8ufWDKnRS1v_A@mail.gmail.com/>
> Link: <https://lore.kernel.org/all/20240724-work-fcntl-v1-1-e8153a2f1991@kernel.org/>
> Link: <https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=28f8cee64a3223636d15c78f69432503d8ef1c22>
> Link: <https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=322e9d4e443084336ea41a8e7bf72456ab273b73>
> 
> Yannick Le Pennec (3):
>   man/man2const/F_DUPFD_QUERY.2const: Add page
>   man/man2const/F_CREATED_QUERY.2const: Add page
>   man/man2/fcntl.2: Add section
> 
>  man/man2/fcntl.2                     |   5 ++
>  man/man2const/F_CREATED_QUERY.2const | 107 +++++++++++++++++++++++++++
>  man/man2const/F_DUPFD_QUERY.2const   | 105 ++++++++++++++++++++++++++
>  3 files changed, 217 insertions(+)
>  create mode 100644 man/man2const/F_CREATED_QUERY.2const
>  create mode 100644 man/man2const/F_DUPFD_QUERY.2const
> 
> Range-diff against v0:
> -:  ---------- > 1:  8fc8c6255e man/man2const/F_DUPFD_QUERY.2const: Add page
> -:  ---------- > 2:  a29379d2a6 man/man2const/F_CREATED_QUERY.2const: Add page
> -:  ---------- > 3:  fcc62e822a man/man2/fcntl.2: Add section
> -- 
> 2.55.0
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH v1 1/3] man/man2const/F_DUPFD_QUERY.2const: Add page
  2026-10-12 21:08 ` [PATCH v1 1/3] man/man2const/F_DUPFD_QUERY.2const: Add page Yannick Le Pennec
@ 2026-10-24 11:13   ` Alejandro Colomar
  0 siblings, 0 replies; 7+ messages in thread
From: Alejandro Colomar @ 2026-10-24 11:13 UTC (permalink / raw)
  To: Yannick Le Pennec; +Cc: linux-man

[-- Attachment #1: Type: text/plain, Size: 5577 bytes --]

Hi Yannick,

> Date: 2026-10-12 23:08:14+0200
> From: Yannick Le Pennec <yannick.lepennec@live.fr>
>
> Linux 6.10 adds a new fcntl(2) operation, F_DUPFD_QUERY, which glibc exposes
> since 2.41. This commit documents it, with example usage.
> 
> In essence, F_DUPFD_QUERY takes two file descriptors and determines whether they
> refer to the same open file description (by comparing the pointers to the
> underlying struct file). Two file descriptors can refer to the same open file
> description if one was obtained by dup(2)ing the other, for example.
> 
> Previously, this comparison could be done through the kcmp system call with
> KCMP_FILE (see kcmp(2)), but not only that interface is much broader, glibc
> does not presently provide a wrapper for it.
> 
> See-also: linux.git c62b758bae6a ("fcntl: add F_DUPFD_QUERY fcntl()")
> See-also: glibc.git 28f8cee64a32 ("Add F_DUPFD_QUERY from Linux 6.10 to
>                                   bits/fcntl-linux.h")
> Link: <https://lore.kernel.org/dri-devel/CAHk-=wixO-fmQYgbGic-BQVUd9RQhwGsF4bGk8ufWDKnRS1v_A@mail.gmail.com/>
> Link: <https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=28f8cee64a3223636d15c78f69432503d8ef1c22>
> Signed-off-by: Yannick Le Pennec <yannick.lepennec@live.fr>
> ---

Thanks!  LGTM, except for a feww minor details; see below.

>  man/man2const/F_DUPFD_QUERY.2const | 105 +++++++++++++++++++++++++++++
>  1 file changed, 105 insertions(+)
>  create mode 100644 man/man2const/F_DUPFD_QUERY.2const
> 
> diff --git a/man/man2const/F_DUPFD_QUERY.2const b/man/man2const/F_DUPFD_QUERY.2const
> new file mode 100644
> index 0000000000..0a07f3968a
> --- /dev/null
> +++ b/man/man2const/F_DUPFD_QUERY.2const
> @@ -0,0 +1,105 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH F_DUPFD_QUERY 2const 2026-10-11 "Linux man-pages (unreleased)"
> +.SH NAME
> +F_DUPFD_QUERY
> +\-
> +determine whether two file descriptors refer to the same open file description
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc )
> +.SH SYNOPSIS
> +.nf
> +.B #define _GNU_SOURCE
> +.B #include <fcntl.h>
> +.P
> +.BI "int fcntl(int " fd ", F_DUPFD_QUERY, int " other );
> +.fi
> +.SH DESCRIPTION
> +Determine whether file descriptors
> +.I fd
> +and
> +.I other
> +refer to the same open file description (see
> +.BR open (2)).
> +.SH RETURN VALUE
> +On success, if both
> +.I fd
> +and
> +.I other

We don't need to repeat their names.

> +refer to the same open file description, 1 is returned.
> +Otherwise, zero is returned.
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.

The 'Otherwise' above seems imprecise, since an error would also be an
otherwise.  I'd reword:

	On success,
	if both file descriptors
	refer to the same open file description,
	1 is returned;
	and if they don't,
	0 is returned.
	.P
	On error,
	\-1 is returned,
	and
	.I errno
	is set to indicate the error.

> +.SH ERRORS
> +See
> +.BR fcntl (2).
> +.SH STANDARDS
> +Linux.
> +.SH HISTORY
> +Linux 6.10.
> +.SH NOTES
> +On Linux, this
> +.BR fcntl ()

I'd remove the 'fcntl()' mention.  F_DUPFD_QUERY already implies
fcntl(2).  (And if we kept it, since it's a different page, it should
have a (2), not ().)

> +.BR F_DUPFD_QUERY
> +operation is a narrower, more efficient spelling of the following
> +.BR kcmp (2)
> +invocation:
> +.P
> +.in +4n
> +.EX
> +int   ret;
> +pid_t pid;
> +

We avoid blank lines in source code, since that triggers diagnostics
from groff(1).  We use a dummy character for these: \&

	pid_t  pid;
	\&
	pid = getpid();

> +pid = getpid();
> +ret = syscall(SYS_kcmp, pid, pid, KCMP_FILE, fd, other);
> +
> +if (ret == 0) {
> +	/* fd and other refer to the same file */
> +}

We can avoid the 'ret' variable:

	if (syscall(...) == 0) {
		/* ... */
	}

> +.EE
> +.in
> +.SH EXAMPLES
> +The following program checks whether standard output and standard error streams
> +refer to the same open file description (typically, the user's terminal).
> +Example output:
> +.P
> +.in +4n
> +.EX
> +.RB $ " ./a.out"
> +stdout and stderr are the same file
> +.RB $ " ./a.out 2> /dev/null"
> +stdout and stderr are different files

The output text seems imprecise.  It should say "refer to the same /
different open file descriptions".

	$ ./a.out >/dev/tty 2>/dev/tty
	stdout and stderr are different files

In the case above, it clearly refers to the same files, but they're
different open file descriptions.

> +.EE
> +.in
> +.SS Program source
> +.\" SRC BEGIN (dupfd_query.c)
> +.EX
> +#define _GNU_SOURCE
> +#include <err.h>
> +#include <fcntl.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <unistd.h>
> +\&

Yup, you used the \& correctly here.  :)

> +int
> +main(void) {

We have the opening brace on a line of its own (like the kernel).  The
coding style is in <CONTRIBUTING.d/style/c> (although you don't need to
read it; it's just this minor thing).


Cheers,
Alex

> +	int ret;
> +
> +	ret = fcntl(STDOUT_FILENO, F_DUPFD_QUERY, STDERR_FILENO);
> +	if (ret == -1)
> +		err(EXIT_FAILURE, "fcntl");
> +
> +	printf("stdout and stderr are %s\[rs]n",
> +	       ret ? "the same file" : "different files");
> +}
> +.EE
> +.\" SRC END
> +.SH SEE ALSO
> +.BR dup (2),
> +.BR fcntl (2),
> +.BR kcmp (2),
> +.BR open (2)
> -- 
> 2.55.0
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH v1 3/3] man/man2/fcntl.2: Add section
  2026-10-12 21:08 ` [PATCH v1 3/3] man/man2/fcntl.2: Add section Yannick Le Pennec
@ 2026-10-24 11:18   ` Alejandro Colomar
  0 siblings, 0 replies; 7+ messages in thread
From: Alejandro Colomar @ 2026-10-24 11:18 UTC (permalink / raw)
  To: Yannick Le Pennec; +Cc: linux-man

[-- Attachment #1: Type: text/plain, Size: 1021 bytes --]

Hi Yannick,

> Date: 2026-10-12 23:08:16+0200
> From: Yannick Le Pennec <yannick.lepennec@live.fr>
>
> Add a new fcntl.2 section, 'Open file description queries', listing
> F_DUPFD_QUERY and F_CREATED_QUERY.
> 
> Signed-off-by: Yannick Le Pennec <yannick.lepennec@live.fr>

Thanks!  I've applied this 3rd patch (not 1 nor 2).


Cheers,
Alex

> ---
>  man/man2/fcntl.2 | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2
> index 446411a06e..521a4ddd09 100644
> --- a/man/man2/fcntl.2
> +++ b/man/man2/fcntl.2
> @@ -112,6 +112,11 @@ indicating that the kernel does not recognize this value.
>  .BR F_GET_FILE_RW_HINT (2const)
>  .TQ
>  .BR F_SET_FILE_RW_HINT (2const)
> +.SS Open file description queries
> +.TP
> +.BR F_DUPFD_QUERY (2const)
> +.TQ
> +.BR F_CREATED_QUERY (2const)
>  .SH RETURN VALUE
>  For a successful call, the return value depends on the operation.
>  .P
> -- 
> 2.55.0
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2026-10-24 11:18 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-10-12 21:08 [PATCH v1 0/3] man/man2const: Document fcntls F_DUPFD_QUERY, F_CREATED_QUERY Yannick Le Pennec
2026-10-12 21:08 ` [PATCH v1 1/3] man/man2const/F_DUPFD_QUERY.2const: Add page Yannick Le Pennec
2026-10-24 11:13   ` Alejandro Colomar
2026-10-12 21:08 ` [PATCH v1 2/3] man/man2const/F_CREATED_QUERY.2const: " Yannick Le Pennec
2026-10-12 21:08 ` [PATCH v1 3/3] man/man2/fcntl.2: Add section Yannick Le Pennec
2026-10-24 11:18   ` Alejandro Colomar
2026-10-24 10:55 ` [PATCH v1 0/3] man/man2const: Document fcntls F_DUPFD_QUERY, F_CREATED_QUERY Alejandro Colomar

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox