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