1% File src/library/base/man/showConnections.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2018 R Core Team
4% Distributed under GPL 2 or later
5
6\name{showConnections}
7\alias{showConnections}
8\alias{getConnection}
9\alias{getAllConnections}
10\alias{closeAllConnections}
11\alias{stdin}
12\alias{stdout}
13\alias{stderr}
14\alias{nullfile}
15\alias{isatty}
16\title{Display Connections}
17\description{
18  Display aspects of \link{connections}.
19}
20\usage{
21showConnections(all = FALSE)
22getConnection(what)
23closeAllConnections()
24
25stdin()
26stdout()
27stderr()
28nullfile()
29
30isatty(con)
31}
32\arguments{
33  \item{all}{logical: if true all connections, including closed ones
34    and the standard ones are displayed.  If false only open user-created
35    connections are included.}
36
37  \item{what}{integer: a row number of the table given by
38    \code{showConnections}.}
39
40  \item{con}{a connection.}
41}
42\details{
43  \code{stdin()}, \code{stdout()} and \code{stderr()} are standard
44  connections corresponding to input, output and error on the console
45  respectively (and not necessarily to file streams).  They are text-mode
46  connections of class \code{"terminal"} which cannot be opened or
47  closed, and are read-only, write-only and write-only respectively.
48  The \code{stdout()} and \code{stderr()} connections can be
49  re-directed by \code{\link{sink}} (and in some circumstances the
50  output from \code{stdout()} can be split: see the help page).
51
52  The encoding for \code{\link{stdin}()} when redirected can
53  be set by the command-line flag \option{--encoding}.
54
55  \code{nullfile()} returns filename of the null device (\code{"/dev/null"}
56  on Unix, \code{"nul:"} on Windows).
57
58  \code{showConnections} returns a matrix of information.  If a
59  connection object has been lost or forgotten, \code{getConnection}
60  will take a row number from the table and return a connection object
61  for that connection, which can be used to close the connection,
62  for example.  However, if there is no \R level object referring to the
63  connection it will be closed automatically at the next garbage
64  collection (except for \code{\link{gzcon}} connections).
65
66  \code{closeAllConnections} closes (and destroys) all user
67  connections, restoring all \code{\link{sink}} diversions as it does
68  so.
69
70  \code{isatty} returns true if the connection is one of the class
71  \code{"terminal"} connections and it is apparently connected to a
72  terminal, otherwise false.  This may not be reliable in embedded
73  applications, including GUI consoles.
74}
75\note{
76  \code{stdin()} refers to the \sQuote{console} and not to the C-level
77  \file{stdin} of the process.  The distinction matters in GUI consoles
78  (which may not have an active \file{stdin}, and if they do it may not
79  be connected to console input), and also in embedded applications.
80  If you want access to the C-level file stream \file{stdin}, use
81  \code{\link{file}("stdin")}.
82
83  When \R is reading a script from a file, the \emph{file} is the
84  \sQuote{console}: this is traditional usage to allow in-line data (see
85  \sQuote{An Introduction to R} for an example).
86}
87\value{
88  \code{stdin()}, \code{stdout()} and \code{stderr()} return connection
89  objects.
90
91  \code{showConnections} returns a character matrix of information with
92  a row for each connection, by default only for open non-standard connections.
93
94  \code{getConnection} returns a connection object, or \code{NULL}.
95}
96\seealso{\code{\link{connections}}}
97
98\examples{
99showConnections(all = TRUE)
100\dontrun{
101textConnection(letters)
102# oops, I forgot to record that one
103showConnections()
104#  class     description      mode text   isopen   can read can write
105#3 "letters" "textConnection" "r"  "text" "opened" "yes"    "no"
106mycon <- getConnection(3)
107}
108
109c(isatty(stdin()), isatty(stdout()), isatty(stderr()))
110}
111\keyword{connection}
112