Connections and the File System

path <- tempfile(fileext = ".txt")
writeLines(c("alpha", "beta", "gamma"), path)

# Close in on.exit(): the connection is released even when the body fails.
first_line <- function(path) {
  con <- file(path, "r")
  on.exit(close(con))
  readLines(con, n = 1)
}
first_line(path)
#> [1] "alpha"

failing <- function(path) {
  con <- file(path, "r")
  on.exit(close(con))
  stop("could not parse the file")
}
tryCatch(failing(path), error = \(e) conditionMessage(e))
#> [1] "could not parse the file"
nrow(showConnections())
#> [1] 0

# Several resources: add = TRUE keeps the earlier handlers.
copy_lines <- function(from, to) {
  input <- file(from, "r")
  on.exit(close(input), add = TRUE)
  output <- file(to, "w")
  on.exit(close(output), add = TRUE)
  writeLines(toupper(readLines(input)), output)
}
target <- tempfile(fileext = ".txt")
copy_lines(path, target)
readLines(target)
#> [1] "ALPHA" "BETA"  "GAMMA"
nrow(showConnections())
#> [1] 0

# Forgetting to close: the connection stays open until it is garbage
# collected, and the R object is the only thing that keeps it alive.
leaked <- file(path, "r")
readLines(leaked, n = 1)
#> [1] "alpha"
showConnections()[, c("class", "mode", "isopen"), drop = FALSE]
#>   class  mode isopen
#> 3 "file" "r"  "opened"

# Once the last reference is gone, gc() closes it and warns. The warning text
# names the file, so it is captured through a message sink here and the path
# is replaced.
rm(leaked)
captured <- character()
sink_con <- textConnection("captured", "w")
sink(sink_con, type = "message")
invisible(gc())
sink(type = "message")
close(sink_con)
sub("\\([^()]*\\)$", "(<path>)", captured)
#> [1] "Warning in .Internal(gc(verbose, reset, full)) :"
#> [2] "  closing unused connection 3 (<path>)"
nrow(showConnections())
#> [1] 0

# A connection is also reachable by its number, as in showConnections().
con <- file(path, "r")
id <- as.integer(con)
id
#> [1] 3
same <- getConnection(id)
readLines(same, n = 1)
#> [1] "alpha"
close(con)
tryCatch(getConnection(77), error = \(e) conditionMessage(e))
#> [1] "there is no connection 77"

# closeAllConnections() closes every user connection, whoever opened it.
a <- file(path, "r")
b <- file(target, "r")
nrow(showConnections())
#> [1] 2
closeAllConnections()
nrow(showConnections())
#> [1] 0
tryCatch(isOpen(a), error = \(e) conditionMessage(e))
#> [1] "invalid connection"
showConnections(all = TRUE)[, c("class", "description")]
#>   class      description
#> 0 "terminal" "stdin"
#> 1 "terminal" "stdout"
#> 2 "terminal" "stderr"

closing unused connection 3 (<path>)

# The same text through the four compressed connection types.
lines <- rep(readLines("books.csv"), 100)
plain_bytes <- sum(nchar(lines, type = "bytes") + 1L)
writers <- list(gzip = gzfile, bzip2 = bzfile, xz = xzfile, zstd = zstdfile)
compressed_bytes <- vapply(writers, \(open_fn) {
  path <- tempfile()
  on.exit(unlink(path))
  con <- open_fn(path, "w")
  writeLines(lines, con)
  close(con)
  file.size(path)
}, numeric(1))
compressed_bytes < plain_bytes
#>  gzip bzip2    xz  zstd
#>  TRUE  TRUE  TRUE  TRUE

# Reading detects the compression from the first bytes of the file.
path <- tempfile(fileext = ".gz")
con <- gzfile(path, "w")
writeLines(c("alpha", "beta"), con)
close(con)
readLines(path)
#> [1] "alpha" "beta"
readBin(path, "raw", n = 2)
#> [1] 1f 8b

# "rb" gives the compressed bytes themselves; gzfile() reads any mode.
con <- file(path, "rb")
readBin(con, "raw", n = 2)
#> [1] 1f 8b
close(con)
con <- gzfile(path)
readLines(con)
#> [1] "alpha" "beta"
close(con)

# Append mode adds a second compressed stream, which R reads as one file.
con <- gzfile(path, "a")
writeLines("gamma", con)
close(con)
readLines(path)
#> [1] "alpha" "beta"  "gamma"

# gzcon() adds gzip decompression to an existing binary connection.
raw_con <- file(path, "rb")
gz <- gzcon(raw_con)
readLines(gz)
#> [1] "alpha" "beta"  "gamma"
class(gz)
#> [1] "gzcon"      "connection"
close(gz)

# Input: a character vector read as if it were a file.
csv_text <- c("title,pages", "Orchard Logic,210", "Rivers of Glass,310")
tc <- textConnection(csv_text)
read.csv(tc)
#>             title pages
#> 1   Orchard Logic   210
#> 2 Rivers of Glass   310
close(tc)
read.csv(text = csv_text)
#>             title pages
#> 1   Orchard Logic   210
#> 2 Rivers of Glass   310

# Output: complete lines are in the vector at all times; the last, unfinished
# line appears when the connection is closed.
tc <- textConnection("report", "w")
writeLines(c("Loans per member", "Ana Ruiz: 7"), tc)
cat("partial line", file = tc)
isIncomplete(tc)
#> [1] TRUE
report
#> [1] "Loans per member" "Ana Ruiz: 7"
close(tc)
report
#> [1] "Loans per member" "Ana Ruiz: 7"      "partial line"

# With a NULL name nothing is created; textConnectionValue() reads the lines.
tc <- textConnection(NULL, "w")
writeLines(c("one", "two"), tc)
textConnectionValue(tc)
#> [1] "one" "two"
close(tc)

