forked from rpms/glibc
71 lines
3.4 KiB
Diff
71 lines
3.4 KiB
Diff
commit 7fe1fde499507126f7de10ebf12fecaf77ae6602
|
|
Author: Joseph Myers <josmyers@redhat.com>
|
|
Date: Mon Oct 28 22:22:26 2024 +0000
|
|
|
|
Document further requirement on mixing streams / file descriptors
|
|
|
|
The gilbc manual has some documentation in llio.texi of requirements
|
|
for moving between I/O on FILE * streams and file descriptors on the
|
|
same open file description.
|
|
|
|
The documentation of what must be done on a FILE * stream to move from
|
|
it to either a file descriptor or another FILE * for the same open
|
|
file description seems to match POSIX. However, there is an
|
|
additional requirement in POSIX on the *second* of the two handles
|
|
being moved between, which is not mentioned in the glibc manual: "If
|
|
any previous active handle has been used by a function that explicitly
|
|
changed the file offset, except as required above for the first
|
|
handle, the application shall perform an lseek() or fseek() (as
|
|
appropriate to the type of handle) to an appropriate location.".
|
|
|
|
Document this requirement on seeking in the glibc manual, limited to
|
|
the case that seems relevant to glibc (the new channel is a previously
|
|
active stream, on which the seeking previously occurred). Note that
|
|
I'm not sure what the "except as required above for the first handle"
|
|
is meant to be about, so I haven't documented anything for it. As far
|
|
as I can tell, nothing specified for moving from the first handle
|
|
actually list calling a seek function as one of the steps to be done.
|
|
(Current POSIX doesn't seem to have any relevant rationale for this
|
|
section. The rationale in the 1996 edition says "In requiring the
|
|
seek to an appropriate location for the new handle, the application is
|
|
required to know what it is doing if it is passing streams with seeks
|
|
involved. If the required seek is not done, the results are undefined
|
|
(and in fact the program probably will not work on many common
|
|
implementations)." - which also doesn't help in understanding the
|
|
purpose of "except as required above for the first handle".)
|
|
|
|
Tested with "make info" and "make pdf".
|
|
|
|
diff --git a/manual/llio.texi b/manual/llio.texi
|
|
index 12194273801adc18..0f84a593ee92b31f 100644
|
|
--- a/manual/llio.texi
|
|
+++ b/manual/llio.texi
|
|
@@ -1097,6 +1097,27 @@ streams persist in other processes, their file positions become
|
|
undefined as a result. To prevent this, you must clean up the streams
|
|
before destroying them.
|
|
|
|
+In addition to cleaning up a stream before doing I/O using another
|
|
+linked channel, additional precautions are needed to ensure a
|
|
+well-defined file position indicator in some cases. If both the
|
|
+following conditions hold, you must set the file position indicator on
|
|
+the new channel (a stream) using a function such as @code{fseek}.
|
|
+
|
|
+@itemize @bullet
|
|
+@item
|
|
+The new linked channel is a stream that was previously active.
|
|
+
|
|
+@item
|
|
+The file position indicator was previously set on that channel (while
|
|
+it was previously active) with a function such as @code{fseek}.
|
|
+@end itemize
|
|
+
|
|
+POSIX requires such precautions in more cases: if either the old or
|
|
+the new linked channel is a stream (whether or not previously active)
|
|
+and the file position indicator was previously set on any channel
|
|
+linked to those channels with a function such as @code{fseek} or
|
|
+@code{lseek}.
|
|
+
|
|
@node Independent Channels
|
|
@subsection Independent Channels
|
|
@cindex independent channels
|