diff options
Diffstat (limited to 'doc/gawk.texi')
| -rw-r--r-- | doc/gawk.texi | 44 |
1 files changed, 28 insertions, 16 deletions
diff --git a/doc/gawk.texi b/doc/gawk.texi index cfe6cc91..63e9cbd6 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -20,7 +20,7 @@ @c applies to and all the info about who's publishing this edition @c These apply across the board. -@set UPDATE-MONTH October, 2012 +@set UPDATE-MONTH December, 2012 @set VERSION 4.0 @set PATCHLEVEL 2 @@ -15515,7 +15515,7 @@ which discusses this feature in more detail and gives an example. @cindex extensions, common@comma{} @code{fflush()} function Flush any buffered output associated with @var{filename}, which is either a file opened for writing or a shell command for redirecting output to -a pipe or coprocess. @value{COMMONEXT}. +a pipe or coprocess. @cindex portability, @code{fflush()} function and @cindex buffers, flushing @@ -15532,23 +15532,35 @@ buffers its output and the @code{fflush()} function forces @command{gawk} to flush its buffers. @code{fflush()} was added to Brian Kernighan's -version of @command{awk} in 1994; it is not part of the POSIX standard and is -not available if @option{--posix} has been specified on the -command line (@pxref{Options}). - -@cindex @command{gawk}, @code{fflush()} function in -@command{gawk} extends the @code{fflush()} function in two ways. The first -is to allow no argument at all. In this case, the buffer for the -standard output is flushed. The second is to allow the null string -(@w{@code{""}}) as the argument. In this case, the buffers for -@emph{all} open output files and pipes are flushed. -Brian Kernighan's @command{awk} also supports these extensions. +version of @command{awk} in 1994. +For over two decades, it was not part of the POSIX standard. +As of December, 2012, it was accepted for +inclusion into the POSIX standard. +See @uref{http://austingroupbugs.net/view.php?id=634, the Austin Group website}. + +POSIX standardizes @code{fflush()} as follows: If there +is no argument, or if the argument is the null string (@w{@code{""}}), +then @command{awk} flushes the buffers for @emph{all} open output files +and pipes. + +@quotation NOTE +Prior to version 4.0.2, @command{gawk} +would flush only the standard output if there was no argument, +and flush all output files and pipes if the argument was the null +string. This was changed in order to be compatible with Brian +Kernighan's @command{awk}, in the hope that standardizing this +feature in POSIX would then be easier (which indeed helped). + +With @command{gawk}, +you can use @samp{fflush("/dev/stdout")} if you wish to flush +only the standard output. +@end quotation @c @cindex automatic warnings @c @cindex warnings, automatic @cindex troubleshooting, @code{fflush()} function @code{fflush()} returns zero if the buffer is successfully flushed; -otherwise, it returns @minus{}1. +otherwise, it returns non-zero (@command{gawk} returns @minus{}1). In the case where all buffers are flushed, the return value is zero only if all buffers were flushed successfully. Otherwise, it is @minus{}1, and @command{gawk} warns about the problem @var{filename}. @@ -15656,7 +15668,7 @@ it is all buffered and sent down the pipe to @command{cat} in one shot. @cindex output, buffering The @code{fflush()} function provides explicit control over output buffering for -individual files and pipes. However, its use is not portable to many other +individual files and pipes. However, its use is not portable to many older @command{awk} implementations. An alternative method to flush output buffers is to call @code{system()} with a null string as its argument: @@ -26753,6 +26765,7 @@ The use of @code{func} as an abbreviation for @code{function} @item The @code{fflush()} built-in function for flushing buffered output (@pxref{I/O Functions}). +As of December 2012, this function is now standardized by POSIX. @ignore @item @@ -27068,7 +27081,6 @@ the three most widely-used freely available versions of @command{awk} @item @code{nextfile} statement @tab X @tab X @tab X @item @code{delete} without subscript @tab X @tab X @tab X @item @code{length()} of an array @tab X @tab @tab X -@item @code{fflush()} function @tab X @tab X @tab X @item @code{BINMODE} variable @tab @tab X @tab X @end multitable |