# local = TRUE creates the vector in the calling function, not the workspace.
collect <- function() {
  tc <- textConnection("collected", "w", local = TRUE)
  writeLines(c("a", "b"), tc)
  close(tc)
  collected # nolint: object_usage_linter.
}
collect()
#> [1] "a" "b"
exists("collected")
#> [1] FALSE

# capture.output() is built on an output text connection and sink().
capture.output(print(1:3), cat("done\n"))
#> [1] "[1] 1 2 3" "done"

# A raw connection is a file in memory: write binary data, take the bytes.
rc <- rawConnection(raw(0), "wb")
writeBin(c(1L, 2L, 3L), rc)
writeBin("shelf", rc)
bytes <- rawConnectionValue(rc)
close(rc)
bytes
#>  [1] 01 00 00 00 02 00 00 00 03 00 00 00 73 68 65 6c 66 00
length(bytes)
#> [1] 18

# Read the bytes back through another raw connection.
rc <- rawConnection(bytes, "rb")
readBin(rc, "integer", n = 3)
#> [1] 1 2 3
readBin(rc, "character", n = 1)
#> [1] "shelf"
close(rc)

# In text mode a raw vector can be read line by line.
rc <- rawConnection(charToRaw("line one\nline two\n"))
readLines(rc)
#> [1] "line one" "line two"
close(rc)

capabilities(c("fifo", "sockets", "libcurl"))
#>    fifo sockets libcurl
#>    TRUE    TRUE    TRUE

# Reading from a pipe: the command runs in a shell when the connection opens.
con <- pipe("echo shelf; echo catalogue")
readLines(con)
#> [1] "shelf"     "catalogue"
close(con)

# Writing to a pipe: whatever R writes becomes the command's standard input.
sorted <- tempfile(fileext = ".txt")
con <- pipe(paste("sort >", shQuote(sorted)), "w")
writeLines(c("pear", "apple", "fig"), con)
status <- close(con)
status
#> [1] 0
readLines(sorted)
#> [1] "apple" "fig"   "pear"

# close() returns the exit status of the command (zero means success).
con <- pipe("exit 3")
open(con, "r")
status <- close(con)
status != 0L
#> [1] TRUE

# A fifo (named pipe), opened for reading and writing in the same process.
if (capabilities("fifo")) {
  fifo_path <- tempfile()
  con <- fifo(fifo_path, "w+")
  writeLines("through the fifo", con)
  print(readLines(con))
  close(con)
  unlink(fifo_path)
}
#> [1] "through the fifo"

# A TCP server and client talking over the loopback interface. The port
# number is an arbitrary free one.
port <- 11823L
server <- serverSocket(port)
client <- socketConnection("localhost", port, blocking = TRUE, open = "r+")
peer <- socketAccept(server, blocking = TRUE, open = "r+")
writeLines("ping", client)
flush(client)
readLines(peer, n = 1)
#> [1] "ping"
writeLines("pong", peer)
flush(peer)
readLines(client, n = 1)
#> [1] "pong"
vapply(list(server, client, peer), \(con) class(con)[1L], character(1))
#> [1] "servsockconn" "sockconn"     "sockconn"
close(client)
close(peer)
close(server)
nrow(showConnections())
#> [1] 0

# Read a file in pieces of three lines.
path <- tempfile(fileext = ".txt")
writeLines(sprintf("row %02d", 1:7), path)
con <- file(path, "r")
repeat {
  chunk <- readLines(con, n = 3)
  if (length(chunk) == 0L) break
  cat(length(chunk), "lines, first:", chunk[1L], "\n")
}
#> 3 lines, first: row 01
#> 3 lines, first: row 04
#> 1 lines, first: row 07
close(con)

# Different readers on one open connection: the header as text, then rows.
con <- file("books.csv", "r")
header <- readLines(con, n = 1)
columns <- strsplit(gsub('"', "", header), ",")[[1L]]
columns
#> [1] "title"  "author" "isbn"   "year"   "genre"  "pages"
rows <- read.csv(con, header = FALSE, nrows = 3, col.names = columns)
rows[, c("title", "year", "pages")]
#>                  title year pages
#> 1     The Dispossessed 1974   387
#> 2  Pride and Prejudice 1813   432
#> 3   the quiet streets  2019   214
readLines(con, n = 1)
#> [1] "\"Loud Roofs\",\"Mara Quill\",\"978-0-00-200029-1\",2021,\"fiction\",198"
close(con)

# A file without a final newline: a warning, and the text is still read.
no_eol <- tempfile()
cat("line one\nline two", file = no_eol)
msg <- tryCatch(readLines(no_eol), warning = \(w) conditionMessage(w))
sub("'.*'", "'<file>'", msg)
#> [1] "incomplete final line found on '<file>'"
readLines(no_eol, warn = FALSE)
#> [1] "line one" "line two"

# pushBack() puts lines back; the most recently pushed lines are read first.
tc <- textConnection(LETTERS)
readLines(tc, 2)
#> [1] "A" "B"
scan(tc, "", 4, quiet = TRUE)
#> [1] "C" "D" "E" "F"
pushBack(c("aa", "bb"), tc)
pushBackLength(tc)
#> [1] 2
scan(tc, "", 4, quiet = TRUE)
#> [1] "aa" "bb" "G"  "H"
pushBackLength(tc)
#> [1] 0
close(tc)

# Peek at a line without consuming it.
peek_line <- function(con) {
  line <- readLines(con, n = 1)
  pushBack(line, con)
  line
}
tc <- textConnection(c("# comment", "data"))
peek_line(tc)
#> [1] "# comment"
readLines(tc, n = 2)
#> [1] "# comment" "data"
close(tc)

# seek() moves the file position (it returns the position before the move).
text_file <- tempfile()
writeLines(c("abc", "def", "ghi"), text_file)
con <- file(text_file, "rb")
isSeekable(con)
#> [1] TRUE
readChar(con, 3)
#> [1] "abc"
seek(con)
#> [1] 3
seek(con, 8)
#> [1] 3
readChar(con, 3)
#> [1] "ghi"
seek(con, 0)
#> [1] 11
readChar(con, 3)
#> [1] "abc"
close(con)

