michael@0: // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: 
michael@0: // This file contains utility functions for dealing with the local
michael@0: // filesystem.
michael@0: 
michael@0: #ifndef BASE_FILE_UTIL_H_
michael@0: #define BASE_FILE_UTIL_H_
michael@0: 
michael@0: #include "build/build_config.h"
michael@0: 
michael@0: #if defined(OS_WIN)
michael@0: #include <windows.h>
michael@0: #elif defined(ANDROID)
michael@0: #include <sys/stat.h>
michael@0: #elif defined(OS_POSIX) 
michael@0: #include <sys/types.h>
michael@0: #include <fts.h>
michael@0: #include <sys/stat.h>
michael@0: #endif
michael@0: 
michael@0: #include <stdio.h>
michael@0: 
michael@0: #include <stack>
michael@0: #include <string>
michael@0: #include <vector>
michael@0: 
michael@0: #include "base/basictypes.h"
michael@0: #include "base/scoped_ptr.h"
michael@0: #include "base/file_path.h"
michael@0: 
michael@0: namespace file_util {
michael@0: 
michael@0: //-----------------------------------------------------------------------------
michael@0: // Functions that operate purely on a path string w/o touching the filesystem:
michael@0: 
michael@0: // Returns true if the given path ends with a path separator character.
michael@0: bool EndsWithSeparator(const FilePath& path);
michael@0: // These two versions are both deprecated. TODO(estade): remove them.
michael@0: bool EndsWithSeparator(std::wstring* path);
michael@0: bool EndsWithSeparator(const std::wstring& path);
michael@0: 
michael@0: // Modifies a string by trimming all trailing separators from the end.
michael@0: // Deprecated. FilePath does this automatically, and if it's constructed from a
michael@0: // path with a trailing separator, StripTrailingSeparators() may be used.
michael@0: void TrimTrailingSeparator(std::wstring* dir);
michael@0: 
michael@0: // Strips the topmost directory from the end of 'dir'.  Assumes 'dir' does not
michael@0: // refer to a file.
michael@0: // If 'dir' is a root directory, return without change.
michael@0: // Deprecated. Use FilePath::DirName instead.
michael@0: void UpOneDirectory(std::wstring* dir);
michael@0: 
michael@0: // Returns the filename portion of 'path', without any leading \'s or /'s.
michael@0: // Deprecated. Use FilePath::BaseName instead.
michael@0: std::wstring GetFilenameFromPath(const std::wstring& path);
michael@0: 
michael@0: // Deprecated compatibility function.  Use FilePath::Extension.
michael@0: FilePath::StringType GetFileExtensionFromPath(const FilePath& path);
michael@0: // Deprecated temporary compatibility function.
michael@0: std::wstring GetFileExtensionFromPath(const std::wstring& path);
michael@0: 
michael@0: // Appends new_ending to path, adding a separator between the two if necessary.
michael@0: void AppendToPath(std::wstring* path, const std::wstring& new_ending);
michael@0: 
michael@0: // Convert provided relative path into an absolute path.  Returns false on
michael@0: // error. On POSIX, this function fails if the path does not exist.
michael@0: bool AbsolutePath(FilePath* path);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool AbsolutePath(std::wstring* path);
michael@0: 
michael@0: // Deprecated compatibility function.  Use FilePath::InsertBeforeExtension.
michael@0: void InsertBeforeExtension(FilePath* path, const FilePath::StringType& suffix);
michael@0: 
michael@0: // Deprecated compatibility function.  Use FilePath::ReplaceExtension.
michael@0: void ReplaceExtension(FilePath* file_name,
michael@0:                       const FilePath::StringType& extension);
michael@0: 
michael@0: #if defined(OS_WIN)
michael@0: // Deprecated temporary compatibility functions.
michael@0: void InsertBeforeExtension(std::wstring* path, const std::wstring& suffix);
michael@0: void ReplaceExtension(std::wstring* file_name, const std::wstring& extension);
michael@0: #endif
michael@0: 
michael@0: //-----------------------------------------------------------------------------
michael@0: // Functions that involve filesystem access or modification:
michael@0: 
michael@0: // Deletes the given path, whether it's a file or a directory.
michael@0: // If it's a directory, it's perfectly happy to delete all of the
michael@0: // directory's contents.  Passing true to recursive deletes
michael@0: // subdirectories and their contents as well.
michael@0: // Returns true if successful, false otherwise.
michael@0: //
michael@0: // WARNING: USING THIS WITH recursive==true IS EQUIVALENT
michael@0: //          TO "rm -rf", SO USE WITH CAUTION.
michael@0: bool Delete(const FilePath& path, bool recursive);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool Delete(const std::wstring& path, bool recursive);
michael@0: 
michael@0: // Copies a single file. Use CopyDirectory to copy directories.
michael@0: bool CopyFile(const FilePath& from_path, const FilePath& to_path);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool CopyFile(const std::wstring& from_path, const std::wstring& to_path);
michael@0: 
michael@0: // Copies the given path, and optionally all subdirectories and their contents
michael@0: // as well.
michael@0: // If there are files existing under to_path, always overwrite.
michael@0: // Returns true if successful, false otherwise.
michael@0: // Dont't use wildcards on the names, it may stop working without notice.
michael@0: //
michael@0: // If you only need to copy a file use CopyFile, it's faster.
michael@0: bool CopyDirectory(const FilePath& from_path, const FilePath& to_path,
michael@0:                    bool recursive);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool CopyDirectory(const std::wstring& from_path, const std::wstring& to_path,
michael@0:                    bool recursive);
michael@0: 
michael@0: // Returns true if the given path exists on the local filesystem,
michael@0: // false otherwise.
michael@0: bool PathExists(const FilePath& path);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool PathExists(const std::wstring& path);
michael@0: 
michael@0: // Returns true if the given path is writable by the user, false otherwise.
michael@0: bool PathIsWritable(const FilePath& path);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool PathIsWritable(const std::wstring& path);
michael@0: 
michael@0: // Returns true if the given path exists and is a directory, false otherwise.
michael@0: bool DirectoryExists(const FilePath& path);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool DirectoryExists(const std::wstring& path);
michael@0: 
michael@0: #if defined(OS_POSIX)
michael@0: // Read exactly |bytes| bytes from file descriptor |fd|, storing the result
michael@0: // in |buffer|. This function is protected against EINTR and partial reads.
michael@0: // Returns true iff |bytes| bytes have been successfuly read from |fd|.
michael@0: bool ReadFromFD(int fd, char* buffer, size_t bytes);
michael@0: #endif  // defined(OS_POSIX)
michael@0: 
michael@0: // Get the temporary directory provided by the system.
michael@0: bool GetTempDir(FilePath* path);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool GetTempDir(std::wstring* path);
michael@0: // Get a temporary directory for shared memory files.
michael@0: // Only useful on POSIX; redirects to GetTempDir() on Windows.
michael@0: bool GetShmemTempDir(FilePath* path);
michael@0: 
michael@0: // Creates a temporary file. The full path is placed in |path|, and the
michael@0: // function returns true if was successful in creating the file. The file will
michael@0: // be empty and all handles closed after this function returns.
michael@0: // TODO(erikkay): rename this function and track down all of the callers.
michael@0: // (Clarification of erik's comment: the intent is to rename the BlahFileName()
michael@0: //  calls into BlahFile(), since they create temp files (not temp filenames).)
michael@0: bool CreateTemporaryFileName(FilePath* path);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool CreateTemporaryFileName(std::wstring* temp_file);
michael@0: 
michael@0: // Create and open a temporary file.  File is opened for read/write.
michael@0: // The full path is placed in |path|, and the function returns true if
michael@0: // was successful in creating and opening the file.
michael@0: FILE* CreateAndOpenTemporaryFile(FilePath* path);
michael@0: // Like above but for shmem files.  Only useful for POSIX.
michael@0: FILE* CreateAndOpenTemporaryShmemFile(FilePath* path);
michael@0: 
michael@0: // Similar to CreateAndOpenTemporaryFile, but the file is created in |dir|.
michael@0: FILE* CreateAndOpenTemporaryFileInDir(const FilePath& dir, FilePath* path);
michael@0: 
michael@0: // Same as CreateTemporaryFileName but the file is created in |dir|.
michael@0: bool CreateTemporaryFileNameInDir(const std::wstring& dir,
michael@0:                                   std::wstring* temp_file);
michael@0: 
michael@0: // Create a new directory under TempPath. If prefix is provided, the new
michael@0: // directory name is in the format of prefixyyyy.
michael@0: // NOTE: prefix is ignored in the POSIX implementation.
michael@0: // TODO(erikkay): is this OK?
michael@0: // If success, return true and output the full path of the directory created.
michael@0: bool CreateNewTempDirectory(const FilePath::StringType& prefix,
michael@0:                             FilePath* new_temp_path);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool CreateNewTempDirectory(const std::wstring& prefix,
michael@0:                             std::wstring* new_temp_path);
michael@0: 
michael@0: // Creates a directory, as well as creating any parent directories, if they
michael@0: // don't exist. Returns 'true' on successful creation, or if the directory
michael@0: // already exists.
michael@0: bool CreateDirectory(const FilePath& full_path);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool CreateDirectory(const std::wstring& full_path);
michael@0: 
michael@0: // Returns the file size. Returns true on success.
michael@0: bool GetFileSize(const FilePath& file_path, int64_t* file_size);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool GetFileSize(const std::wstring& file_path, int64_t* file_size);
michael@0: 
michael@0: // Used to hold information about a given file path.  See GetFileInfo below.
michael@0: struct FileInfo {
michael@0:   // The size of the file in bytes.  Undefined when is_directory is true.
michael@0:   int64_t size;
michael@0: 
michael@0:   // True if the file corresponds to a directory.
michael@0:   bool is_directory;
michael@0: 
michael@0:   // Add additional fields here as needed.
michael@0: };
michael@0: 
michael@0: // Returns information about the given file path.
michael@0: bool GetFileInfo(const FilePath& file_path, FileInfo* info);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool GetFileInfo(const std::wstring& file_path, FileInfo* info);
michael@0: 
michael@0: // Wrapper for fopen-like calls. Returns non-NULL FILE* on success.
michael@0: FILE* OpenFile(const FilePath& filename, const char* mode);
michael@0: // Deprecated temporary compatibility functions.
michael@0: FILE* OpenFile(const std::string& filename, const char* mode);
michael@0: FILE* OpenFile(const std::wstring& filename, const char* mode);
michael@0: 
michael@0: // Closes file opened by OpenFile. Returns true on success.
michael@0: bool CloseFile(FILE* file);
michael@0: 
michael@0: // Reads the given number of bytes from the file into the buffer.  Returns
michael@0: // the number of read bytes, or -1 on error.
michael@0: int ReadFile(const FilePath& filename, char* data, int size);
michael@0: // Deprecated temporary compatibility function.
michael@0: int ReadFile(const std::wstring& filename, char* data, int size);
michael@0: 
michael@0: // Writes the given buffer into the file, overwriting any data that was
michael@0: // previously there.  Returns the number of bytes written, or -1 on error.
michael@0: int WriteFile(const FilePath& filename, const char* data, int size);
michael@0: // Deprecated temporary compatibility function.
michael@0: int WriteFile(const std::wstring& filename, const char* data, int size);
michael@0: 
michael@0: // Gets the current working directory for the process.
michael@0: bool GetCurrentDirectory(FilePath* path);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool GetCurrentDirectory(std::wstring* path);
michael@0: 
michael@0: // Sets the current working directory for the process.
michael@0: bool SetCurrentDirectory(const FilePath& path);
michael@0: // Deprecated temporary compatibility function.
michael@0: bool SetCurrentDirectory(const std::wstring& current_directory);
michael@0: 
michael@0: }  // namespace file_util
michael@0: 
michael@0: #endif  // BASE_FILE_UTIL_H_