diff options
Diffstat (limited to 'upstream/archlinux/man3p/fflush.3p')
| -rw-r--r-- | upstream/archlinux/man3p/fflush.3p | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/fflush.3p b/upstream/archlinux/man3p/fflush.3p new file mode 100644 index 00000000..1e680daa --- /dev/null +++ b/upstream/archlinux/man3p/fflush.3p @@ -0,0 +1,217 @@ +'\" 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 . |