* [bug report] opendir(3): document file offset behavior for fdopendir()
@ 2026-11-13 21:28 Jorge Almeida
2026-11-13 21:39 ` Alejandro Colomar
0 siblings, 1 reply; 4+ messages in thread
From: Jorge Almeida @ 2026-11-13 21:28 UTC (permalink / raw)
To: linux-man
Hi,
The opendir(3) manual page currently describes fdopendir() as being
"like opendir(), but returns a directory stream for the directory
referred to by the open file descriptor fd."
However, it omits a critical detail documented in POSIX (fdopendir(3p))
and the BSD man pages: fdopendir() uses the current file offset of fd
rather than resetting it to zero.
If a caller duplicates an open directory descriptor with dup() and
exhausts the stream with readdir(), subsequent dup() + fdopendir()
calls will immediately hit EOF unless rewinddir() or lseek() is called.
By contrast, fdopen(3) explicitly warns that the stream's file
position indicator is set to that belonging to fd.
Could a similar note be added to the fdopendir() description in
opendir(3)?
Thanks.
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [bug report] opendir(3): document file offset behavior for fdopendir()
2026-11-13 21:28 [bug report] opendir(3): document file offset behavior for fdopendir() Jorge Almeida
@ 2026-11-13 21:39 ` Alejandro Colomar
2026-11-18 0:45 ` Alejandro Colomar
0 siblings, 1 reply; 4+ messages in thread
From: Alejandro Colomar @ 2026-11-13 21:39 UTC (permalink / raw)
To: Jorge Almeida; +Cc: linux-man
[-- Attachment #1: Type: text/plain, Size: 1311 bytes --]
Hi Jorge,
> Date: 2026-11-13 21:28:32+0000
> From: Jorge Almeida <jjalmeida@gmail.com>
>
> Hi,
>
> The opendir(3) manual page currently describes fdopendir() as being
> "like opendir(), but returns a directory stream for the directory
> referred to by the open file descriptor fd."
>
> However, it omits a critical detail documented in POSIX (fdopendir(3p))
> and the BSD man pages: fdopendir() uses the current file offset of fd
> rather than resetting it to zero.
>
> If a caller duplicates an open directory descriptor with dup() and
> exhausts the stream with readdir(), subsequent dup() + fdopendir()
> calls will immediately hit EOF unless rewinddir() or lseek() is called.
> By contrast, fdopen(3) explicitly warns that the stream's file
> position indicator is set to that belonging to fd.
>
> Could a similar note be added to the fdopendir() description in
> opendir(3)?
Would you mind sending a patch?
If so, you can have a look at
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING>
and
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/>
for some help (and I will gladly help if you have any questions).
Have a lovely night!
Alex
>
> Thanks.
>
--
<https://www.alejandro-colomar.es>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [bug report] opendir(3): document file offset behavior for fdopendir()
2026-11-13 21:39 ` Alejandro Colomar
@ 2026-11-18 0:45 ` Alejandro Colomar
[not found] ` <CAKpSnpJtcEf-RT+4yf=t3KtdYDWD3hfKqM51Di26ay7JHSj5MQ@mail.gmail.com>
0 siblings, 1 reply; 4+ messages in thread
From: Alejandro Colomar @ 2026-11-18 0:45 UTC (permalink / raw)
To: Jorge Almeida; +Cc: linux-man
[-- Attachment #1: Type: text/plain, Size: 2795 bytes --]
Hi Jorge,
> Date: 2026-11-13 22:39:06+0100
> From: Alejandro Colomar <alx+linux-man@kernel.org>
>
>
> Hi Jorge,
>
> > Date: 2026-11-13 21:28:32+0000
> > From: Jorge Almeida <jjalmeida@gmail.com>
> >
> > Hi,
> >
> > The opendir(3) manual page currently describes fdopendir() as being
> > "like opendir(), but returns a directory stream for the directory
> > referred to by the open file descriptor fd."
> >
> > However, it omits a critical detail documented in POSIX (fdopendir(3p))
> > and the BSD man pages: fdopendir() uses the current file offset of fd
> > rather than resetting it to zero.
> >
> > If a caller duplicates an open directory descriptor with dup() and
> > exhausts the stream with readdir(), subsequent dup() + fdopendir()
> > calls will immediately hit EOF unless rewinddir() or lseek() is called.
> > By contrast, fdopen(3) explicitly warns that the stream's file
> > position indicator is set to that belonging to fd.
> >
> > Could a similar note be added to the fdopendir() description in
> > opendir(3)?
I have applied the following patch:
commit 7b4329e4945b1506f75c67c18730ad0191e09fb0
Author: Alejandro Colomar <alx@kernel.org>
Date: 2026-11-18 01:38:13 +0100
man/man3/opendir.3: fdopendir(): Use wording mirroring that of fdopen(3)
The old documentation didn't clarify whether the position indicator was
reset or was that of the existing file descriptor. Let's use wording
mirroring fdopen(3), which already made this clear. This makes the
pages more consistent.
Reported-by: Jorge Almeida <jjalmeida@gmail.com>
Message-ID: <CAKpSnp+XojktUF=UL81JZ2bFyBSxXHneFSBsiPi2BMg043xa3g@mail.gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
diff --git a/man/man3/opendir.3 b/man/man3/opendir.3
index 443ea8f3dd0a..8184844893b9 100644
--- a/man/man3/opendir.3
+++ b/man/man3/opendir.3
@@ -43,16 +43,16 @@ .SH DESCRIPTION
The
.BR fdopendir ()
function
-is like
-.BR opendir (),
-but returns a directory stream for the directory referred
-to by the open file descriptor
+associates a directory stream
+with the existing directory file descriptor,
.IR fd .
-After a successful call to
-.BR fdopendir (),
-.I fd
-is used internally by the implementation,
-and should not otherwise be used by the application.
+The stream position indicator of the new directory stream
+is set to that belonging to
+.IR fd .
+The file descriptor is not dup'ed,
+and will be closed when the directory stream created by
+.BR fdopendir ()
+is closed.
.SH RETURN VALUE
The
.BR opendir ()
Let me know if you'd apply any changes after this patch.
Cheers,
Alex
--
<https://www.alejandro-colomar.es>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2026-11-18 11:21 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-13 21:28 [bug report] opendir(3): document file offset behavior for fdopendir() Jorge Almeida
2026-11-13 21:39 ` Alejandro Colomar
2026-11-18 0:45 ` Alejandro Colomar
[not found] ` <CAKpSnpJtcEf-RT+4yf=t3KtdYDWD3hfKqM51Di26ay7JHSj5MQ@mail.gmail.com>
2026-11-18 11:21 ` Alejandro Colomar
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.