close.3p (10509B)
- '\" 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 .