# truncate() cuts a file opened for writing at the current write position.
con <- file(text_file, "r+")
invisible(seek(con, 4, rw = "write"))
invisible(truncate(con))
close(con)
readLines(text_file)
#> [1] "abc"

# flush() pushes buffered output to the file without closing it.
out <- file(text_file, "w")
cat("buffered text", file = out)
flush(out)
file.size(text_file)
#> [1] 13
close(out)

# file() with no description is an anonymous scratch file.
scratch <- file()
cat("abc\ndef\n", file = scratch)
readLines(scratch)
#> [1] "abc" "def"
close(scratch)

# Write several types to a binary file, then read them back in order.
path <- tempfile(fileext = ".bin")
con <- file(path, "wb")
writeBin(c(1L, 256L, -1L), con)
writeBin(c(1.5, -2), con)
writeBin(TRUE, con)
writeBin("shelf", con)
writeBin(as.raw(c(0xde, 0xad)), con)
close(con)
file.size(path)
#> [1] 40

con <- file(path, "rb")
readBin(con, "integer", n = 3)
#> [1]   1 256  -1
readBin(con, "double", n = 2)
#> [1]  1.5 -2.0
readBin(con, "logical", n = 1)
#> [1] TRUE
readBin(con, "character", n = 1)
#> [1] "shelf"
readBin(con, "raw", n = 10)
#> [1] de ad
readBin(con, "integer", n = 5)
#> integer(0)
close(con)

# The first twelve bytes: three 4-byte integers (little-endian here).
readBin(path, "raw", n = 12)
#>  [1] 01 00 00 00 00 01 00 00 ff ff ff ff

# endian and size make the byte stream independent of the machine.
writeBin(1L, raw(), endian = "little")
#> [1] 01 00 00 00
writeBin(1L, raw(), endian = "big")
#> [1] 00 00 00 01
writeBin(1L, raw(), size = 2, endian = "big")
#> [1] 00 01
writeBin(1L, raw(), size = 1)
#> [1] 01
writeBin(pi, raw(), size = 4, endian = "big")
#> [1] 40 49 0f db
readBin(writeBin(pi, raw(), size = 4), "double", size = 4)
#> [1] 3.141593
bytes <- as.raw(c(0xff, 0xff))
readBin(bytes, "integer", size = 2)
#> [1] -1
readBin(bytes, "integer", size = 2, signed = FALSE)
#> [1] 65535
.Platform$endian
#> [1] "little"

# Missing values are passed through at the natural size.
writeBin(NA_integer_, raw())
#> [1] 00 00 00 80
readBin(writeBin(NA_integer_, raw()), "integer")
#> [1] NA

# Fixed-length strings: writeChar() and readChar().
chars <- tempfile()
con <- file(chars, "wb")
writeChar("ABCDEF", con, eos = NULL)
writeChar("xyz", con)
close(con)
readBin(chars, "raw", n = 20)
#>  [1] 41 42 43 44 45 46 78 79 7a 00
con <- file(chars, "rb")
readChar(con, 3)
#> [1] "ABC"
readChar(con, c(3, 3))
#> [1] "DEF" "xyz"
close(con)
readChar(chars, 6)
#> [1] "ABCDEF"

# Characters and bytes differ for non-ASCII text.
utf8 <- tempfile()
writeChar("é", utf8, eos = NULL)
file.size(utf8)
#> [1] 2
readChar(utf8, 1)
#> [1] "é"
readChar(utf8, 1, useBytes = TRUE)
#> [1] "\xc3"

# Raw vectors and strings.
r <- charToRaw("shelf é")
r
#> [1] 73 68 65 6c 66 20 c3 a9
rawToChar(r)
#> [1] "shelf é"
class(r)
#> [1] "raw"
rawToChar(r[1:5])
#> [1] "shelf"

# In-memory compression.
text <- paste(readLines("books.csv"), collapse = "\n")
packed <- memCompress(charToRaw(text), type = "gzip")
packed[1:2]
#> [1] 78 9c
length(packed) < nchar(text, type = "bytes")
#> [1] TRUE
identical(rawToChar(memDecompress(packed, type = "gzip")), text)
#> [1] TRUE
identical(rawToChar(memDecompress(packed, type = "unknown")), text)
#> [1] TRUE

# stdin(), stdout() and stderr() are always open and cannot be closed.
isOpen(stdout())
#> [1] TRUE
isOpen(stdin())
#> [1] TRUE
unlist(summary(stdout())[c("class", "mode", "opened")])
#>      class       mode     opened
#> "terminal"        "w"   "opened"
tryCatch(close(stdout()), error = \(e) conditionMessage(e))
#> [1] "cannot close standard connections"
tryCatch(open(stdin()), error = \(e) conditionMessage(e))
#> [1] "cannot open standard connections"

# Writing to the two output streams; a message sink can capture stderr.
writeLines("to stdout", stdout())
#> to stdout
capture.output(writeLines("to stderr", stderr()), type = "message")
#> [1] "to stderr"

# What a script reads depends on the connection. Two throw-away scripts are
# run with Rscript and given three lines of standard input.
rscript <- file.path(R.home("bin"), "Rscript")
child <- tempfile(fileext = ".R")
writeLines(c(
  "text <- readLines(file(\"stdin\"), n = 2)",
  "cat(\"file(stdin) read:\", text, \"\\n\")"
), child)
system2(rscript, shQuote(child), input = c("one", "two", "three"),
        stdout = TRUE)
#> [1] "file(stdin) read: one two "

