14249 pseudo-terminal nomenclature should reflect POSIX
Change-Id: Ib4a3cef899ff4c71b09cb0dc6878863c5e8357bc

*** 41,251 ****
  .\"
  .\"
  .\" Copyright 1989 AT&T
  .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
  .\"
! .TH CLOSE 2 "Oct 18, 2005"
! .SH NAME
! close \- close a file descriptor
! .SH SYNOPSIS
! .LP
! .nf
! #include <unistd.h>
! 
! \fBint\fR \fBclose\fR(\fBint\fR \fIfildes\fR);
! .fi
! 
! .SH DESCRIPTION
! .sp
! .LP
! The \fBclose()\fR function deallocates the file descriptor indicated by
! \fIfildes\fR. To deallocate means to make the file descriptor available for
! return by subsequent calls to \fBopen\fR(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).
! .sp
! .LP
! If \fBclose()\fR is interrupted by a signal that is to be caught, it will
! return \fB\(mi1\fR with \fBerrno\fR set to \fBEINTR\fR and the state of
! \fIfildes\fR is unspecified. If an I/O error occurred while reading from or
! writing to the file system during \fBclose()\fR, it returns -1, sets
! \fBerrno\fR to \fBEIO\fR, and the state of \fIfildes\fR is unspecified.
! .sp
! .LP
! When all file descriptors associated with a pipe or \fBFIFO\fR special file are
! closed, any data remaining in the pipe or \fBFIFO\fR will be discarded.
! .sp
! .LP
  When all file descriptors associated with an open file description have been
  closed the open file description will be freed.
! .sp
! .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 will be freed and the file
! will no longer be accessible.
! .sp
! .LP
! If a streams-based (see \fBIntro\fR(2)) \fIfildes\fR is closed and the calling
! process was previously registered to receive a \fBSIGPOLL\fR signal (see
! \fBsignal\fR(3C)) for events associated with that stream (see \fBI_SETSIG\fR in
! \fBstreamio\fR(7I)), the calling process will be unregistered for events
! associated with the stream.  The last \fBclose()\fR for a stream causes the
! stream associated with \fIfildes\fR to be dismantled. If \fBO_NONBLOCK\fR and
! \fBO_NDELAY\fR are not set and there have been no signals posted for the
! stream, and if there is data on the module's write queue, \fBclose()\fR 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 \fBI_SETCLTIME\fR
! \fBioctl\fR(2) request (see \fBstreamio\fR(7I)). If the \fBO_NONBLOCK\fR or
! \fBO_NDELAY\fR flag is set, or if there are any pending signals, \fBclose()\fR
  does not wait for output to drain, and dismantles the stream immediately.
! .sp
! .LP
! If \fIfildes\fR is associated with one end of a pipe, the last \fBclose()\fR
! 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 \fBfattach\fR(3C), then the last
! \fBclose()\fR forces the named end to be detached by \fBfdetach\fR(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.
! .sp
! .LP
! If \fIfildes\fR refers to the master side of a pseudo-terminal, a \fBSIGHUP\fR
! signal is sent to the session leader, 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.
! .sp
! .LP
! If \fIfildes\fR refers to the slave side of a streams-based pseudo-terminal, a
! zero-length message may be sent to the master.
! .sp
! .LP
  When there is an outstanding cancelable asynchronous I/O operation against
! \fIfildes\fR when \fBclose()\fR is called, that I/O operation is canceled. An
! I/O operation that is not canceled completes as if the \fBclose()\fR operation
! had not yet occurred. All operations that are not canceled will complete as if
! the \fBclose()\fR blocked until the operations completed.
! .sp
! .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 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.
! .sp
! .LP
! If \fIfildes\fR refers to a socket, \fBclose()\fR causes the socket to be
! destroyed.  If the socket is connection-mode, and the \fBSO_LINGER\fR option is
! set for the socket with non-zero linger time, and the socket has untransmitted
! data, then \fBclose()\fR will block for up to the current linger interval until
! all data is transmitted.
! .SH RETURN VALUES
! .sp
! .LP
! Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
! returned and \fBerrno\fR is set to indicate the error.
! .SH ERRORS
! .sp
! .LP
! The \fBclose()\fR function will fail if:
! .sp
! .ne 2
! .na
! \fB\fBEBADF\fR\fR
! .ad
! .RS 11n
! The \fIfildes\fR argument is not a valid file descriptor.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fBEINTR\fR\fR
! .ad
! .RS 11n
! The \fBclose()\fR function was interrupted by a signal.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fBENOLINK\fR\fR
! .ad
! .RS 11n
! The \fIfildes\fR argument is on a remote machine and the link to that machine
! is no longer active.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fBENOSPC\fR\fR
! .ad
! .RS 11n
! There was no free space remaining on the device containing the file.
! .RE
! 
! .sp
! .LP
! The \fBclose()\fR function may fail if:
! .sp
! .ne 2
! .na
! \fB\fBEIO\fR\fR
! .ad
! .RS 7n
! An I/O error occurred while reading from or writing to the file system.
! .RE
! 
! .SH EXAMPLES
! .LP
! \fBExample 1 \fRReassign a file descriptor.
! .sp
! .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
! .in +2
! .nf
  #include <unistd.h>
  \&...
  int pfd;
  \&...
  close(1);
  dup(pfd);
  close(pfd);
  \&...
! .fi
! .in -2
! 
! .sp
! .LP
  Incidentally, this is exactly what could be achieved using:
! 
! .sp
! .in +2
! .nf
  dup2(pfd, 1);
  close(pfd);
! .fi
! .in -2
! 
! .LP
! \fBExample 2 \fRClose a file descriptor.
! .sp
! .LP
! In the following example, \fBclose()\fR is used to close a file descriptor
! after an unsuccessful attempt is made to associate that file descriptor with a
! stream.
! 
! .sp
! .in +2
! .nf
  #include <stdio.h>
  #include <unistd.h>
  #include <stdlib.h>
  
  #define LOCKFILE "/etc/ptmp"
--- 41,261 ----
  .\"
  .\"
  .\" 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 2022 Oxide Computer Company
  .\"
! .Dd February 5, 2022
! .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
! .Pq "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
! .Er 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
! .Er 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
! .Po
! see
! .Xr Intro 2
! .Pc
! .Fa fildes
! is closed and the calling process was previously registered to receive a
! .Dv SIGPOLL
! signal
! .Po
! see
! .Xr signal 3C
! .Pc
! for events associated with that stream
! .Po
! see
! .Dv I_SETSIG
! in
! .Xr streamio 7I
! .Pc ,
! 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
! 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
! .Pq 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
! .Po
! see
! .Xr streamio 7I
! .Pc .
! 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
! .Pq "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
! .Rv -std close
! .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"
*** 257,296 ****
          close(pfd);
          unlink(LOCKFILE);
          exit(1);
  }
  \&...
! .fi
! .in -2
! 
! .SH USAGE
! .sp
! .LP
! An application that used the \fBstdio\fR function \fBfopen\fR(3C) to open a
! file should use the corresponding \fBfclose\fR(3C) function rather than
! \fBclose()\fR.
! .SH ATTRIBUTES
! .sp
! .LP
! See \fBattributes\fR(5) for descriptions of the following attributes:
! .sp
! 
! .sp
! .TS
! box;
! c | c
! l | l .
! ATTRIBUTE TYPE  ATTRIBUTE VALUE
! _
! Interface Stability     Standard
! _
! MT-Level        Async-Signal-Safe
! .TE
! 
! .SH SEE ALSO
! .sp
! .LP
! \fBIntro\fR(2), \fBcreat\fR(2), \fBdup\fR(2), \fBexec\fR(2), \fBfcntl\fR(2),
! \fBioctl\fR(2), \fBopen\fR(2) \fBpipe\fR(2), \fBfattach\fR(3C),
! \fBfclose\fR(3C), \fBfdetach\fR(3C), \fBfopen\fR(3C), \fBsignal\fR(3C),
! \fBsignal.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5),
! \fBstreamio\fR(7I)
--- 267,332 ----
          close(pfd);
          unlink(LOCKFILE);
          exit(1);
  }
  \&...
! .Ed
! .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 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 creat 2 ,
! .Xr dup 2 ,
! .Xr exec 2 ,
! .Xr fcntl 2 ,
! .Xr Intro 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