Re: [PATCH v1 1/3] man/man2const/F_DUPFD_QUERY.2const: Add page

[Alejandro Colomar <alx@kernel.org>]

[-- 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 --]