# stdin() is the console; in a script run by Rscript the console is the
# script file, so the next line of the script is what gets read.
writeLines(c(
  "text <- readLines(stdin(), n = 1)",
  "this line is read as data and never evaluated",
  "cat(\"stdin() read:\", text, \"\\n\")"
), child)
system2(rscript, shQuote(child), input = c("one", "two", "three"),
        stdout = TRUE)
#> [1] "stdin() read: this line is read as data and never evaluated "

# Assemble paths with file.path(), never with paste().
file.path("data", "books.csv")
#> [1] "data/books.csv"
file.path("data", c("books.csv", "loans.csv"))
#> [1] "data/books.csv" "data/loans.csv"
file.path("data", character())
#> character(0)
file.path("data/", "books.csv")
#> [1] "data//books.csv"
paste("data", "books.csv", sep = "/")
#> [1] "data/books.csv"

# Split them with basename() and dirname().
files <- c("data/books.csv", "data/", "books.csv", "/", "")
basename(files)
#> [1] "books.csv" "data"      "books.csv" ""          ""
dirname(files)
#> [1] "data" "."    "."    "/"    ""

# Extensions: tools::file_ext() and tools::file_path_sans_ext().
file_names <- c(
  "books.csv", "backup.tar.gz", "README", ".gitignore", "LOANS.CSV"
)
tools::file_ext(file_names)
#> [1] "csv" "gz"  ""    ""    "CSV"
tools::file_path_sans_ext(file_names)
#> [1] "books"      "backup.tar" "README"     ".gitignore" "LOANS"
tools::file_path_sans_ext("backup.tar.gz", compression = TRUE)
#> [1] "backup"

# The tilde is expanded by R itself, from HOME (or R_USER on Windows).
path.expand("~") == Sys.getenv("HOME")
#> [1] TRUE
identical(
  path.expand("~/shelf/books.csv"),
  file.path(Sys.getenv("HOME"), "shelf", "books.csv")
)
#> [1] TRUE

# normalizePath() makes a path absolute and resolves ".." and links.
normalizePath("books.csv") == file.path(getwd(), "books.csv")
#> [1] TRUE
basename(normalizePath("../shelf/./books.csv"))
#> [1] "books.csv"

# A path that does not exist: a warning by default, an error with mustWork.
msg <- tryCatch(normalizePath("nosuch.csv"), warning = \(w) conditionMessage(w))
msg
#> [1] "path[1]=\"nosuch.csv\": No such file or directory"
tryCatch(
  normalizePath("nosuch.csv", mustWork = TRUE),
  error = \(e) conditionMessage(e)
)
#> [1] "path[1]=\"nosuch.csv\": No such file or directory"
normalizePath("nosuch.csv", mustWork = FALSE)
#> [1] "nosuch.csv"

# winslash only matters on Windows: "\\" (the default) or "/".
normalizePath("books.csv", winslash = "/") == normalizePath("books.csv")
#> [1] TRUE

# On Windows file.path() still joins with "/", which Windows accepts.
file.path("C:", "data", "books.csv")
#> [1] "C:/data/books.csv"
.Platform$file.sep
#> [1] "/"

# Build a small tree in a temporary directory (nothing is printed in full:
# the examples show paths relative to it).
root <- file.path(tempdir(), "shelf-export")
dir.create(file.path(root, "reports", "2026"), recursive = TRUE)
dir.create(file.path(root, "data"))
tree <- c(
  "data/books.csv", "data/loans.csv", "data/notes.txt", "data/.hidden",
  "reports/summary.md", "reports/2026/q1.csv", "reports/2026/q2.csv",
  "top.R", "a.b.csv", "axb.csv", "book[1].csv"
)
invisible(file.create(file.path(root, tree)))

# list.files(): names only, hidden files off, not recursive.
list.files(root)
#> [1] "a.b.csv"     "axb.csv"     "book[1].csv" "data"        "reports"
#> [6] "top.R"
list.files(root, all.files = TRUE)
#> [1] "."           ".."          "a.b.csv"     "axb.csv"     "book[1].csv"
#> [6] "data"        "reports"     "top.R"
list.files(root, all.files = TRUE, no.. = TRUE)
#> [1] "a.b.csv"     "axb.csv"     "book[1].csv" "data"        "reports"
#> [6] "top.R"
list.files(file.path(root, "data"), all.files = TRUE, no.. = TRUE)
#> [1] ".hidden"   "books.csv" "loans.csv" "notes.txt"

# recursive = TRUE lists files in subdirectories; include.dirs keeps the
# directories themselves.
list.files(root, recursive = TRUE)
#>  [1] "a.b.csv"             "axb.csv"             "book[1].csv"
#>  [4] "data/books.csv"      "data/loans.csv"      "data/notes.txt"
#>  [7] "reports/2026/q1.csv" "reports/2026/q2.csv" "reports/summary.md"
#> [10] "top.R"
list.files(root, recursive = TRUE, include.dirs = TRUE)
#>  [1] "a.b.csv"             "axb.csv"             "book[1].csv"
#>  [4] "data"                "data/books.csv"      "data/loans.csv"
#>  [7] "data/notes.txt"      "reports"             "reports/2026"
#> [10] "reports/2026/q1.csv" "reports/2026/q2.csv" "reports/summary.md"
#> [13] "top.R"

# pattern is a regular expression, matched against the file name only.
list.files(root, pattern = "\\.csv$", recursive = TRUE)
#> [1] "a.b.csv"             "axb.csv"             "book[1].csv"
#> [4] "data/books.csv"      "data/loans.csv"      "reports/2026/q1.csv"
#> [7] "reports/2026/q2.csv"
list.files(root, pattern = "^[Tt]", recursive = TRUE)
#> [1] "top.R"

# full.names = TRUE prepends the directory.
full <- list.files(root, pattern = "csv$", recursive = TRUE, full.names = TRUE)
substring(full, nchar(root) + 2L)
#> [1] "a.b.csv"             "axb.csv"             "book[1].csv"
#> [4] "data/books.csv"      "data/loans.csv"      "reports/2026/q1.csv"
#> [7] "reports/2026/q2.csv"

