mirror of https://github.com/mkerrisk/man-pages
221 lines
7.6 KiB
Plaintext
221 lines
7.6 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "CLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" close
|
||
|
.SH NAME
|
||
|
close \- close a file descriptor
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <unistd.h>
|
||
|
.br
|
||
|
.sp
|
||
|
int close(int\fP \fIfildes\fP\fB);
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIclose\fP() function shall deallocate the file descriptor indicated
|
||
|
by \fIfildes\fP. To deallocate means to make the
|
||
|
file descriptor available for return by subsequent calls to \fIopen\fP()
|
||
|
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).
|
||
|
.LP
|
||
|
If \fIclose\fP() is interrupted by a signal that is to be caught,
|
||
|
it shall return -1 with \fIerrno\fP set to [EINTR] and the
|
||
|
state of \fIfildes\fP is unspecified. If an I/O error occurred while
|
||
|
reading from or writing to the file system during
|
||
|
\fIclose\fP(), it may return -1 with \fIerrno\fP set to [EIO]; if
|
||
|
this error is returned, the state of \fIfildes\fP is
|
||
|
unspecified.
|
||
|
.LP
|
||
|
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.
|
||
|
.LP
|
||
|
When all file descriptors associated with an open file description
|
||
|
have been closed, the open file description shall be
|
||
|
freed.
|
||
|
.LP
|
||
|
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.
|
||
|
.LP
|
||
|
If a STREAMS-based \fIfildes\fP 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\fP() for a STREAM shall cause the STREAM associated with
|
||
|
\fIfildes\fP 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\fP() 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\fP() request. If the O_NONBLOCK
|
||
|
flag is set, or if there
|
||
|
are any pending signals, \fIclose\fP() shall not wait for output to
|
||
|
drain, and shall dismantle the STREAM immediately.
|
||
|
.LP
|
||
|
If the implementation supports STREAMS-based pipes, and \fIfildes\fP
|
||
|
is associated with one end of a pipe, the last
|
||
|
\fIclose\fP() 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\fP(), then the last \fIclose\fP() shall force the named
|
||
|
end to be detached
|
||
|
by \fIfdetach\fP(). 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.
|
||
|
.LP
|
||
|
If \fIfildes\fP 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.
|
||
|
.LP
|
||
|
If \fIfildes\fP refers to the slave side of a STREAMS-based pseudo-terminal,
|
||
|
a zero-length message may be sent to the master.
|
||
|
.LP
|
||
|
When there is an outstanding cancelable asynchronous I/O operation
|
||
|
against \fIfildes\fP when \fIclose\fP() is called, that I/O
|
||
|
operation may be canceled. An I/O operation that is not canceled completes
|
||
|
as if the \fIclose\fP() operation had not yet occurred.
|
||
|
All operations that are not canceled shall complete as if the \fIclose\fP()
|
||
|
blocked until the operations completed. The
|
||
|
\fIclose\fP() 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\fP(), is implementation-defined.
|
||
|
.LP
|
||
|
If a shared memory object or a memory mapped file 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
|
||
|
shared memory object or a memory mapped file and the close results
|
||
|
in the memory object becoming unreferenced, and the memory
|
||
|
object has been unlinked, then the memory object shall be removed.
|
||
|
.LP
|
||
|
If \fIfildes\fP refers to a socket, \fIclose\fP() 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\fP() shall block for up to the current linger interval until
|
||
|
all data is transmitted.
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
Upon successful completion, 0 shall be returned; otherwise, -1 shall
|
||
|
be returned and \fIerrno\fP set to indicate the error.
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
The \fIclose\fP() function shall fail if:
|
||
|
.TP 7
|
||
|
.B EBADF
|
||
|
The \fIfildes\fP argument is not a valid file descriptor.
|
||
|
.TP 7
|
||
|
.B EINTR
|
||
|
The \fIclose\fP() function was interrupted by a signal.
|
||
|
.sp
|
||
|
.LP
|
||
|
The \fIclose\fP() function may fail if:
|
||
|
.TP 7
|
||
|
.B EIO
|
||
|
An I/O error occurred while reading from or writing to the file system.
|
||
|
.sp
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.SS Reassigning a File Descriptor
|
||
|
.LP
|
||
|
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
|
||
|
.nf
|
||
|
|
||
|
\fB#include <unistd.h>
|
||
|
\&...
|
||
|
int pfd;
|
||
|
\&...
|
||
|
close(1);
|
||
|
dup(pfd);
|
||
|
close(pfd);
|
||
|
\&...
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
Incidentally, this is exactly what could be achieved using:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBdup2(pfd, 1);
|
||
|
close(pfd);
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.SS Closing a File Descriptor
|
||
|
.LP
|
||
|
In the following example, \fIclose\fP() is used to close a file descriptor
|
||
|
after an unsuccessful attempt is made to associate
|
||
|
that file descriptor with a stream.
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB#include <stdio.h>
|
||
|
#include <unistd.h>
|
||
|
#include <stdlib.h>
|
||
|
.sp
|
||
|
|
||
|
#define LOCKFILE "/etc/ptmp"
|
||
|
\&...
|
||
|
int pfd;
|
||
|
FILE *fpfd;
|
||
|
\&...
|
||
|
if ((fpfd = fdopen (pfd, "w")) == NULL) {
|
||
|
close(pfd);
|
||
|
unlink(LOCKFILE);
|
||
|
exit(1);
|
||
|
}
|
||
|
\&...
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
An application that had used the \fIstdio\fP routine \fIfopen\fP()
|
||
|
to open a file should
|
||
|
use the corresponding \fIfclose\fP() routine rather than \fIclose\fP().
|
||
|
Once a file is
|
||
|
closed, the file descriptor no longer exists, since the integer corresponding
|
||
|
to it no longer refers to a file.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
The use of interruptible device close routines should be discouraged
|
||
|
to avoid problems with the implicit closes of file
|
||
|
descriptors by \fIexec\fP and \fIexit\fP(). This volume
|
||
|
of IEEE\ Std\ 1003.1-2001 only intends to permit such behavior by
|
||
|
specifying the [EINTR] error condition.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fISTREAMS\fP , \fIfattach\fP() , \fIfclose\fP() , \fIfdetach\fP()
|
||
|
, \fIfopen\fP() , \fIioctl\fP() , \fIopen\fP() , the Base Definitions
|
||
|
volume of
|
||
|
IEEE\ Std\ 1003.1-2001, \fI<unistd.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 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 .
|