-tmp-close.2

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
.\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2021 Oxide Computer Company
.\"
.Dd November 18, 2021
.Dt CLOSE 2
.Os
.Sh NAME
.Nm close
.Nd close a file descriptor
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fo close
.Fa "int fildes"
.Fc
.Sh DESCRIPTION
The
.Fn close
function deallocates the file descriptor indicated by
.Fa fildes .
To deallocate means to make the file descriptor available for return by
subsequent calls to
.Xr open 2
or other functions that allocate file descriptors.
All outstanding record locks owned by the process on the file associated with
the file descriptor will be removed (that is, unlocked).
.Pp
If
.Fn close
is interrupted by a signal that is to be caught, it will return
.Sy -1
with
.Va errno
set to
.Dv EINTR
and the state of
.Fa fildes
is unspecified.
If an I/O error occurred while reading from or writing to the file system during
.Fn close ,
it returns
.Sy -1 ,
sets
.Va errno
to
.Dv EIO ,
and the state of
.Fa fildes
is unspecified.
.Pp
When all file descriptors associated with a pipe or FIFO special file are
closed, any data remaining in the pipe or FIFO will be discarded.
.Pp
When all file descriptors associated with an open file description have been
closed the open file description will be freed.
.Pp
If the link count of the file is
.Sy 0 ,
when all file descriptors associated with the file are closed, the space
occupied by the file will be freed and the file will no longer be accessible.
.Pp
If a streams-based (see
.Xr Intro 2 )
.Fa fildes
is closed and the calling process was previously registered to receive a
.Dv SIGPOLL
signal (see
.Xr signal 3C )
for events associated with that stream (see
.Dv I_SETSIG
in
.Xr streamio 7I ),
the calling process will be unregistered for events associated with the stream.
The last 
.Fn close
for a stream causes the stream associated with 
.Fa fildes
to be dismantled.
If
.Dv O_NONBLOCK\fR
and
.Dv O_NDELAY
are not set and there have been no signals posted for the stream, and if there
is data on the module's write queue,
.Fn close
waits up to 15 seconds (for each module and driver) for any output to drain
before dismantling the stream. The time delay can be changed via an
.Dv I_SETCLTIME
.Xr ioctl 2
request (see
.Xr streamio 7I ).
If the 
.Dv O_NONBLOCK
or
.Dv O_NDELAY
flag is set, or if there are any pending signals,
.Fn close
does not wait for output to drain, and dismantles the stream immediately.
.Pp
If
.Fa fildes
is associated with one end of a pipe, the last
.Fn close
causes a hangup to occur on the other end of the pipe.
In addition, if the other end of the pipe has been named by
.Xr fattach 3C ,
then the last
.Fn close
forces the named end to be detached by
.Xr fdetach 3C .
If the named end has no open file descriptors associated with it and gets
detached, the stream associated with that end is also dismantled.
.Pp
If
.Fa fildes
refers to the manager side of a pseudo-terminal, a
.Dv SIGHUP
signal is sent to the session leader, if any, for which the subsidiary side of
the pseudo-terminal is the controlling terminal.
It is unspecified whether closing the manager side of the pseudo-terminal
flushes all queued input and output.
.Pp
If
.Fa fildes
refers to the subsidiary side of a streams-based pseudo-terminal, a zero-length
message may be sent to the manager.
.Pp
When there is an outstanding cancelable asynchronous I/O operation against
.Fa fildes
when
.Fn close
is called, that I/O operation is canceled.
An I/O operation that is not canceled completes as if the
.Fn close
operation had not yet occurred.
All operations that are not canceled will complete as if the
.Fn close
blocked until the operations completed.
.Pp
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 will 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 will be removed.
.Pp
If
.Fa fildes
refers to a socket,
.Fn close
causes the socket to be destroyed.
If the socket is connection-mode, and the
.Dv SO_LINGER
option is set for the socket with non-zero linger time, and the socket has
untransmitted data, then
.Fn close
will block for up to the current linger interval until all data is transmitted.
.Sh RETURN VALUES
Upon successful completion,
.Sy 0
is returned.
Otherwise,
.Sy -1
is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn close
function will fail if:
.Bl -tag -width Er
.It Er EBADF
The
.Fa fildes
argument is not a valid file descriptor.
.It Er EINTR
The
.Fn close
function was interrupted by a signal.
.It Er ENOLINK
The
.Fa fildes
argument is on a remote machine and the link to that machine is no longer
active.
.It Er ENOSPC
There was no free space remaining on the device containing the file.
.El
.Pp
The
.Fn close
function may fail if:
.Bl -tag -width Er
.It Er EIO
An I/O error occurred while reading from or writing to the file system.
.El
.Sh EXAMPLES
.Sy Example 1
Reassign a file descriptor.
.Pp
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
.Sy 0 ,
which is the descriptor for standard input, is not closed.
.Bd -literal -offset Ds
#include <unistd.h>
\&...
int pfd;
\&...
close(1);
dup(pfd);
close(pfd);
\&...
.Ed
.Pp
Incidentally, this is exactly what could be achieved using:
.Bd -literal -offset Ds
dup2(pfd, 1);
close(pfd);
.Ed
.Pp
.Sy Example 2
Close a file descriptor.
.Pp
In the following example,
.Fn close
is used to close a file descriptor after an unsuccessful attempt is made to
associate that file descriptor with a stream.
.Bd -literal -offset Ds
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>

#define LOCKFILE "/etc/ptmp"
\&...
int pfd;
FILE *fpfd;
\&...
if ((fpfd = fdopen (pfd, "w")) == NULL) {
        close(pfd);
        unlink(LOCKFILE);
        exit(1);
}
\&...
.Ed
.Sh USAGE
An application that used the
.Xr stdio 3C
function
.Xr fopen 3C
to open a file should use the corresponding
.Xr fclose 3C
function rather than
.Fn close .
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy Async-Signal-Safe
.Sh SEE ALSO
.Xr Intro 2 ,
.Xr creat 2 ,
.Xr dup 2 ,
.Xr exec 2 ,
.Xr fcntl 2 ,
.Xr ioctl 2 ,
.Xr open 2 ,
.Xr pipe 2 ,
.Xr fattach 3C ,
.Xr fclose 3C ,
.Xr fdetach 3C ,
.Xr fopen 3C ,
.Xr signal 3C ,
.Xr signal.h 3HEAD ,
.Xr attributes 5 ,
.Xr standards 5 ,
.Xr streamio 7I