# fixed = TRUE (R 4.6.0): the pattern is literal text, not a regular expression.
list.files(root, pattern = "a.b.csv")
#> [1] "a.b.csv" "axb.csv"
list.files(root, pattern = "a.b.csv", fixed = TRUE)
#> [1] "a.b.csv"
list.files(root, pattern = "[1]", recursive = TRUE)
#> [1] "book[1].csv"         "reports/2026/q1.csv"
list.files(root, pattern = "[1]", recursive = TRUE, fixed = TRUE)
#> [1] "book[1].csv"
tryCatch(
  list.files(root, pattern = "book[1.csv"),
  error = \(e) conditionMessage(e)
)
#> [1] "invalid 'pattern' regular expression"

# list.dirs() and wildcards.
list.dirs(root, full.names = FALSE)
#> [1] ""             "data"         "reports"      "reports/2026"
list.dirs(root, full.names = FALSE, recursive = FALSE)
#> [1] "data"    "reports"
basename(Sys.glob(file.path(root, "data", "*.csv")))
#> [1] "books.csv" "loans.csv"
substring(Sys.glob(file.path(root, "*", "*.csv")), nchar(root) + 2L)
#> [1] "data/books.csv" "data/loans.csv"
Sys.glob(file.path(root, "nosuch*"))
#> character(0)
glob2rx("a*.csv")
#> [1] "^a.*\\.csv$"
list.files(root, pattern = glob2rx("a*.csv"))
#> [1] "a.b.csv" "axb.csv"

# A directory that does not exist is an empty listing, not an error.
list.files(file.path(root, "nosuch"))
#> character(0)

# Existence tests.
file.exists(file.path(root, c("top.R", "data", "nosuch")))
#> [1]  TRUE  TRUE FALSE
dir.exists(file.path(root, c("top.R", "data", "nosuch")))
#> [1] FALSE  TRUE FALSE
utils::file_test("-f", file.path(root, c("top.R", "data")))
#> [1]  TRUE FALSE

unlink(root, recursive = TRUE)

# Work in a scratch directory under tempdir().
work <- file.path(tempdir(), "work")
dir.create(work)

# Creating it again is a warning and FALSE; showWarnings = FALSE hides it.
msg <- tryCatch(dir.create(work), warning = \(w) conditionMessage(w))
sub("^'.*' ", "'<dir>' ", msg)
#> [1] "'<dir>' already exists"
print(dir.create(work, showWarnings = FALSE))
#> [1] FALSE

# Nested directories need recursive = TRUE.
nested <- file.path(work, "a", "b")
msg <- tryCatch(dir.create(nested), warning = \(w) conditionMessage(w))
sub("'.*', reason", "'<dir>', reason", msg)
#> [1] "cannot create dir '<dir>', reason 'No such file or directory'"
dir.create(nested, recursive = TRUE)
dir.exists(nested)
#> [1] TRUE

# Create, copy, rename, append.
src <- file.path(work, "src.txt")
file.create(src)
#> [1] TRUE
writeLines("hello", src)
dst <- file.path(work, "dst.txt")
file.copy(src, dst)
#> [1] TRUE
file.copy(src, dst)
#> [1] FALSE
file.copy(src, dst, overwrite = TRUE)
#> [1] TRUE
file.copy(src, file.path(work, "a"))
#> [1] TRUE
list.files(work, recursive = TRUE)
#> [1] "a/src.txt" "dst.txt"   "src.txt"
file.rename(dst, file.path(work, "renamed.txt"))
#> [1] TRUE
file.append(src, src)
#> [1] TRUE
readLines(src)
#> [1] "hello" "hello"

# Failures are warnings and FALSE; the paths in the messages are replaced here.
missing <- file.path(work, "nosuch.txt")
msg <- tryCatch(
  file.rename(missing, file.path(work, "again.txt")),
  warning = \(w) conditionMessage(w)
)
gsub("'[^']*/[^']*'", "'<path>'", msg)
#> [1] "cannot rename file '<path>' to '<path>', reason 'No such file or directory'"
msg <- tryCatch(
  file.copy(c(src, missing), file.path(work, "a")),
  warning = \(w) conditionMessage(w)
)
gsub("/[^ :]+", "<path>", msg)
#> [1] "problem copying <path> to <path>: No such file or directory"

# Copying a directory needs recursive = TRUE and an existing target directory.
dir.create(file.path(work, "z"))
tryCatch(
  file.copy(file.path(work, "a"), file.path(work, "new")),
  warning = \(w) conditionMessage(w)
)
#> [1] "directories are omitted unless 'recursive = TRUE'"
tryCatch(
  file.copy(file.path(work, "a"), file.path(work, "new"), recursive = TRUE),
  warning = \(w) conditionMessage(w)
)
#> [1] "'recursive' will be ignored as 'to' is not a single existing directory"
file.copy(file.path(work, "a"), file.path(work, "z"), recursive = TRUE)
#> [1] TRUE
list.files(file.path(work, "z"), recursive = TRUE, include.dirs = TRUE)
#> [1] "a"         "a/b"       "a/src.txt"

# file.remove() deletes files; unlink() also deletes directories and
# understands wildcards.
file.remove(file.path(work, "renamed.txt"))
#> [1] TRUE
msg <- tryCatch(
  file.remove(file.path(work, "a")),
  warning = \(w) conditionMessage(w)
)
sub("'.*', reason", "'<dir>', reason", msg)
#> [1] "cannot remove file '<dir>', reason 'Directory not empty'"
print(unlink(file.path(work, "a")))
#> [1] 1
dir.exists(file.path(work, "a"))
#> [1] TRUE
unlink(file.path(work, "a"), recursive = TRUE)
dir.exists(file.path(work, "a"))
#> [1] FALSE
invisible(file.create(file.path(work, c("x1.tmp", "x2.tmp", "keep.txt"))))
unlink(file.path(work, "*.tmp"))
list.files(work)
#> [1] "keep.txt" "src.txt"  "z"
unlink(file.path(work, "nosuch.txt"))

