diff options
Diffstat (limited to 'upstream/archlinux/man3p/close.3p')
| -rw-r--r-- | upstream/archlinux/man3p/close.3p | 356 |
1 files changed, 356 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/close.3p b/upstream/archlinux/man3p/close.3p new file mode 100644 index 00000000..8c880ec0 --- /dev/null +++ b/upstream/archlinux/man3p/close.3p @@ -0,0 +1,356 @@ +'\" et +.TH CLOSE "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 +close +\(em close a file descriptor +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> +.P +int close(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIclose\fR() +function shall deallocate the file descriptor indicated by +.IR fildes . +To deallocate means to make the file descriptor available for return by +subsequent calls to +\fIopen\fR() +or other functions that allocate file descriptors. All outstanding +record locks owned by the process on the file associated with the file +descriptor shall be removed (that is, unlocked). +.P +If +\fIclose\fR() +is interrupted by a signal that is to be caught, it shall return +\-1 with +.IR errno +set to +.BR [EINTR] +and the state of +.IR fildes +is unspecified. If an I/O error occurred while reading from or writing +to the file system during +\fIclose\fR(), +it may return \-1 with +.IR errno +set to +.BR [EIO] ; +if this error is returned, the state of +.IR fildes +is unspecified. +.P +When all file descriptors associated with a pipe or FIFO special file +are closed, any data remaining in the pipe or FIFO shall be discarded. +.P +When all file descriptors associated with an open file description have +been closed, the open file description shall be freed. +.P +If the link count of the file is 0, when all file descriptors +associated with the file are closed, the space occupied by the file +shall be freed and the file shall no longer be accessible. +.P +If a STREAMS-based +.IR fildes +is closed and the calling process was previously registered to receive +a SIGPOLL signal +for events associated with that STREAM, the calling process shall be +unregistered for events associated with the STREAM. The last +\fIclose\fR() +for a STREAM shall cause the STREAM associated with +.IR fildes +to be dismantled. If O_NONBLOCK is not set and there have been no +signals posted for the STREAM, +and if there is data on the module's write queue, +\fIclose\fR() +shall wait for an unspecified time (for each module and driver) for +any output to drain before dismantling the STREAM. The time delay +can be changed via an I_SETCLTIME +\fIioctl\fR() +request. If the O_NONBLOCK flag is set, or if there are any pending +signals, +\fIclose\fR() +shall not wait for output to drain, and shall dismantle the STREAM +immediately. +.P +If the implementation supports STREAMS-based pipes, and +.IR fildes +is associated with one end of a pipe, the last +\fIclose\fR() +shall cause a hangup to occur on the other end of the pipe. In +addition, if the other end of the pipe has been named by +\fIfattach\fR(), +then the last +\fIclose\fR() +shall force the named end to be detached by +\fIfdetach\fR(). +If the named end has no open file descriptors associated with it and +gets detached, the STREAM associated with that end shall also be +dismantled. +.P +If +.IR fildes +refers to the master side of a pseudo-terminal, and this is the last +close, a SIGHUP signal shall be sent to the +controlling process, if any, for which the slave side of the +pseudo-terminal is the controlling terminal. It is unspecified whether +closing the master side of the pseudo-terminal flushes all queued input +and output. +.P +If +.IR fildes +refers to the slave side of a STREAMS-based pseudo-terminal, a +zero-length message may be sent to the master. +.P +When there is an outstanding cancelable asynchronous I/O operation +against +.IR fildes +when +\fIclose\fR() +is called, that I/O operation may be canceled. An I/O operation that +is not canceled completes as if the +\fIclose\fR() +operation had not yet occurred. All operations that are not canceled +shall complete as if the +\fIclose\fR() +blocked until the operations completed. The +\fIclose\fR() +operation itself need not block awaiting such I/O completion. Whether +any I/O operation is canceled, and which I/O operation may be +canceled upon +\fIclose\fR(), +is implementation-defined. +.P +If a memory mapped file +or a shared memory object +remains referenced at the last close (that is, a process has +it mapped), then the entire contents of the memory object shall +persist until the memory object becomes unreferenced. +If this is the last close of a memory mapped file +or a shared memory object +and the close results in the memory object becoming unreferenced, +and the memory object has been unlinked, then the memory object +shall be removed. +.P +If +.IR fildes +refers to a socket, +\fIclose\fR() +shall cause the socket to be destroyed. If the socket is in +connection-mode, and the SO_LINGER option is set for the socket with +non-zero linger time, and the socket has untransmitted data, then +\fIclose\fR() +shall block for up to the current linger interval until all data is +transmitted. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIclose\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a open file descriptor. +.TP +.BR EINTR +The +\fIclose\fR() +function was interrupted by a signal. +.P +The +\fIclose\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reassigning a File Descriptor" +.P +The following example closes the file descriptor associated with +standard output for the current process, re-assigns standard output to +a new file descriptor, and closes the original file descriptor to clean +up. This example assumes that the file descriptor 0 (which is the +descriptor for standard input) is not closed. +.sp +.RS 4 +.nf + +#include <unistd.h> +\&... +int pfd; +\&... +close(1); +dup(pfd); +close(pfd); +\&... +.fi +.P +.RE +.P +Incidentally, this is exactly what could be achieved using: +.sp +.RS 4 +.nf + +dup2(pfd, 1); +close(pfd); +.fi +.P +.RE +.SS "Closing a File Descriptor" +.P +In the following example, +\fIclose\fR() +is used to close +a file descriptor after an unsuccessful attempt is made to associate that +file descriptor with a stream. +.sp +.RS 4 +.nf + +#include <stdio.h> +#include <unistd.h> +#include <stdlib.h> +.P +#define LOCKFILE "/etc/ptmp" +\&... +int pfd; +FILE *fpfd; +\&... +if ((fpfd = fdopen (pfd, "w")) == NULL) { + close(pfd); + unlink(LOCKFILE); + exit(1); +} +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +An application that had used the +.IR stdio +routine +\fIfopen\fR() +to open a file should use the corresponding +\fIfclose\fR() +routine rather than +\fIclose\fR(). +Once a file is closed, the file descriptor no longer exists, since the +integer corresponding to it no longer refers to a file. +.P +Implementations may use file descriptors that must be inherited into +child processes for the child process to remain conforming, such as for +message catalog or tracing purposes. Therefore, an application that calls +\fIclose\fR() +on an arbitrary integer risks non-conforming behavior, and +\fIclose\fR() +can only portably be used on file descriptor values that the application +has obtained through explicit actions, as well as the three file +descriptors corresponding to the standard file streams. In multi-threaded +parent applications, the practice of calling +\fIclose\fR() +in a loop after +\fIfork\fR() +and before an +.IR exec +call in order to avoid a race condition of leaking an unintended file +descriptor into a child process, is therefore unsafe, and the race should +instead be combatted by opening all file descriptors with the FD_CLOEXEC +bit set unless the file descriptor is intended to be inherited across +.IR exec . +.P +Usage of +\fIclose\fR() +on file descriptors STDIN_FILENO, STDOUT_FILENO, or STDERR_FILENO +should immediately be followed by an operation to reopen these file +descriptors. Unexpected behavior will result if any of these file +descriptors is left in a closed state (for example, an +.BR [EBADF] +error from +\fIperror\fR()) +or if an unrelated +\fIopen\fR() +or similar call later in the application accidentally allocates +a file to one of these well-known file descriptors. Furthermore, a +\fIclose\fR() +followed by a reopen operation (e.g., +\fIopen\fR(), +\fIdup\fR(), +etc.) is not atomic; +\fIdup2\fR() +should be used to change standard file descriptors. +.SH RATIONALE +The use of interruptible device close routines should be discouraged to +avoid problems with the implicit closes of file descriptors by +.IR exec +and +\fIexit\fR(). +This volume of POSIX.1\(hy2017 only intends to permit such behavior by specifying the +.BR [EINTR] +error condition. +.P +Note that the requirement for +\fIclose\fR() +on a socket to block for up to the current linger interval is not +conditional on the O_NONBLOCK setting. +.P +The standard developers rejected a proposal to add +\fIclosefrom\fR() +to the standard. Because the standard permits implementations to +use inherited file descriptors as a means of providing a conforming +environment for the child process, it is not possible to standardize an +interface that closes arbitrary file descriptors above a certain value +while still guaranteeing a conforming environment. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfattach\fR\^(\|)", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdetach\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIioctl\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIperror\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<unistd.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 . |