fflush.3p (6212B)
- '\" et
- .TH FFLUSH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- fflush
- \(em flush a stream
- .SH SYNOPSIS
- .LP
- .nf
- #include <stdio.h>
- .P
- int fflush(FILE *\fIstream\fP);
- .fi
- .SH DESCRIPTION
- The functionality described on this reference page is aligned with the
- ISO\ C standard. Any conflict between the requirements described here and the
- ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
- .P
- If
- .IR stream
- points to an output stream or an update stream in which the most recent
- operation was not input,
- \fIfflush\fR()
- shall cause any unwritten data for that stream to be written to the
- file,
- and the last data modification and last file status change timestamps
- of the underlying file shall be marked for update.
- .P
- For a stream open for reading with an underlying file description,
- if the file is not already at EOF, and the file is one capable
- of seeking, the file offset of the underlying open file description
- shall be set to the file position of the stream, and any characters
- pushed back onto the stream by
- \fIungetc\fR()
- or
- \fIungetwc\fR()
- that have not subsequently been read from the stream shall be discarded
- (without further changing the file offset).
- .P
- If
- .IR stream
- is a null pointer,
- \fIfflush\fR()
- shall perform this flushing action on all streams for which the
- behavior is defined above.
- .SH "RETURN VALUE"
- Upon successful completion,
- \fIfflush\fR()
- shall return 0; otherwise, it shall set the error indicator for
- the stream, return EOF,
- and set
- .IR errno
- to indicate the error.
- .SH ERRORS
- The
- \fIfflush\fR()
- function shall fail if:
- .TP
- .BR EAGAIN
- The O_NONBLOCK flag is set for the file descriptor underlying
- .IR stream
- and the thread would be delayed in the write operation.
- .TP
- .BR EBADF
- The file descriptor underlying
- .IR stream
- is not valid.
- .TP
- .BR EFBIG
- An attempt was made to write a file that exceeds the maximum file size.
- .TP
- .BR EFBIG
- An attempt was made to write a file that exceeds the file size
- limit of the process.
- .TP
- .BR EFBIG
- The file is a regular file and an attempt was made to write at or
- beyond the offset maximum associated with the corresponding stream.
- .TP
- .BR EINTR
- The
- \fIfflush\fR()
- function was interrupted by a signal.
- .TP
- .BR EIO
- The process is a member of a background process group attempting to
- write to its controlling terminal, TOSTOP is set, the calling thread
- is not blocking SIGTTOU, the process is not ignoring SIGTTOU, and the
- process group of the process is orphaned.
- This error may also be returned under implementation-defined conditions.
- .TP
- .BR ENOMEM
- The underlying stream was created by
- \fIopen_memstream\fR()
- or
- \fIopen_wmemstream\fR()
- and insufficient memory is available.
- .TP
- .BR ENOSPC
- There was no free space remaining on the device containing the file or
- in the buffer used by the
- \fIfmemopen\fR()
- function.
- .TP
- .BR EPIPE
- An attempt is made to write to a pipe or FIFO that is not open for
- reading by any process. A SIGPIPE signal shall also be sent to the thread.
- .P
- The
- \fIfflush\fR()
- function may fail if:
- .TP
- .BR ENXIO
- A request was made of a nonexistent device, or the request was
- outside the capabilities of the device.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .SS "Sending Prompts to Standard Output"
- .P
- The following example uses
- \fIprintf\fR()
- calls to print a series of prompts for information the user must enter
- from standard input. The
- \fIfflush\fR()
- calls force the output to standard output. The
- \fIfflush\fR()
- function is used because standard output is usually buffered and the
- prompt may not immediately be printed on the output or terminal. The
- \fIgetline\fR()
- function calls read strings from standard input and place the
- results in variables, for use later in the program.
- .sp
- .RS 4
- .nf
- char *user;
- char *oldpasswd;
- char *newpasswd;
- ssize_t llen;
- size_t blen;
- struct termios term;
- tcflag_t saveflag;
- .P
- printf("User name: ");
- fflush(stdout);
- blen = 0;
- llen = getline(&user, &blen, stdin);
- user[llen-1] = 0;
- tcgetattr(fileno(stdin), &term);
- saveflag = term.c_lflag;
- term.c_lflag &= \(tiECHO;
- tcsetattr(fileno(stdin), TCSANOW, &term);
- printf("Old password: ");
- fflush(stdout);
- blen = 0;
- llen = getline(&oldpasswd, &blen, stdin);
- oldpasswd[llen-1] = 0;
- .P
- printf("\enNew password: ");
- fflush(stdout);
- blen = 0;
- llen = getline(&newpasswd, &blen, stdin);
- newpasswd[llen-1] = 0;
- term.c_lflag = saveflag;
- tcsetattr(fileno(stdin), TCSANOW, &term);
- free(user);
- free(oldpasswd);
- free(newpasswd);
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- Data buffered by the system may make determining the validity of the
- position of the current file descriptor impractical. Thus, enforcing
- the repositioning of the file descriptor after
- \fIfflush\fR()
- on streams open for
- \fIread\fR()
- is not mandated by POSIX.1\(hy2008.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Section 2.5" ", " "Standard I/O Streams",
- .IR "\fIfmemopen\fR\^(\|)",
- .IR "\fIgetrlimit\fR\^(\|)",
- .IR "\fIopen_memstream\fR\^(\|)",
- .IR "\fIulimit\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<stdio.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .