1% File src/library/base/man/file.info.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2021 R Core Team
4% Distributed under GPL 2 or later
5
6\name{file.info}
7\alias{file.info}
8\alias{file.mode}
9\alias{file.mtime}
10\alias{file.size}
11\title{Extract File Information}
12\description{
13  Utility function to extract information about files on the user's
14  file systems.
15}
16\usage{
17file.info(\dots, extra_cols = TRUE)
18
19file.mode(\dots)
20file.mtime(\dots)
21file.size(\dots)
22}
23\arguments{
24  \item{\dots}{character vectors containing file paths.  Tilde-expansion
25    is done: see \code{\link{path.expand}}.}
26  \item{extra_cols}{Logical: return all cols rather than just the
27    first six.}
28}
29\details{
30  What constitutes a \sQuote{file} is OS-dependent but includes
31  directories.  (However, directory names must not include a trailing
32  backslash or slash on Windows.)  See also the section in the help for
33  \code{\link{file.exists}} on case-insensitive file systems.
34
35  The file \sQuote{mode} follows POSIX conventions, giving three octal
36  digits summarizing the permissions for the file owner, the owner's
37  group and for anyone respectively.  Each digit is the logical
38  \emph{or} of read (4), write (2) and execute/search (1) permissions.
39
40  See \link{files} for how file paths with marked encodings are interpreted.
41
42#ifdef unix
43  On most systems symbolic links are followed, so information is given
44  about the file to which the link points rather than about the link.
45#endif
46#ifdef windows
47  File modes are probably only useful on NTFS file systems, and it seems
48  all three digits refer to the file's owner.
49  The execute/search bits are set for directories, and for files based
50  on their extensions (e.g., \file{.exe}, \file{.com}, \file{.cmd}
51  and \file{.bat} files).  \code{\link{file.access}} will give a more
52  reliable view of read/write access availability to the \R process.
53
54  UTF-8-encoded file names not valid in the current locale can be used.
55
56  Junction points and symbolic links are followed, so information is
57  given about the file/directory to which the link points rather than
58  about the link.
59#endif
60}
61\value{
62  For \code{file.info}, data frame with row names the file names and columns
63  \item{size}{double: File size in bytes.}
64  \item{isdir}{logical: Is the file a directory?}
65  \item{mode}{integer of class \code{"octmode"}.  The file permissions,
66    printed in octal, for example \code{644}.}
67  \item{mtime, ctime, atime}{object of class \code{"POSIXct"}:
68    file modification, \sQuote{last status change} and last access times.}
69#ifdef unix
70  \item{uid}{integer: the user ID of the file's owner.}
71  \item{gid}{integer: the group ID of the file's group.}
72  \item{uname}{character: \code{uid} interpreted as a user name.}
73  \item{grname}{character: \code{gid} interpreted as a group name.}
74  Unknown user and group names will be \code{NA}.
75#endif
76#ifdef windows
77  \item{exe}{character: what sort of executable is this?  Possible
78    values are \code{"no"}, \code{"msdos"}, \code{"win16"},
79    \code{"win32"}, \code{"win64"} and \code{"unknown"}.  Note that a
80    file (e.g., a script file) can be executable according to the mode
81    bits but not executable in this sense.}
82#endif
83
84  If \code{extra_cols} is false, only the first six columns are
85  returned: as these can all be found from a single C system call this
86  can be faster.  (However, properly configured systems will use a
87  \sQuote{name service cache daemon} to speed up the name lookups.)
88
89  Entries for non-existent or non-readable files will be \code{NA}.
90#ifdef unix
91  The \code{uid}, \code{gid}, \code{uname} and \code{grname} columns
92  may not be supplied on a non-POSIX Unix-alike system, and will not be
93  on Windows.
94#endif
95
96  What is meant by the three file times depends on the OS and file
97  system.  On Windows native file systems \code{ctime} is the file
98  creation time (something which is not recorded on most Unix-alike file
99  systems).  What is meant by \sQuote{file access} and hence the
100  \sQuote{last access time} is system-dependent.
101
102  The resolution of the file times depends on both the OS and the type
103  of the file system.  Modern file systems typically record times to an
104  accuracy of a microsecond or better: notable exceptions are HFS+ on
105  macOS (recorded in seconds) and modification time on older FAT systems
106  (recorded in increments of 2 seconds).  Note that \code{"POSIXct"}
107  times are by default printed in whole seconds: to change that see
108  \code{\link{strftime}}.
109
110  \code{file.mode}, \code{file.mtime} and \code{file.size} are
111  convenience wrappers returning just one of the columns.
112}
113#ifdef unix
114\note{
115  Some (now old) systems allow files of more than 2Gb to be created but
116  not accessed by the \code{stat} system call.  Such files may show up
117  as non-readable (and very likely not be readable by any of \R's input
118  functions).
119}
120#endif
121
122\seealso{
123  \code{\link{Sys.readlink}} to find out about symbolic links,
124  \code{\link{files}}, \code{\link{file.access}},
125  \code{\link{list.files}},
126  and \code{\link{DateTimeClasses}} for the date formats.
127
128  \code{\link{Sys.chmod}} to change permissions.
129}
130\examples{
131ncol(finf <- file.info(dir()))  # at least six
132\donttest{finf # the whole list}
133## Those that are more than 100 days old :
134finf <- file.info(dir(), extra_cols = FALSE)
135finf[difftime(Sys.time(), finf[,"mtime"], units = "days") > 100 , 1:4]
136
137file.info("no-such-file-exists")
138}
139\keyword{file}
140