Bug 91931

Summary:	fflush(3) is misleading about input streams
Product:	Documentation	Reporter:	cubbi
Component:	man-pages	Assignee:	documentation_man-pages (documentation_man-pages)
Status:	RESOLVED CODE_FIX
Severity:	normal	CC:	mtk.manpages
Priority:	P1
Hardware:	All
OS:	Linux
Kernel Version:		Subsystem:
Regression:	No	Bisected commit-id:

Description cubbi 2015-01-23 16:15:25 UTC

Current fflush(3) claims that

"For input streams, fflush() discards any buffered data that has been fetched from the underlying file, but has not been consumed by the application."

While technically true (assuming 'file' implies seekable device), this is incomplete: flushing an input stream associated with a non-seekable device, such as the terminal input, does nothing (the update to fp->_IO_read_end at libio/fileops.c:872 does not happen due to ESPIPE from lseek)

There have been enough confused beginner posts to various internet forums asking why flushing stdin doesn't work on Linux. I believe it is worth making the man page more explicit. At the very least, it should begin that sentence with "For input streams associated with seekable devices", or perhaps it should mention the unfortunately popular use case fflush(stdin) explicitly.

On a very minor note, fflush(3) also claims that
"The standards do not specify the behavior for input streams"

This is no longer precisely correct; POSIX specifies behavior for seekable input streams to move fileno's offset to match FILE's offset and undo all ungetc's: http://pubs.opengroup.org/onlinepubs/9699919799/functions/fflush.html and glibc conforms to that (or tries to, https://sourceware.org/bugzilla/show_bug.cgi?id=5994 is still open)

Comment 1 Michael Kerrisk 2015-01-25 19:53:00 UTC

Thanks for the report. I think you are more or less right. One question though: should the text not be in terms of "block buffered stream" rather than "seekable device"?

Thanks,

Michael

Comment 2 cubbi 2015-01-27 04:35:40 UTC

I don't see how buffering strategy would be relevant: it calls lseek(2) the same way whether the streams are setvbuf'd line-buffered or block-buffered.

POSIX wording is simply "the file is one capable of seeking"

Comment 3 Michael Kerrisk 2015-01-28 08:31:33 UTC

(In reply to cubbi from comment #0)

> On a very minor note, fflush(3) also claims that
> "The standards do not specify the behavior for input streams"
> 
> This is no longer precisely correct; POSIX specifies behavior for seekable
> input streams to move fileno's offset to match FILE's offset and undo all
> ungetc's:
> http://pubs.opengroup.org/onlinepubs/9699919799/functions/fflush.html and
> glibc conforms to that (or tries to,
> https://sourceware.org/bugzilla/show_bug.cgi?id=5994 is still open)

Thanks. I modified the text to note that POSIX.1-2008 does add specification for input streams.