/*************************************************************************************************
* Filesystem abstraction
* Copyright (C) 2009-2012 FAL Labs
* This file is part of Kyoto Cabinet.
* This program is free software: you can redistribute it and/or modify it under the terms of
* the GNU General Public License as published by the Free Software Foundation, either version
* 3 of the License, or any later version.
* This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
* without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
* See the GNU General Public License for more details.
* You should have received a copy of the GNU General Public License along with this program.
* If not, see <http://www.gnu.org/licenses/>.
*************************************************************************************************/
#ifndef _KCFILE_H // duplication check
#define _KCFILE_H
#include <kccommon.h>
#include <kcutil.h>
#include <kcthread.h>
namespace kyotocabinet { // common namespace
/**
* Filesystem abstraction.
*/
class File {
public:
struct Status;
public:
/** Path delimiter character. */
static const char PATHCHR;
/** Path delimiter string. */
static const char* const PATHSTR;
/** Extension delimiter character. */
static const char EXTCHR;
/** Extension delimiter string. */
static const char* const EXTSTR;
/** Current directory string. */
static const char* const CDIRSTR;
/** Parent directory string. */
static const char* const PDIRSTR;
/**
* Status information.
*/
struct Status {
bool isdir; ///< whether directory or not
int64_t size; ///< file size
int64_t mtime; ///< last modified time
};
/**
* Open modes.
*/
enum OpenMode {
OREADER = 1 << 0, ///< open as a reader
OWRITER = 1 << 1, ///< open as a writer
OCREATE = 1 << 2, ///< writer creating
OTRUNCATE = 1 << 3, ///< writer truncating
ONOLOCK = 1 << 4, ///< open without locking
OTRYLOCK = 1 << 5 ///< lock without blocking
};
/**
* Default constructor.
*/
explicit File();
/**
* Destructor.
* @note If the file is not closed, it is closed implicitly.
*/
~File();
/**
* Get the last happened error information.
* @return the last happened error information.
*/
const char* error() const;
/**
* Open a file.
* @param path the path of a file.
* @param mode the connection mode. File::OWRITER as a writer, File::OREADER as a reader.
* The following may be added to the writer mode by bitwise-or: File::OCREATE, which means it
* creates a new file if the file does not exist, File::OTRUNCATE, which means it creates a
* new file regardless if the file exists. The following may be added to both of the reader
* mode and the writer mode by bitwise-or: File::ONOLOCK, which means it opens the file
* without file locking, File::TRYLOCK, which means locking is performed without blocking.
* @param msiz the size of the internal memory-mapped region.
* @return true on success, or false on failure.
*/
bool open(const std::string& path, uint32_t mode = OWRITER | OCREATE, int64_t msiz = 0);
/**
* Close the file.
* @return true on success, or false on failure.
*/
bool close();
/**
* Write data.
* @param off the offset of the destination.
* @param buf the pointer to the data region.
* @param size the size of the data region.
* @return true on success, or false on failure.
*/
bool write(int64_t off, const void* buf, size_t size);
/**
* Write data.
* @note Equal to the original File::write method except that the sigunature is different.
*/
bool write(int64_t off, const std::string& str) {
_assert_(off >= 0);
return write(off, str.c_str(), str.size());
}
/**
* Write data with assuring the region does not spill from the file size.
* @param off the offset of the destination.
* @param buf the pointer to the data region.
* @param size the size of the data region.
* @return true on success, or false on failure.
*/
bool write_fast(int64_t off, const void* buf, size_t size);
/**
* Write data with assuring the region does not spill from the file size.
* @note Equal to the original File::write_fast method except that the sigunature is different.
*/
bool write_fast(int64_t off, const std::string& str) {
_assert_(off >= 0);
return write_fast(off, str.c_str(), str.size());
}
/**
* Write data at the end of the file.
* @param buf the pointer to the data region.
* @param size the size of the data region.
* @return true on success, or false on failure.
*/
bool append(const void* buf, size_t size);
/**
* Write data at the end of the file.
* @note Equal to the original File::append method except that the sigunature is different.
*/
bool append(const std::string& str) {
_assert_(true);
return append(str.c_str(), str.size());
}
/**
* Read data.
* @param off the offset of the source.
* @param buf the pointer to the destination region.
* @param size the size of the data to be read.
* @return true on success, or false on failure.
*/
bool read(int64_t off, void* buf, size_t size);
/**
* Read data.
* @note Equal to the original File::read method except that the sigunature is different.
*/
bool read(int64_t off, std::string* buf, size_t size) {
_assert_(off >= 0 && buf);
char* tbuf = new char[size];
if (!read(off, tbuf, size)) {
delete[] tbuf;
return false;
}
buf->append(std::string(tbuf, size));
delete[] tbuf;
return true;
}
/**
* Read data with assuring the region does not spill from the file size.
* @param off the offset of the source.
* @param buf the pointer to the destination region.
* @param size the size of the data to be read.
* @return true on success, or false on failure.
*/
bool read_fast(int64_t off, void* buf, size_t size);
/**
* Read data.
* @note Equal to the original File::read method except that the sigunature is different.
*/
bool read_fast(int64_t off, std::string* buf, size_t size) {
_assert_(off >= 0 && buf);
char* tbuf = new char[size];
if (!read_fast(off, tbuf, size)) {
delete[] tbuf;
return false;
}
buf->append(std::string(tbuf, size));
delete[] tbuf;
return true;
}
/**
* Truncate the file.
* @param size the new size of the file.
* @return true on success, or false on failure.
*/
bool truncate(int64_t size);
/**
* Synchronize updated contents with the file and the device.
* @param hard true for physical synchronization with the device, or false for logical
* synchronization with the file system.
* @return true on success, or false on failure.
*/
bool synchronize(bool hard);
/**
* Refresh the internal state for update by others.
* @return true on success, or false on failure.
*/
bool refresh();
/**
* Begin transaction.
* @param hard true for physical synchronization with the device, or false for logical
* synchronization with the file system.
* @param off the beginning offset of the guarded region
* @return true on success, or false on failure.
*/
bool begin_transaction(bool hard, int64_t off);
/**
* End transaction.
* @param commit true to commit the transaction, or false to abort the transaction.
* @return true on success, or false on failure.
*/
bool end_transaction(bool commit);
/**
* Write a WAL message of transaction explicitly.
* @param off the offset of the source.
* @param size the size of the data to be read.
* @return true on success, or false on failure.
*/
bool write_transaction(int64_t off, size_t size);
/**
* Get the size of the file.
* @return the size of the file, or 0 on failure.
*/
int64_t size() const;
/**
* Get the path of the file.
* @return the path of the file in bytes, or an empty string on failure.
*/
std::string path() const;
/**
* Check whether the file was recovered or not.
* @return true if recovered, or false if not.
*/
bool recovered() const;
/**
* Read the whole data from a file.
* @param path the path of a file.
* @param sp the pointer to the variable into which the size of the region of the return value
* is assigned.
* @param limit the limit length to read. If it is nagative, no limit is specified.
* @return the pointer to the region of the read data, or NULL on failure.
* @note Because an additional zero code is appended at the end of the region of the return
* value, the return value can be treated as a C-style string. Because the region of the
* return value is allocated with the the new[] operator, it should be released with the
* delete[] operator when it is no longer in use.
*/
static char* read_file(const std::string& path, int64_t* sp, int64_t limit = -1);
/**
* Write the whole data into a file.
* @param path the path of a file.
* @param buf the data buffer to write.
* @param size the size of the data buffer.
* @return true on success, or false on failure.
* @note The existing file corresponding to the path is overwritten. If no file corresponds
* to the path, a new file is created.
*/
static bool write_file(const std::string& path, const char* buf, int64_t size);
/**
* Get the status information of a file.
* @param path the path of a file.
* @param buf a structure of status information. If it is NULL, it is omitted.
* @return true on success, or false on failure.
*/
static bool status(const std::string& path, Status* buf = NULL);
/**
* Get the absolute path of a file.
* @param path the path of a file.
* @return the absolute path of the file, or an empty string on failure.
*/
static std::string absolute_path(const std::string& path);
/**
* Remove a file.
* @param path the path of a file.
* @return true on success, or false on failure.
*/
static bool remove(const std::string& path);
/**
* Change the name or location of a file.
* @param opath the old path of a file.
* @param npath the new path of a file.
* @return true on success, or false on failure.
*/
static bool rename(const std::string& opath, const std::string& npath);
/**
* Read a directory.
* @param path the path of a directory.
* @param strvec a string list to contain the result.
* @return true on success, or false on failure.
*/
static bool read_directory(const std::string& path, std::vector<std::string>* strvec);
/**
* Make a directory.
* @param path the path of a directory.
* @return true on success, or false on failure.
*/
static bool make_directory(const std::string& path);
/**
* Remove a directory.
* @param path the path of a directory.
* @return true on success, or false on failure.
*/
static bool remove_directory(const std::string& path);
/**
* Remove a file or a directory recursively.
* @param path the path of a file or a directory.
* @return true on success, or false on failure.
*/
static bool remove_recursively(const std::string& path);
/**
* Get the path of the current working directory.
* @return the path of the current working directory, or an empty string on failure.
*/
static std::string get_current_directory();
/**
* Set the current working directory.
* @param path the path of a directory.
* @return true on success, or false on failure.
*/
static bool set_current_directory(const std::string& path);
/**
* Synchronize the whole of the file system with the device.
* @return true on success, or false on failure.
*/
static bool synchronize_whole();
private:
/** Dummy constructor to forbid the use. */
File(const File&);
/** Dummy Operator to forbid the use. */
File& operator =(const File&);
/** Opaque pointer. */
void* opq_;
};
/**
* Directory stream abstraction.
*/
class DirStream {
public:
/**
* Default constructor.
*/
explicit DirStream();
/**
* Destructor.
* @note If the file is not closed, it is closed implicitly.
*/
~DirStream();
/**
* Open a directory.
* @param path the path of a directory.
* @return true on success, or false on failure.
*/
bool open(const std::string& path);
/**
* Close the file.
* @return true on success, or false on failure.
*/
bool close();
/**
* Read the next file in the directory.
* @param path a string to store the file path.
* @return true on success, or false on failure.
*/
bool read(std::string* path);
private:
/** Dummy constructor to forbid the use. */
DirStream(const DirStream&);
/** Dummy Operator to forbid the use. */
DirStream& operator =(const DirStream&);
/** Opaque pointer. */
void* opq_;
};
} // common namespace
#endif // duplication check
// END OF FILE