1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/sandbox/chromium/base/file_util.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,463 @@
1.4 +// Copyright (c) 2012 The Chromium Authors. All rights reserved.
1.5 +// Use of this source code is governed by a BSD-style license that can be
1.6 +// found in the LICENSE file.
1.7 +
1.8 +// This file contains utility functions for dealing with the local
1.9 +// filesystem.
1.10 +
1.11 +#ifndef BASE_FILE_UTIL_H_
1.12 +#define BASE_FILE_UTIL_H_
1.13 +
1.14 +#include "build/build_config.h"
1.15 +
1.16 +#if defined(OS_WIN)
1.17 +#include <windows.h>
1.18 +#elif defined(OS_POSIX)
1.19 +#include <sys/stat.h>
1.20 +#include <unistd.h>
1.21 +#endif
1.22 +
1.23 +#include <stdio.h>
1.24 +
1.25 +#include <set>
1.26 +#include <string>
1.27 +#include <vector>
1.28 +
1.29 +#include "base/base_export.h"
1.30 +#include "base/basictypes.h"
1.31 +#include "base/files/file_path.h"
1.32 +#include "base/memory/scoped_ptr.h"
1.33 +#include "base/platform_file.h"
1.34 +#include "base/strings/string16.h"
1.35 +
1.36 +#if defined(OS_POSIX)
1.37 +#include "base/file_descriptor_posix.h"
1.38 +#include "base/logging.h"
1.39 +#include "base/posix/eintr_wrapper.h"
1.40 +#endif
1.41 +
1.42 +namespace base {
1.43 +
1.44 +class Time;
1.45 +
1.46 +extern bool g_bug108724_debug;
1.47 +
1.48 +//-----------------------------------------------------------------------------
1.49 +// Functions that involve filesystem access or modification:
1.50 +
1.51 +// Returns an absolute version of a relative path. Returns an empty path on
1.52 +// error. On POSIX, this function fails if the path does not exist. This
1.53 +// function can result in I/O so it can be slow.
1.54 +BASE_EXPORT FilePath MakeAbsoluteFilePath(const FilePath& input);
1.55 +
1.56 +// Returns the total number of bytes used by all the files under |root_path|.
1.57 +// If the path does not exist the function returns 0.
1.58 +//
1.59 +// This function is implemented using the FileEnumerator class so it is not
1.60 +// particularly speedy in any platform.
1.61 +BASE_EXPORT int64 ComputeDirectorySize(const FilePath& root_path);
1.62 +
1.63 +// Deletes the given path, whether it's a file or a directory.
1.64 +// If it's a directory, it's perfectly happy to delete all of the
1.65 +// directory's contents. Passing true to recursive deletes
1.66 +// subdirectories and their contents as well.
1.67 +// Returns true if successful, false otherwise. It is considered successful
1.68 +// to attempt to delete a file that does not exist.
1.69 +//
1.70 +// In posix environment and if |path| is a symbolic link, this deletes only
1.71 +// the symlink. (even if the symlink points to a non-existent file)
1.72 +//
1.73 +// WARNING: USING THIS WITH recursive==true IS EQUIVALENT
1.74 +// TO "rm -rf", SO USE WITH CAUTION.
1.75 +BASE_EXPORT bool DeleteFile(const FilePath& path, bool recursive);
1.76 +
1.77 +#if defined(OS_WIN)
1.78 +// Schedules to delete the given path, whether it's a file or a directory, until
1.79 +// the operating system is restarted.
1.80 +// Note:
1.81 +// 1) The file/directory to be deleted should exist in a temp folder.
1.82 +// 2) The directory to be deleted must be empty.
1.83 +BASE_EXPORT bool DeleteFileAfterReboot(const FilePath& path);
1.84 +#endif
1.85 +
1.86 +// Moves the given path, whether it's a file or a directory.
1.87 +// If a simple rename is not possible, such as in the case where the paths are
1.88 +// on different volumes, this will attempt to copy and delete. Returns
1.89 +// true for success.
1.90 +// This function fails if either path contains traversal components ('..').
1.91 +BASE_EXPORT bool Move(const FilePath& from_path, const FilePath& to_path);
1.92 +
1.93 +// Renames file |from_path| to |to_path|. Both paths must be on the same
1.94 +// volume, or the function will fail. Destination file will be created
1.95 +// if it doesn't exist. Prefer this function over Move when dealing with
1.96 +// temporary files. On Windows it preserves attributes of the target file.
1.97 +// Returns true on success, leaving *error unchanged.
1.98 +// Returns false on failure and sets *error appropriately, if it is non-NULL.
1.99 +BASE_EXPORT bool ReplaceFile(const FilePath& from_path,
1.100 + const FilePath& to_path,
1.101 + PlatformFileError* error);
1.102 +
1.103 +// Copies a single file. Use CopyDirectory to copy directories.
1.104 +// This function fails if either path contains traversal components ('..').
1.105 +BASE_EXPORT bool CopyFile(const FilePath& from_path, const FilePath& to_path);
1.106 +
1.107 +// Copies the given path, and optionally all subdirectories and their contents
1.108 +// as well.
1.109 +//
1.110 +// If there are files existing under to_path, always overwrite. Returns true
1.111 +// if successful, false otherwise. Wildcards on the names are not supported.
1.112 +//
1.113 +// If you only need to copy a file use CopyFile, it's faster.
1.114 +BASE_EXPORT bool CopyDirectory(const FilePath& from_path,
1.115 + const FilePath& to_path,
1.116 + bool recursive);
1.117 +
1.118 +// Returns true if the given path exists on the local filesystem,
1.119 +// false otherwise.
1.120 +BASE_EXPORT bool PathExists(const FilePath& path);
1.121 +
1.122 +// Returns true if the given path is writable by the user, false otherwise.
1.123 +BASE_EXPORT bool PathIsWritable(const FilePath& path);
1.124 +
1.125 +// Returns true if the given path exists and is a directory, false otherwise.
1.126 +BASE_EXPORT bool DirectoryExists(const FilePath& path);
1.127 +
1.128 +// Returns true if the contents of the two files given are equal, false
1.129 +// otherwise. If either file can't be read, returns false.
1.130 +BASE_EXPORT bool ContentsEqual(const FilePath& filename1,
1.131 + const FilePath& filename2);
1.132 +
1.133 +// Returns true if the contents of the two text files given are equal, false
1.134 +// otherwise. This routine treats "\r\n" and "\n" as equivalent.
1.135 +BASE_EXPORT bool TextContentsEqual(const FilePath& filename1,
1.136 + const FilePath& filename2);
1.137 +
1.138 +// Read the file at |path| into |contents|, returning true on success.
1.139 +// This function fails if the |path| contains path traversal components ('..').
1.140 +// |contents| may be NULL, in which case this function is useful for its
1.141 +// side effect of priming the disk cache.
1.142 +// Useful for unit tests.
1.143 +BASE_EXPORT bool ReadFileToString(const FilePath& path, std::string* contents);
1.144 +
1.145 +} // namespace base
1.146 +
1.147 +// -----------------------------------------------------------------------------
1.148 +
1.149 +namespace file_util {
1.150 +
1.151 +#if defined(OS_POSIX)
1.152 +// Read exactly |bytes| bytes from file descriptor |fd|, storing the result
1.153 +// in |buffer|. This function is protected against EINTR and partial reads.
1.154 +// Returns true iff |bytes| bytes have been successfully read from |fd|.
1.155 +BASE_EXPORT bool ReadFromFD(int fd, char* buffer, size_t bytes);
1.156 +
1.157 +// Creates a symbolic link at |symlink| pointing to |target|. Returns
1.158 +// false on failure.
1.159 +BASE_EXPORT bool CreateSymbolicLink(const base::FilePath& target,
1.160 + const base::FilePath& symlink);
1.161 +
1.162 +// Reads the given |symlink| and returns where it points to in |target|.
1.163 +// Returns false upon failure.
1.164 +BASE_EXPORT bool ReadSymbolicLink(const base::FilePath& symlink,
1.165 + base::FilePath* target);
1.166 +
1.167 +// Bits ans masks of the file permission.
1.168 +enum FilePermissionBits {
1.169 + FILE_PERMISSION_MASK = S_IRWXU | S_IRWXG | S_IRWXO,
1.170 + FILE_PERMISSION_USER_MASK = S_IRWXU,
1.171 + FILE_PERMISSION_GROUP_MASK = S_IRWXG,
1.172 + FILE_PERMISSION_OTHERS_MASK = S_IRWXO,
1.173 +
1.174 + FILE_PERMISSION_READ_BY_USER = S_IRUSR,
1.175 + FILE_PERMISSION_WRITE_BY_USER = S_IWUSR,
1.176 + FILE_PERMISSION_EXECUTE_BY_USER = S_IXUSR,
1.177 + FILE_PERMISSION_READ_BY_GROUP = S_IRGRP,
1.178 + FILE_PERMISSION_WRITE_BY_GROUP = S_IWGRP,
1.179 + FILE_PERMISSION_EXECUTE_BY_GROUP = S_IXGRP,
1.180 + FILE_PERMISSION_READ_BY_OTHERS = S_IROTH,
1.181 + FILE_PERMISSION_WRITE_BY_OTHERS = S_IWOTH,
1.182 + FILE_PERMISSION_EXECUTE_BY_OTHERS = S_IXOTH,
1.183 +};
1.184 +
1.185 +// Reads the permission of the given |path|, storing the file permission
1.186 +// bits in |mode|. If |path| is symbolic link, |mode| is the permission of
1.187 +// a file which the symlink points to.
1.188 +BASE_EXPORT bool GetPosixFilePermissions(const base::FilePath& path,
1.189 + int* mode);
1.190 +// Sets the permission of the given |path|. If |path| is symbolic link, sets
1.191 +// the permission of a file which the symlink points to.
1.192 +BASE_EXPORT bool SetPosixFilePermissions(const base::FilePath& path,
1.193 + int mode);
1.194 +#endif // defined(OS_POSIX)
1.195 +
1.196 +// Return true if the given directory is empty
1.197 +BASE_EXPORT bool IsDirectoryEmpty(const base::FilePath& dir_path);
1.198 +
1.199 +// Get the temporary directory provided by the system.
1.200 +// WARNING: DON'T USE THIS. If you want to create a temporary file, use one of
1.201 +// the functions below.
1.202 +BASE_EXPORT bool GetTempDir(base::FilePath* path);
1.203 +// Get a temporary directory for shared memory files.
1.204 +// Only useful on POSIX; redirects to GetTempDir() on Windows.
1.205 +BASE_EXPORT bool GetShmemTempDir(base::FilePath* path, bool executable);
1.206 +
1.207 +// Get the home directory. This is more complicated than just getenv("HOME")
1.208 +// as it knows to fall back on getpwent() etc.
1.209 +BASE_EXPORT base::FilePath GetHomeDir();
1.210 +
1.211 +// Creates a temporary file. The full path is placed in |path|, and the
1.212 +// function returns true if was successful in creating the file. The file will
1.213 +// be empty and all handles closed after this function returns.
1.214 +BASE_EXPORT bool CreateTemporaryFile(base::FilePath* path);
1.215 +
1.216 +// Same as CreateTemporaryFile but the file is created in |dir|.
1.217 +BASE_EXPORT bool CreateTemporaryFileInDir(const base::FilePath& dir,
1.218 + base::FilePath* temp_file);
1.219 +
1.220 +// Create and open a temporary file. File is opened for read/write.
1.221 +// The full path is placed in |path|.
1.222 +// Returns a handle to the opened file or NULL if an error occurred.
1.223 +BASE_EXPORT FILE* CreateAndOpenTemporaryFile(base::FilePath* path);
1.224 +// Like above but for shmem files. Only useful for POSIX.
1.225 +// The executable flag says the file needs to support using
1.226 +// mprotect with PROT_EXEC after mapping.
1.227 +BASE_EXPORT FILE* CreateAndOpenTemporaryShmemFile(base::FilePath* path,
1.228 + bool executable);
1.229 +// Similar to CreateAndOpenTemporaryFile, but the file is created in |dir|.
1.230 +BASE_EXPORT FILE* CreateAndOpenTemporaryFileInDir(const base::FilePath& dir,
1.231 + base::FilePath* path);
1.232 +
1.233 +// Create a new directory. If prefix is provided, the new directory name is in
1.234 +// the format of prefixyyyy.
1.235 +// NOTE: prefix is ignored in the POSIX implementation.
1.236 +// If success, return true and output the full path of the directory created.
1.237 +BASE_EXPORT bool CreateNewTempDirectory(
1.238 + const base::FilePath::StringType& prefix,
1.239 + base::FilePath* new_temp_path);
1.240 +
1.241 +// Create a directory within another directory.
1.242 +// Extra characters will be appended to |prefix| to ensure that the
1.243 +// new directory does not have the same name as an existing directory.
1.244 +BASE_EXPORT bool CreateTemporaryDirInDir(
1.245 + const base::FilePath& base_dir,
1.246 + const base::FilePath::StringType& prefix,
1.247 + base::FilePath* new_dir);
1.248 +
1.249 +// Creates a directory, as well as creating any parent directories, if they
1.250 +// don't exist. Returns 'true' on successful creation, or if the directory
1.251 +// already exists. The directory is only readable by the current user.
1.252 +// Returns true on success, leaving *error unchanged.
1.253 +// Returns false on failure and sets *error appropriately, if it is non-NULL.
1.254 +BASE_EXPORT bool CreateDirectoryAndGetError(const base::FilePath& full_path,
1.255 + base::PlatformFileError* error);
1.256 +
1.257 +// Backward-compatible convenience method for the above.
1.258 +BASE_EXPORT bool CreateDirectory(const base::FilePath& full_path);
1.259 +
1.260 +// Returns the file size. Returns true on success.
1.261 +BASE_EXPORT bool GetFileSize(const base::FilePath& file_path, int64* file_size);
1.262 +
1.263 +// Sets |real_path| to |path| with symbolic links and junctions expanded.
1.264 +// On windows, make sure the path starts with a lettered drive.
1.265 +// |path| must reference a file. Function will fail if |path| points to
1.266 +// a directory or to a nonexistent path. On windows, this function will
1.267 +// fail if |path| is a junction or symlink that points to an empty file,
1.268 +// or if |real_path| would be longer than MAX_PATH characters.
1.269 +BASE_EXPORT bool NormalizeFilePath(const base::FilePath& path,
1.270 + base::FilePath* real_path);
1.271 +
1.272 +#if defined(OS_WIN)
1.273 +
1.274 +// Given a path in NT native form ("\Device\HarddiskVolumeXX\..."),
1.275 +// return in |drive_letter_path| the equivalent path that starts with
1.276 +// a drive letter ("C:\..."). Return false if no such path exists.
1.277 +BASE_EXPORT bool DevicePathToDriveLetterPath(const base::FilePath& device_path,
1.278 + base::FilePath* drive_letter_path);
1.279 +
1.280 +// Given an existing file in |path|, set |real_path| to the path
1.281 +// in native NT format, of the form "\Device\HarddiskVolumeXX\..".
1.282 +// Returns false if the path can not be found. Empty files cannot
1.283 +// be resolved with this function.
1.284 +BASE_EXPORT bool NormalizeToNativeFilePath(const base::FilePath& path,
1.285 + base::FilePath* nt_path);
1.286 +#endif
1.287 +
1.288 +// This function will return if the given file is a symlink or not.
1.289 +BASE_EXPORT bool IsLink(const base::FilePath& file_path);
1.290 +
1.291 +// Returns information about the given file path.
1.292 +BASE_EXPORT bool GetFileInfo(const base::FilePath& file_path,
1.293 + base::PlatformFileInfo* info);
1.294 +
1.295 +// Sets the time of the last access and the time of the last modification.
1.296 +BASE_EXPORT bool TouchFile(const base::FilePath& path,
1.297 + const base::Time& last_accessed,
1.298 + const base::Time& last_modified);
1.299 +
1.300 +// Set the time of the last modification. Useful for unit tests.
1.301 +BASE_EXPORT bool SetLastModifiedTime(const base::FilePath& path,
1.302 + const base::Time& last_modified);
1.303 +
1.304 +#if defined(OS_POSIX)
1.305 +// Store inode number of |path| in |inode|. Return true on success.
1.306 +BASE_EXPORT bool GetInode(const base::FilePath& path, ino_t* inode);
1.307 +#endif
1.308 +
1.309 +// Wrapper for fopen-like calls. Returns non-NULL FILE* on success.
1.310 +BASE_EXPORT FILE* OpenFile(const base::FilePath& filename, const char* mode);
1.311 +
1.312 +// Closes file opened by OpenFile. Returns true on success.
1.313 +BASE_EXPORT bool CloseFile(FILE* file);
1.314 +
1.315 +// Truncates an open file to end at the location of the current file pointer.
1.316 +// This is a cross-platform analog to Windows' SetEndOfFile() function.
1.317 +BASE_EXPORT bool TruncateFile(FILE* file);
1.318 +
1.319 +// Reads the given number of bytes from the file into the buffer. Returns
1.320 +// the number of read bytes, or -1 on error.
1.321 +BASE_EXPORT int ReadFile(const base::FilePath& filename, char* data, int size);
1.322 +
1.323 +// Writes the given buffer into the file, overwriting any data that was
1.324 +// previously there. Returns the number of bytes written, or -1 on error.
1.325 +BASE_EXPORT int WriteFile(const base::FilePath& filename, const char* data,
1.326 + int size);
1.327 +#if defined(OS_POSIX)
1.328 +// Append the data to |fd|. Does not close |fd| when done.
1.329 +BASE_EXPORT int WriteFileDescriptor(const int fd, const char* data, int size);
1.330 +#endif
1.331 +// Append the given buffer into the file. Returns the number of bytes written,
1.332 +// or -1 on error.
1.333 +BASE_EXPORT int AppendToFile(const base::FilePath& filename,
1.334 + const char* data, int size);
1.335 +
1.336 +// Gets the current working directory for the process.
1.337 +BASE_EXPORT bool GetCurrentDirectory(base::FilePath* path);
1.338 +
1.339 +// Sets the current working directory for the process.
1.340 +BASE_EXPORT bool SetCurrentDirectory(const base::FilePath& path);
1.341 +
1.342 +// Attempts to find a number that can be appended to the |path| to make it
1.343 +// unique. If |path| does not exist, 0 is returned. If it fails to find such
1.344 +// a number, -1 is returned. If |suffix| is not empty, also checks the
1.345 +// existence of it with the given suffix.
1.346 +BASE_EXPORT int GetUniquePathNumber(const base::FilePath& path,
1.347 + const base::FilePath::StringType& suffix);
1.348 +
1.349 +#if defined(OS_POSIX)
1.350 +// Creates a directory with a guaranteed unique name based on |path|, returning
1.351 +// the pathname if successful, or an empty path if there was an error creating
1.352 +// the directory. Does not create parent directories.
1.353 +BASE_EXPORT base::FilePath MakeUniqueDirectory(const base::FilePath& path);
1.354 +#endif
1.355 +
1.356 +#if defined(OS_POSIX)
1.357 +// Test that |path| can only be changed by a given user and members of
1.358 +// a given set of groups.
1.359 +// Specifically, test that all parts of |path| under (and including) |base|:
1.360 +// * Exist.
1.361 +// * Are owned by a specific user.
1.362 +// * Are not writable by all users.
1.363 +// * Are owned by a member of a given set of groups, or are not writable by
1.364 +// their group.
1.365 +// * Are not symbolic links.
1.366 +// This is useful for checking that a config file is administrator-controlled.
1.367 +// |base| must contain |path|.
1.368 +BASE_EXPORT bool VerifyPathControlledByUser(const base::FilePath& base,
1.369 + const base::FilePath& path,
1.370 + uid_t owner_uid,
1.371 + const std::set<gid_t>& group_gids);
1.372 +#endif // defined(OS_POSIX)
1.373 +
1.374 +#if defined(OS_MACOSX) && !defined(OS_IOS)
1.375 +// Is |path| writable only by a user with administrator privileges?
1.376 +// This function uses Mac OS conventions. The super user is assumed to have
1.377 +// uid 0, and the administrator group is assumed to be named "admin".
1.378 +// Testing that |path|, and every parent directory including the root of
1.379 +// the filesystem, are owned by the superuser, controlled by the group
1.380 +// "admin", are not writable by all users, and contain no symbolic links.
1.381 +// Will return false if |path| does not exist.
1.382 +BASE_EXPORT bool VerifyPathControlledByAdmin(const base::FilePath& path);
1.383 +#endif // defined(OS_MACOSX) && !defined(OS_IOS)
1.384 +
1.385 +// Returns the maximum length of path component on the volume containing
1.386 +// the directory |path|, in the number of FilePath::CharType, or -1 on failure.
1.387 +BASE_EXPORT int GetMaximumPathComponentLength(const base::FilePath& path);
1.388 +
1.389 +// A class to handle auto-closing of FILE*'s.
1.390 +class ScopedFILEClose {
1.391 + public:
1.392 + inline void operator()(FILE* x) const {
1.393 + if (x) {
1.394 + fclose(x);
1.395 + }
1.396 + }
1.397 +};
1.398 +
1.399 +typedef scoped_ptr_malloc<FILE, ScopedFILEClose> ScopedFILE;
1.400 +
1.401 +#if defined(OS_POSIX)
1.402 +// A class to handle auto-closing of FDs.
1.403 +class ScopedFDClose {
1.404 + public:
1.405 + inline void operator()(int* x) const {
1.406 + if (x && *x >= 0) {
1.407 + if (HANDLE_EINTR(close(*x)) < 0)
1.408 + DPLOG(ERROR) << "close";
1.409 + }
1.410 + }
1.411 +};
1.412 +
1.413 +typedef scoped_ptr_malloc<int, ScopedFDClose> ScopedFD;
1.414 +#endif // OS_POSIX
1.415 +
1.416 +#if defined(OS_LINUX)
1.417 +// Broad categories of file systems as returned by statfs() on Linux.
1.418 +enum FileSystemType {
1.419 + FILE_SYSTEM_UNKNOWN, // statfs failed.
1.420 + FILE_SYSTEM_0, // statfs.f_type == 0 means unknown, may indicate AFS.
1.421 + FILE_SYSTEM_ORDINARY, // on-disk filesystem like ext2
1.422 + FILE_SYSTEM_NFS,
1.423 + FILE_SYSTEM_SMB,
1.424 + FILE_SYSTEM_CODA,
1.425 + FILE_SYSTEM_MEMORY, // in-memory file system
1.426 + FILE_SYSTEM_CGROUP, // cgroup control.
1.427 + FILE_SYSTEM_OTHER, // any other value.
1.428 + FILE_SYSTEM_TYPE_COUNT
1.429 +};
1.430 +
1.431 +// Attempts determine the FileSystemType for |path|.
1.432 +// Returns false if |path| doesn't exist.
1.433 +BASE_EXPORT bool GetFileSystemType(const base::FilePath& path,
1.434 + FileSystemType* type);
1.435 +#endif
1.436 +
1.437 +} // namespace file_util
1.438 +
1.439 +// Internal --------------------------------------------------------------------
1.440 +
1.441 +namespace base {
1.442 +namespace internal {
1.443 +
1.444 +// Same as Move but allows paths with traversal components.
1.445 +// Use only with extreme care.
1.446 +BASE_EXPORT bool MoveUnsafe(const FilePath& from_path,
1.447 + const FilePath& to_path);
1.448 +
1.449 +// Same as CopyFile but allows paths with traversal components.
1.450 +// Use only with extreme care.
1.451 +BASE_EXPORT bool CopyFileUnsafe(const FilePath& from_path,
1.452 + const FilePath& to_path);
1.453 +
1.454 +#if defined(OS_WIN)
1.455 +// Copy from_path to to_path recursively and then delete from_path recursively.
1.456 +// Returns true if all operations succeed.
1.457 +// This function simulates Move(), but unlike Move() it works across volumes.
1.458 +// This function is not transactional.
1.459 +BASE_EXPORT bool CopyAndDeleteDirectory(const FilePath& from_path,
1.460 + const FilePath& to_path);
1.461 +#endif // defined(OS_WIN)
1.462 +
1.463 +} // namespace internal
1.464 +} // namespace base
1.465 +
1.466 +#endif // BASE_FILE_UTIL_H_