# A name that contains a wildcard character needs expand = FALSE.
star <- file.path(work, "star*.tmp")
invisible(file.create(star, file.path(work, "starfish.tmp")))
unlink(star, expand = FALSE)
list.files(work, pattern = "star")
#> [1] "starfish.tmp"

# Information: file.info(), file.size(), file.mtime(), file.access().
info <- file.info(file.path(work, c("src.txt", "z", "nosuch.txt")))
basename(rownames(info))
#> [1] "src.txt"    "z"          "nosuch.txt"
info$isdir
#> [1] FALSE  TRUE    NA
info$size[1L]
#> [1] 12
names(info)
#>  [1] "size"   "isdir"  "mode"   "mtime"  "ctime"  "atime"  "uid"    "gid"
#>  [9] "uname"  "grname"
file.size(file.path(work, c("src.txt", "nosuch.txt")))
#> [1] 12 NA
class(file.mtime(src))
#> [1] "POSIXct" "POSIXt"
unname(file.access(src, 4))
#> [1] 0
unname(file.access(file.path(work, "nosuch.txt"), 0))
#> [1] -1

# Permissions are an octal mode; file.copy(copy.date = TRUE) keeps the time.
Sys.chmod(src, "640")
format(file.info(src)$mode)
#> [1] "640"
Sys.setFileTime(src, as.POSIXct("2026-06-30 12:00:00", tz = "UTC"))
dated <- file.path(work, "dated.txt")
file.copy(src, dated, copy.date = TRUE)
#> [1] TRUE
format(file.mtime(dated), tz = "UTC", usetz = TRUE)
#> [1] "2026-06-30 12:00:00 UTC"

# Links (not on every file system).
link <- file.path(work, "link.txt")
file.symlink(src, link)
#> [1] TRUE
Sys.readlink(link) == src
#> [1] TRUE
Sys.readlink(src)
#> [1] ""
file.exists(link)
#> [1] TRUE
basename(normalizePath(link))
#> [1] "src.txt"

unlink(work, recursive = TRUE)
dir.exists(work)
#> [1] FALSE

# tempfile() only invents a name: it creates nothing.
a <- tempfile()
b <- tempfile()
a != b
#> [1] TRUE
file.exists(a)
#> [1] FALSE
dirname(a) == tempdir()
#> [1] TRUE

# The pattern, the directory and the extension are all arguments.
p <- tempfile("shelf-", fileext = ".csv")
grepl("^shelf-.*\\.csv$", basename(p))
#> [1] TRUE
two <- tempfile(c("a", "b"), fileext = c(".x", ".y"))
sub("[0-9a-f]+", "<id>", basename(two))
#> [1] "<id>.x" "<id>.y"

# A private scratch directory, removed when the function ends.
with_scratch <- function(code) {
  scratch <- tempfile("scratch-")
  dir.create(scratch)
  on.exit(unlink(scratch, recursive = TRUE))
  code(scratch)
}
with_scratch(\(dir) {
  writeLines("temporary", file.path(dir, "note.txt"))
  list.files(dir)
})
#> [1] "note.txt"

# tempdir() is one directory per R session, deleted when the session ends.
dir.exists(tempdir())
#> [1] TRUE
tempdir() == tempdir()
#> [1] TRUE
Sys.getenv("TMPDIR", unset = "<unset>")
#> [1] "<unset>"

# If something deletes it, tempfile() names stop working; tempdir(check =
# TRUE) recreates a valid directory.
old <- tempdir()
unlink(old, recursive = TRUE)
dir.exists(old)
#> [1] FALSE
msg <- tryCatch(writeLines("x", tempfile()), warning = \(w) conditionMessage(w))
sub("'.*'", "'<file>'", msg)
#> [1] "cannot open file '<file>': No such file or directory"
dir.exists(tempdir(check = TRUE))
#> [1] TRUE
writeLines("x", tempfile())

# The working directory is where relative paths start.
basename(getwd())
#> [1] "shelf"
file.exists("books.csv")
#> [1] TRUE
identical(file.path(getwd(), "books.csv"), normalizePath("books.csv"))
#> [1] TRUE

# Environment variables: unset ones are "" unless unset= says otherwise.
Sys.getenv("SHELF_DATA_DIR")
#> [1] ""
Sys.getenv("SHELF_DATA_DIR", unset = NA)
#> [1] NA
Sys.getenv("SHELF_DATA_DIR", unset = "data")
#> [1] "data"

# Sys.setenv() takes named arguments and returns TRUE for each.
Sys.setenv(SHELF_DATA_DIR = "export", SHELF_FORMAT = "csv")
Sys.getenv(c("SHELF_DATA_DIR", "SHELF_FORMAT"))
#> SHELF_DATA_DIR   SHELF_FORMAT
#>       "export"          "csv"
Sys.getenv("SHELF_DATA_DIR") |> file.path("books.csv")
#> [1] "export/books.csv"
Sys.unsetenv("SHELF_FORMAT")
Sys.getenv("SHELF_FORMAT", unset = NA)
#> [1] NA
tryCatch(Sys.setenv("SHELF_FORMAT"), error = \(e) conditionMessage(e))
#> [1] "all arguments must be named"

# Child processes inherit the variables set in the session.
system2("sh", c("-c", shQuote("echo $SHELF_DATA_DIR")), stdout = TRUE)
#> [1] "export"

# Tilde expansion reads HOME.
nzchar(Sys.getenv("HOME"))
#> [1] TRUE
old_home <- Sys.getenv("HOME")
Sys.setenv(HOME = "/srv/shelf")
path.expand("~/books.csv")
#> [1] "/srv/shelf/books.csv"
Sys.setenv(HOME = old_home)

