diff options
Diffstat (limited to 'upstream/archlinux/man3p/fclose.3p')
| -rw-r--r-- | upstream/archlinux/man3p/fclose.3p | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/fclose.3p b/upstream/archlinux/man3p/fclose.3p new file mode 100644 index 00000000..1ea83b09 --- /dev/null +++ b/upstream/archlinux/man3p/fclose.3p @@ -0,0 +1,206 @@ +'\" et +.TH FCLOSE "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 +fclose +\(em close a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +.P +int fclose(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 +The +\fIfclose\fR() +function shall cause the stream pointed to by +.IR stream +to be flushed and the associated file to be closed. Any unwritten +buffered data for the stream shall be written to the file; any unread +buffered data shall be discarded. Whether or not the call succeeds, +the stream shall be disassociated from the file and any buffer set by +the +\fIsetbuf\fR() +or +\fIsetvbuf\fR() +function shall be disassociated from the stream. If the associated +buffer was automatically allocated, it shall be deallocated. +.P +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 if the stream is the active handle to +the underlying file description. +.P +The +\fIfclose\fR() +function shall mark for update the last data modification and last +file status change timestamps of the underlying file, if the stream was +writable, and if buffered data remains that has not yet been written to +the file. The +\fIfclose\fR() +function shall perform the equivalent of a +\fIclose\fR() +on the file descriptor that is associated with the stream pointed to by +.IR stream . +.P +After the call to +\fIfclose\fR(), +any use of +.IR stream +results in undefined behavior. +.SH "RETURN VALUE" +Upon successful completion, +\fIfclose\fR() +shall return 0; otherwise, it shall return EOF +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfclose\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 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 +\fIfclose\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 +\fIfclose\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 +None. +.SH "APPLICATION USAGE" +Since after the call to +\fIfclose\fR() +any use of +.IR stream +results in undefined behavior, +\fIfclose\fR() +should not be used on +.IR stdin , +.IR stdout , +or +.IR stderr +except immediately before process termination (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.303" ", " "Process Termination"), +so as to avoid triggering undefined behavior in other standard +interfaces that rely on these streams. If there are any +\fIatexit\fR() +handlers registered by the application, such a call to +\fIfclose\fR() +should not occur until the last handler is finishing. Once +\fIfclose\fR() +has been used to close +.IR stdin , +.IR stdout , +or +.IR stderr , +there is no standard way to reopen any of these streams. +.P +Use of +\fIfreopen\fR() +to change +.IR stdin , +.IR stdout , +or +.IR stderr +instead of closing them avoids the danger of a file unexpectedly +being opened as one of the special file descriptors STDIN_FILENO, +STDOUT_FILENO, or STDERR_FILENO at a later time in the application. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIatexit\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfreopen\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 . |