\HeaderA{showConnections}{Display Connections}{showConnections}
\aliasA{closeAllConnections}{showConnections}{closeAllConnections}
\aliasA{getAllConnections}{showConnections}{getAllConnections}
\aliasA{getConnection}{showConnections}{getConnection}
\aliasA{stderr}{showConnections}{stderr}
\aliasA{stdin}{showConnections}{stdin}
\aliasA{stdout}{showConnections}{stdout}
\keyword{connection}{showConnections}
\begin{Description}\relax
Display aspects of connections.
\end{Description}
\begin{Usage}
\begin{verbatim}
showConnections(all = FALSE)
getConnection(what)
closeAllConnections()

stdin()
stdout()
stderr()
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{all}] logical: if true all connections, including closed ones
and the standard ones are displayed.  If false only open user-created
connections are included.
\item[\code{what}] integer: a row number of the table given by
\code{showConnections}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{stdin()}, \code{stdout()} and \code{stderr()} are standard
connections corresponding to input, output and error on the console
respectively (and not necessarily to file streams).  They are text-mode
connections of class \code{"terminal"} which cannot be opened or
closed, and are read-only, write-only and write-only respectively.
The \code{stdout()} and \code{stderr()} connections can be
re-directed by \code{\LinkA{sink}{sink}} (and in some circumstances the
output from \code{stdout()} can be split: see the help page).

The encoding for \code{\LinkA{stdin}{stdin}()} when redirected can
be set by the command-line flag \code{--encoding}.

\code{showConnections} returns a matrix of information.  If a
connection object has been lost or forgotten, \code{getConnection}
will take a row number from the table and return a connection object
for that connection, which can be used to close the connection,
for example.  However, if there is no \R{} level object referring to the
connection it will be closed automatically at the next garbage
collection.

\code{closeAllConnections} closes (and destroys) all user
connections, restoring all \code{\LinkA{sink}{sink}} diversions as it does so.
\end{Details}
\begin{Value}
\code{stdin()}, \code{stdout()} and \code{stderr()} return connection
objects.

\code{showConnections} returns a character matrix of information with
a row for each connection, by default only for open non-standard connections.

\code{getConnection} returns a connection object, or \code{NULL}.
\end{Value}
\begin{Note}\relax
\code{stdin()} refers to the \sQuote{console} and not to the C-level
\file{stdin} of the process.  The distinction matters in GUI consoles
(which may not have an active \file{stdin}, and if they do it may not
be connected to console input), and also in embedded applications.
If you want access to the C-level file stream \file{stdin}, use
\code{\LinkA{file}{file}("stdin")}.

When \R{} is reading a script from a file, the \emph{file} is the
\sQuote{console}: this is traditional usage to allow in-line data (see
\sQuote{An Introduction to R} for an example).
\end{Note}
\begin{SeeAlso}\relax
\code{\LinkA{connections}{connections}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
showConnections(all = TRUE)

textConnection(letters)
# oops, I forgot to record that one
showConnections()
#  class     description      mode text   isopen   can read can write
#3 "letters" "textConnection" "r"  "text" "opened" "yes"    "no"     
## Not run: close(getConnection(3))

showConnections()
\end{ExampleCode}
\end{Examples}