# Changing TMPDIR in a running session does not move tempdir().
before <- tempdir()
Sys.setenv(TMPDIR = "/srv/scratch")
identical(before, tempdir())
#> [1] TRUE
Sys.unsetenv("TMPDIR")
Sys.unsetenv("SHELF_DATA_DIR")

# .Renviron: one NAME=value per line, read when R starts (illustrative, not run)
SHELF_DATA_DIR=export
SHELF_DB_PASSWORD=change-me
TMPDIR=/srv/scratch

# system2(): the command and its arguments are separate.
system2("echo", c("a", "b"), stdout = TRUE)
#> [1] "a b"

# Arguments go through a shell: quote anything with spaces or metacharacters.
system2("echo", "a   b", stdout = TRUE)
#> [1] "a b"
system2("echo", shQuote("a   b"), stdout = TRUE)
#> [1] "a   b"
shQuote("a b")
#> [1] "'a b'"
shQuote("it's")
#> [1] "\"it's\""
shQuote("a b", type = "cmd")
#> [1] "\"a b\""

# Capture output: stdout = TRUE returns the lines; stderr = TRUE merges them.
script <- shQuote("echo out; echo err >&2; exit 4")
both <- suppressWarnings(
  system2("sh", c("-c", script), stdout = TRUE, stderr = TRUE)
)
as.vector(both)
#> [1] "out" "err"
attr(both, "status")
#> [1] 4
only_out <- suppressWarnings(
  system2("sh", c("-c", script), stdout = TRUE, stderr = FALSE)
)
as.vector(only_out)
#> [1] "out"

# Without stdout = TRUE the value is the exit status.
system2("sh", c("-c", shQuote("exit 5")))
system2("true")

# Environment variables for the child, and standard input from R.
system2("sh", c("-c", shQuote("echo $SHELF_DEMO")), env = "SHELF_DEMO=books",
        stdout = TRUE)
#> [1] "books"
system2("sort", input = c("pear", "apple", "fig"), stdout = TRUE)
#> [1] "apple" "fig"   "pear"

# A timeout: the command is killed and the status is 124.
res <- suppressWarnings(system2("sleep", "5", timeout = 1))
res
#> [1] 124

# system() takes one command line, which a shell parses.
system("echo from the shell", intern = TRUE)
#> [1] "from the shell"
files <- c("a b.txt", "c.txt")
system(paste("printf '%s\\n'", paste(shQuote(files), collapse = " ")),
       intern = TRUE)
#> [1] "a b.txt" "c.txt"

# Sys.which() finds a program on the PATH ("" if there is none).
nzchar(Sys.which(c("sh", "tar", "no_such_program_xyz")))
#> [1]  TRUE  TRUE FALSE
names(Sys.which("sh"))
#> [1] "sh"

# A program that does not exist: system2() reports a missing command.
msg <- suppressWarnings(tryCatch(
  system2("no_such_program_xyz", stdout = TRUE, stderr = FALSE),
  error = \(e) conditionMessage(e)
))
sub(":.*$", "", msg)
#> [1] "error in running command"

# Build a small export tree inside the working directory (removed at the end).
root <- "export-demo"
dir.create(file.path(root, "data"), recursive = TRUE)
invisible(file.copy(c("books.csv", "loans.csv"), file.path(root, "data")))
writeLines("shelf export", file.path(root, "README.txt"))
list.files(root, recursive = TRUE)
#> [1] "data/books.csv" "data/loans.csv" "README.txt"

# tar: files are recorded with the paths given; the archive lives in tempdir().
tarball <- tempfile(fileext = ".tar.gz")
tar(tarball, files = root, compression = "gzip")
untar(tarball, list = TRUE)
#> [1] "export-demo/data/"          "export-demo/data/books.csv"
#> [3] "export-demo/data/loans.csv" "export-demo/README.txt"

# Extract everything, or only some files, into a directory (created if needed).
dest <- file.path(tempdir(), "from-tar")
untar(tarball, exdir = dest)
list.files(dest, recursive = TRUE)
#> [1] "export-demo/data/books.csv" "export-demo/data/loans.csv"
#> [3] "export-demo/README.txt"
one <- file.path(tempdir(), "one-file")
untar(tarball, files = "export-demo/README.txt", exdir = one)
list.files(one, recursive = TRUE)
#> [1] "export-demo/README.txt"
same <- tools::md5sum(c(
  file.path(root, "data", "books.csv"),
  file.path(dest, root, "data", "books.csv")
))
unname(same[1L] == same[2L])
#> [1] TRUE

# zip needs an external zip program to create an archive.
nzchar(Sys.which("zip"))
#> [1] TRUE
zipfile <- tempfile(fileext = ".zip")
zip(zipfile, files = root, flags = "-r9Xq")
listing <- unzip(zipfile, list = TRUE)
print(listing[order(listing$Name), c("Name", "Length")], row.names = FALSE)
#>                        Name Length
#>                export-demo/      0
#>           export-demo/data/      0
#>  export-demo/data/books.csv   1187
#>  export-demo/data/loans.csv   3694
#>      export-demo/README.txt     13

# unzip() is built in; it returns the extracted paths invisibly.
unzipped <- unzip(zipfile, exdir = file.path(tempdir(), "from-zip"))
sort(basename(unzipped))
#> [1] "books.csv"  "loans.csv"  "README.txt"
unzipped <- unzip(zipfile, files = "export-demo/README.txt",
                  exdir = file.path(tempdir(), "from-zip-one"))
basename(unzipped)
#> [1] "README.txt"

# unz() reads one member of a zip file without extracting it.
con <- unz(zipfile, "export-demo/data/books.csv")
readLines(con, n = 2)
#> [1] "\"title\",\"author\",\"isbn\",\"year\",\"genre\",\"pages\""
#> [2] "\"The Dispossessed\",\"Ursula K. Le Guin\",\"978-0-306-40615-7\",1974,\"Science fiction\",387"
close(con)

