files {base} | R Documentation

## File Manipulation

### Description

These functions provide a low-level interface to the computer's file system.

### Usage

    file.create(..., showWarnings = TRUE)
    file.exists(...)
    file.remove(...)
    file.rename(from, to)
    file.append(file1, file2)
    file.copy(from, to, overwrite = recursive, recursive = FALSE,
              copy.mode = TRUE, copy.date = FALSE)
    file.symlink(from, to)
    file.link(from, to)
    Sys.junction(from, to)

### Arguments

`..., file1, file2` | character vectors, containing file names or paths.
`from, to` | character vectors, containing file names or paths. For `file.copy` and `file.symlink` and `Sys.junction` `to` can alternatively be the path to a single existing directory.
`overwrite` | logical; should existing destination files be overwritten?
`showWarnings` | logical; should the warnings on failure be shown?
`recursive` | logical. If `to` is a directory, should directories in `from` be copied (and their contents)? (Like `cp -R` on POSIX OSes.)
`copy.mode` | logical: should file permission bits be copied where possible?
`copy.date` | logical: should file dates be preserved where possible? See `Sys.setFileTime`.

### Details

The `...` arguments are concatenated to form one character string: you can specify the files separately or as one vector. All of these functions expand path names: see `path.expand`.

`file.create` creates files with the given names if they do not already exist and truncates them if they do. They are created with the maximal read/write permissions allowed by the ‘umask’ setting (where relevant). By default a warning is given (with the reason) if the operation fails.

`file.exists` returns a logical vector indicating whether the files named by its argument exist. (Here ‘exists’ is in the sense of the system's `stat` call: a file will be reported as existing only if you have the permissions needed by `stat`. Existence can also be checked by `file.access`, which might use different permissions and so obtain a different result. Note that the existence of a file does not imply that it is readable: for that use `file.access`.) What constitutes a ‘file’ is system-dependent, but should include directories. (However, directory names must not include a trailing backslash or slash on Windows.) Note that if the file is a symbolic link on a Unix-alike, the result indicates if the link points to an actual file, not just if the link exists. Lastly, note the different function `exists` which checks for existence of R objects.

`file.remove` attempts to remove the files named in its argument. On most Unix platforms ‘file’ includes empty directories, symbolic links, fifos and sockets. On Windows, ‘file’ means a regular file and not, say, an empty directory.

`file.rename` attempts to rename files (and `from` and `to` must be of the same length). Where file permissions allow this will overwrite an existing element of `to`. This is subject to the limitations of the OS's corresponding system call (see something like `man 2 rename` on a Unix-alike): in particular in the interpretation of ‘file’: most platforms will not rename files from one file system to another. (On Windows, `file.rename` can rename files but not directories across volumes.) On platforms which allow directories to be renamed, typically neither or both of `from` and `to` must a directory, and if `to` exists it must be an empty directory.

`file.append` attempts to append the files named by its second argument to those named by its first. The R subscript recycling rule is used to align names given in vectors of different lengths.

`file.copy` works in a similar way to `file.append` but with the arguments in the natural order for copying. Copying to existing destination files is skipped unless `overwrite = TRUE`. The `to` argument can specify a single existing directory. If `copy.mode = TRUE` file read/write/execute permissions are copied where possible, restricted by ‘umask’. (On Windows this applies only to files.) Other security attributes such as ACLs are not copied. On a POSIX filesystem the targets of symbolic links will be copied rather than the links themselves, and hard links are copied separately. Using `copy.date = TRUE` may or may not copy the timestamp exactly (for example, fractional seconds may be omitted), but is more likely to do so as from R 3.4.0.

`file.symlink` and `file.link` make symbolic and hard links on those file systems which support them. For `file.symlink` the `to` argument can specify a single existing directory. (Unix and macOS native filesystems support both. Windows has hard links to files on NTFS file systems and concepts related to symbolic links on recent versions: see the section below on the Windows version of this help page. What happens on a FAT or SMB-mounted file system is OS-specific.)

### Value

These functions return a logical vector indicating which operation succeeded for each of the files attempted. Using a missing value for a file or path name will always be regarded as a failure.

If `showWarnings = TRUE`, `file.create` will give a warning for an unexpected failure.

### Case-insensitive file systems

Case-insensitive file systems are the norm on Windows and macOS, but can be found on all OSes (for example a FAT-formatted USB drive is probably case-insensitive).

These functions will most likely match existing files regardless of case on such file systems: however this is an OS function and it is possible that file names might be mapped to upper or lower case.

### Symbolic links on Windows

Symbolic links in the sense of POSIX file systems do not exist on Windows: however, NTFS file systems support two similar concepts.

There are ‘junctions’ (or ‘junction points’), unfortunately without a public API: a Windows version of the Unix concept of mounting one directory on another. A junction can link directories located on the same or different local volumes of the same computer, but cannot link to a network drive. Function `Sys.junction` creates one or more junctions: `to` should either specify a single existing directory or a set of non-existent file paths of the same length as `from`. (Command `mklink /J` can also be used to create junctions.)

A version of symbolic linking to files/directories was implemented more recently, and `file.symlink` makes use of that interface. However, it has restrictions which are crippling. First, the user needs permission to make symbolic links, and that permission is not normally granted except to Administrator accounts (note: not users with Administrator rights): further many users report that whereas the Policy Editor appears to be able to grant such rights, the API still reports insufficient permissions. Second, the interface needs to know if `from` is a file or a directory (and it need not yet exist): we have implemented this to allow linking from a directory only if it currently exists.

Care is needed with removing a junction (and most likely also a symbolic link): many tools will remove the target and its contents.

### Warning

Always check the return value of these functions when used in package code. This is especially important for `file.rename`, which has OS-specific restrictions (and note that the session temporary directory is commonly on a different file system from the working directory): it is only portable to use `file.rename` to change file name(s) within a single directory.

### Note

There is no guarantee that these functions will handle Windows relative paths of the form ‘d:path’: try ‘d:./path’ instead. In particular, ‘d:’ is not recognized as a directory. Nor are \\?\ prefixes (and similar) supported.

Most of these functions accept UTF-8 filepaths not valid in the current locale.

User error in supplying invalid file names (and note that ‘foo/’ and ‘foo\’ are invalid on Windows) has undefined consequences.

### Author(s)

Ross Ihaka, Brian Ripley

### See Also

`file.info`, `file.access`, `file.path`, `file.show`, `list.files`, `unlink`, `basename`, `path.expand`.

`dir.create`.

`Sys.glob` to expand wildcards in file specifications.

`file_test`, `Sys.readlink` (for ‘symlink’s).

https://en.wikipedia.org/wiki/Hard_link and https://en.wikipedia.org/wiki/Symbolic_link for the concepts of links and their limitations.

### Examples

    cat("file A\n", file = "A")
    cat("file B\n", file = "B")
    file.append("A", "B")
    file.create("A") # (trashing previous)
    file.append("A", rep("B", 10))
    if(interactive()) file.show("A") # -> the 10 lines from 'B'
    file.copy("A", "C")
    dir.create("tmp")
    file.copy(c("A", "B"), "tmp")
    list.files("tmp") # -> "A" and "B"
    unlink("tmp", recursive = TRUE)
    file.remove("A", "B", "C")

[Package base version 3.6.1 Index]