1 // Copyright 2014 The Chromium OS Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4
5 #ifndef LIBBRILLO_BRILLO_FILE_UTILS_H_
6 #define LIBBRILLO_BRILLO_FILE_UTILS_H_
7
8 #include <sys/types.h>
9
10 #include <string>
11
12 #include <base/files/file_path.h>
13 #include <base/files/scoped_file.h>
14 #include <brillo/brillo_export.h>
15 #include <brillo/secure_blob.h>
16
17 namespace brillo {
18
19 // Ensures a regular file owned by user |uid| and group |gid| exists at |path|.
20 // Any other entity at |path| will be deleted and replaced with an empty
21 // regular file. If a new file is needed, any missing parent directories will
22 // be created, and the file will be assigned |new_file_permissions|.
23 // Should be safe to use in all directories, including tmpdirs with the sticky
24 // bit set.
25 // Returns true if the file existed or was able to be created.
26 BRILLO_EXPORT bool TouchFile(const base::FilePath& path,
27 int new_file_permissions,
28 uid_t uid,
29 gid_t gid);
30
31 // Convenience version of TouchFile() defaulting to 600 permissions and the
32 // current euid/egid.
33 // Should be safe to use in all directories, including tmpdirs with the sticky
34 // bit set.
35 BRILLO_EXPORT bool TouchFile(const base::FilePath& path);
36
37 // Opens the absolute |path| to a regular file or directory ensuring that none
38 // of the path components are symbolic links and returns a FD. If |path| is
39 // relative, or contains any symbolic links, or points to a non-regular file or
40 // directory, an invalid FD is returned instead. |mode| is ignored unless
41 // |flags| has either O_CREAT or O_TMPFILE. Note that O_CLOEXEC is set so the
42 // file descriptor will not be inherited across exec calls.
43 //
44 // Parameters
45 // path - An absolute path of the file to open
46 // flags - Flags to pass to open.
47 // mode - Mode to pass to open.
48 BRILLO_EXPORT base::ScopedFD OpenSafely(const base::FilePath& path,
49 int flags,
50 mode_t mode);
51
52 // Opens the |path| relative to the |parent_fd| to a regular file or directory
53 // ensuring that none of the path components are symbolic links and returns a
54 // FD. If |path| contains any symbolic links, or points to a non-regular file or
55 // directory, an invalid FD is returned instead. |mode| is ignored unless
56 // |flags| has either O_CREAT or O_TMPFILE. Note that O_CLOEXEC is set so the
57 // file descriptor will not be inherited across exec calls.
58 //
59 // Parameters
60 // parent_fd - The file descriptor of the parent directory
61 // path - An absolute path of the file to open
62 // flags - Flags to pass to open.
63 // mode - Mode to pass to open.
64 BRILLO_EXPORT base::ScopedFD OpenAtSafely(int parent_fd,
65 const base::FilePath& path,
66 int flags,
67 mode_t mode);
68
69 // Opens the absolute |path| to a FIFO ensuring that none of the path components
70 // are symbolic links and returns a FD. If |path| is relative, or contains any
71 // symbolic links, or points to a non-regular file or directory, an invalid FD
72 // is returned instead. |mode| is ignored unless |flags| has either O_CREAT or
73 // O_TMPFILE.
74 //
75 // Parameters
76 // path - An absolute path of the file to open
77 // flags - Flags to pass to open.
78 // mode - Mode to pass to open.
79 BRILLO_EXPORT base::ScopedFD OpenFifoSafely(const base::FilePath& path,
80 int flags,
81 mode_t mode);
82
83 // Iterates through the path components and creates any missing ones. Guarantees
84 // the ancestor paths are not symlinks. This function returns an invalid FD on
85 // failure. Newly created directories will have |mode| permissions. The returned
86 // file descriptor was opened with both O_RDONLY and O_CLOEXEC.
87 //
88 // Parameters
89 // full_path - An absolute path of the directory to create and open.
90 BRILLO_EXPORT base::ScopedFD MkdirRecursively(const base::FilePath& full_path,
91 mode_t mode);
92
93 // Writes the entirety of the given data to |path| with 0640 permissions
94 // (modulo umask). If missing, parent (and parent of parent etc.) directories
95 // are created with 0700 permissions (modulo umask). Returns true on success.
96 //
97 // Parameters
98 // path - Path of the file to write
99 // blob/data - blob/string/array to populate from
100 // (size - array size)
101 BRILLO_EXPORT bool WriteStringToFile(const base::FilePath& path,
102 const std::string& data);
103 BRILLO_EXPORT bool WriteToFile(const base::FilePath& path,
104 const char* data,
105 size_t size);
106 template <class T>
WriteBlobToFile(const base::FilePath & path,const T & blob)107 BRILLO_EXPORT bool WriteBlobToFile(const base::FilePath& path, const T& blob) {
108 return WriteToFile(path, reinterpret_cast<const char*>(blob.data()),
109 blob.size());
110 }
111
112 // Calls fdatasync() on file if data_sync is true or fsync() on directory or
113 // file when data_sync is false. Returns true on success.
114 //
115 // Parameters
116 // path - File/directory to be sync'ed
117 // is_directory - True if |path| is a directory
118 // data_sync - True if |path| does not need metadata to be synced
119 BRILLO_EXPORT bool SyncFileOrDirectory(const base::FilePath& path,
120 bool is_directory,
121 bool data_sync);
122
123 // Atomically writes the entirety of the given data to |path| with |mode|
124 // permissions (modulo umask). If missing, parent (and parent of parent etc.)
125 // directories are created with 0700 permissions (modulo umask). Returns true
126 // if the file has been written successfully and it has physically hit the
127 // disk. Returns false if either writing the file has failed or if it cannot
128 // be guaranteed that it has hit the disk.
129 //
130 // Parameters
131 // path - Path of the file to write
132 // blob/data - blob/array to populate from
133 // (size - array size)
134 // mode - File permission bit-pattern, eg. 0644 for rw-r--r--
135 BRILLO_EXPORT bool WriteToFileAtomic(const base::FilePath& path,
136 const char* data,
137 size_t size,
138 mode_t mode);
139 template <class T>
WriteBlobToFileAtomic(const base::FilePath & path,const T & blob,mode_t mode)140 BRILLO_EXPORT bool WriteBlobToFileAtomic(const base::FilePath& path,
141 const T& blob,
142 mode_t mode) {
143 return WriteToFileAtomic(path, reinterpret_cast<const char*>(blob.data()),
144 blob.size(), mode);
145 }
146
147 // ComputeDirectoryDiskUsage() is similar to base::ComputeDirectorySize() in
148 // libbase, but it returns the actual disk usage instead of the apparent size.
149 // In another word, ComputeDirectoryDiskUsage() behaves like "du -s
150 // --apparent-size", and ComputeDirectorySize() behaves like "du -s". The
151 // primary difference is that sparse file and files on filesystem with
152 // transparent compression will report smaller file size than
153 // ComputeDirectorySize(). Returns the total used bytes.
154 // The following behaviours of this function is guaranteed and is verified by
155 // unit tests:
156 // - This function recursively processes directory down the tree, so disk space
157 // used by files in all the subdirectories are counted.
158 // - Symbolic links will not be followed (the size of link itself is counted,
159 // the target is not)
160 // - Hidden files are counted as well.
161 // The following behaviours are not guaranteed, and it is recommended to avoid
162 // them in the field. Their current behaviour is provided for reference only:
163 // - This function doesn't care about filesystem boundaries, so it'll cross
164 // filesystem boundary to count file size if there's one in the specified
165 // directory.
166 // - Hard links will be treated like normal files, so they could be
167 // over-reported.
168 // - Directories that the current user doesn't have permission to list/stat will
169 // be ignored, and an error will be logged but the returned result could be
170 // under-reported without error in the returned value.
171 // - Deduplication (should the filesystem support it) is ignored, and the result
172 // could be over-reported.
173 // - Doesn't check if |root_path| exists, a non-existent directory will results
174 // in 0 bytes without any error.
175 // - There are no limit on the depth of file system tree, the program will crash
176 // if it run out of memory to hold the entire depth of file system tree.
177 // - If the directory is modified during this function call, there's no
178 // guarantee on if the function will count the updated or original file system
179 // state. The function could choose to count the updated state for one file and
180 // original state for another file.
181 // - Non-POSIX system is not supported.
182 // - Disk space used by directory (and its subdirectories) itself is counted.
183 //
184 // Parameters
185 // root_path - The directory to compute the size for
186 BRILLO_EXPORT int64_t
187 ComputeDirectoryDiskUsage(const base::FilePath& root_path);
188
189 } // namespace brillo
190
191 #endif // LIBBRILLO_BRILLO_FILE_UTILS_H_
192