unlink(root, recursive = TRUE)
dir.exists(root)
#> [1] FALSE

# Write "cafe" with an acute accent in Latin-1: the connection converts.
path <- tempfile(fileext = ".txt")
con <- file(path, "w", encoding = "latin1")
writeLines("café", con)
close(con)
readBin(path, "raw", n = 5)
#> [1] 63 61 66 e9 0a

# Without the encoding the Latin-1 byte is not valid UTF-8.
x <- suppressWarnings(readLines(path))
x
#> [1] "caf\xe9"
validUTF8(x)
#> [1] FALSE

# Declaring the encoding of the strings does not convert the bytes ...
y <- readLines(path, encoding = "latin1")
Encoding(y)
#> [1] "latin1"
y
#> [1] "café"

# ... re-encoding is done by the connection, or by fileEncoding.
con <- file(path, encoding = "latin1")
z <- readLines(con)
close(con)
z
#> [1] "café"
Encoding(z)
#> [1] "UTF-8"
read.csv(path, header = FALSE, fileEncoding = "latin1")
#>     V1
#> 1 café

# A byte order mark from a Windows tool. In a UTF-8 locale readLines() drops
# it by itself; the encoding name UTF-8-BOM makes the connection drop it.
bom <- tempfile(fileext = ".csv")
writeBin(c(as.raw(c(0xef, 0xbb, 0xbf)), charToRaw("title,pages\n")), bom)
readBin(bom, "raw", n = 4)
#> [1] ef bb bf 74
utf8ToInt(readLines(bom, n = 1L))[1L]
#> [1] 116
con <- file(bom, encoding = "UTF-8-BOM")
utf8ToInt(readLines(con, n = 1L))[1L]
#> [1] 116
close(con)

# An unsupported encoding name fails when the connection is used.
con <- file(path, encoding = "no-such-encoding")
tryCatch(readLines(con), error = \(e) conditionMessage(e))
#> [1] "unsupported conversion from 'no-such-encoding' to ''"
tryCatch(isOpen(con), error = \(e) conditionMessage(e))
#> [1] "invalid connection"

# Record every warning and error that an expression signals, in order.
conditions <- function(expr) {
  seen <- new.env()
  seen$messages <- character()
  note <- \(type, cond) {
    text <- paste0(type, ": ", conditionMessage(cond))
    seen$messages <- c(seen$messages, text)
  }
  withCallingHandlers(
    tryCatch(expr, error = \(e) note("error", e)),
    warning = \(w) {
      note("warning", w)
      invokeRestart("muffleWarning")
    }
  )
  seen$messages
}
hide_path <- \(x) gsub("'[^']*/[^']*'", "'<path>'", x)

# A file that does not exist.
conditions(readLines("nosuch.txt"))
#> [1] "warning: cannot open file 'nosuch.txt': No such file or directory"
#> [2] "error: cannot open the connection"
conditions(read.csv("nosuch.csv"))
#> [1] "warning: cannot open file 'nosuch.csv': No such file or directory"
#> [2] "error: cannot open the connection"
conditions(gzfile("nosuch.gz", "r"))
#> [1] "warning: cannot open compressed file 'nosuch.gz', probable reason 'No such file or directory'"
#> [2] "error: cannot open the connection"

# A directory is not a file.
hide_path(conditions(readLines(tempdir())))
#> [1] "warning: 'raw = FALSE' but '<path>' is not a regular file"
#> [2] "warning: cannot open file '<path>': it is a directory"
#> [3] "error: cannot open the connection"

# A closed or unknown connection.
path <- tempfile()
writeLines(c("a", "b"), path)
con <- file(path, "r")
close(con)
conditions(readLines(con))
#> [1] "error: invalid connection"
conditions(close(con))
#> [1] "error: invalid connection"
conditions(getConnection(77))
#> [1] "error: there is no connection 77"
conditions(readLines(1))
#> [1] "error: 'con' is not a connection"

# Operations that need an open connection, or the other mode.
unopened <- file(path)
conditions(seek(unopened))
#> [1] "error: connection is not open"
conditions(truncate(unopened))
#> [1] "error: can only truncate an open connection"
close(unopened)
writer <- file(path, "w")
conditions(readLines(writer))
#> [1] "error: cannot read from this connection"
close(writer)
reader <- file(path, "r")
conditions(writeLines("x", reader))
#> [1] "error: cannot write to this connection"
conditions(readBin(reader, "integer", size = 3))
#> [1] "error: can only read from a binary connection"
close(reader)
conditions(close(stdout()))
#> [1] "error: cannot close standard connections"
conditions(file(c("a", "b")))
#> [1] "error: invalid 'description' argument"

# Binary data read as text.
bin <- tempfile()
writeBin(as.raw(c(0x41, 0x00, 0x42, 0x0a)), bin)
conditions(readLines(bin))
#> [1] "warning: line 1 appears to contain an embedded nul"
conditions(rawToChar(as.raw(c(0x73, 0x00, 0x68))))
#> [1] "error: embedded nul in string: 's\\0h'"

# Too many connections at once: the limit is 128 including the standard three.
leaked <- list()
conditions(repeat leaked[[length(leaked) + 1L]] <- file(path, "r"))
#> [1] "error: all 128 connections are in use"
length(leaked)
#> [1] 125
invisible(lapply(leaked, close))
nrow(showConnections())
#> [1] 0

# A socket nobody listens on.
conditions(socketConnection("localhost", 11824L, open = "r+", timeout = 2))
#> [1] "warning: localhost:11824 cannot be opened"
#> [2] "error: cannot open the connection"

# Files that are not what the reader expects.
conditions(readRDS(path))
#> [1] "error: error reading from connection"
conditions(unzip("nosuch.zip"))
#> [1] "warning: error 1 in extracting from zip file"
conditions(dir.create(""))
#> [1] "error: zero-length 'path' argument"