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

@@ -41,211 +41,221 @@
 .\"
 .\"
 .\" 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
 .\"
-.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
+.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.
-.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
+.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.
-.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
+.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
-\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
+.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
+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.
-.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
+.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 0, which is the descriptor for standard input,
-is not closed.
-
-.sp
-.in +2
-.nf
+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);
 \&...
-.fi
-.in -2
-
-.sp
-.LP
+.Ed
+.Pp
 Incidentally, this is exactly what could be achieved using:
-
-.sp
-.in +2
-.nf
+.Bd -literal -offset Ds
 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
+.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,40 +267,66 @@
         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)
+.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