# kyotocabinet::File Class Reference

Filesystem abstraction. More...

`#include <kcfile.h>`

List of all members.

## Classes

struct | Status
| Status information. More...

## Public Types

enum | OpenMode { OREADER = 1 << 0, OWRITER = 1 << 1, OCREATE = 1 << 2, OTRUNCATE = 1 << 3, ONOLOCK = 1 << 4, OTRYLOCK = 1 << 5 }
| Open modes. More...

## Public Member Functions

| File ()
| Default constructor.
| ~File ()
| Destructor.
const char * | error () const
| Get the last happened error information.
bool | open (const std::string &path, uint32_t mode=OWRITER|OCREATE, int64_t msiz=0)
| Open a file.
bool | close ()
| Close the file.
bool | write (int64_t off, const void *buf, size_t size)
| Write data.
bool | write (int64_t off, const std::string &str)
| Write data.
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.
bool | write_fast (int64_t off, const std::string &str)
| Write data with assuring the region does not spill from the file size.
bool | append (const void *buf, size_t size)
| Write data at the end of the file.
bool | append (const std::string &str)
| Write data at the end of the file.
bool | read (int64_t off, void *buf, size_t size)
| Read data.
bool | read (int64_t off, std::string *buf, size_t size)
| Read data.
bool | read_fast (int64_t off, void *buf, size_t size)
| Read data with assuring the region does not spill from the file size.
bool | read_fast (int64_t off, std::string *buf, size_t size)
| Read data.
bool | truncate (int64_t size)
| Truncate the file.
bool | synchronize (bool hard)
| Synchronize updated contents with the file and the device.
bool | refresh ()
| Refresh the internal state for update by others.
bool | begin_transaction (bool hard, int64_t off)
| Begin transaction.
bool | end_transaction (bool commit)
| End transaction.
bool | write_transaction (int64_t off, size_t size)
| Write a WAL message of transaction explicitly.
int64_t | size () const
| Get the size of the file.
std::string | path () const
| Get the path of the file.
bool | recovered () const
| Check whether the file was recovered or not.

## Static Public Member Functions

static char * | read_file (const std::string &path, int64_t *sp, int64_t limit=-1)
| Read the whole data from a file.
static bool | write_file (const std::string &path, const char *buf, int64_t size)
| Write the whole data into a file.
static bool | status (const std::string &path, Status *buf=NULL)
| Get the status information of a file.
static std::string | absolute_path (const std::string &path)
| Get the absolute path of a file.
static bool | remove (const std::string &path)
| Remove a file.
static bool | rename (const std::string &opath, const std::string &npath)
| Change the name or location of a file.
static bool | read_directory (const std::string &path, std::vector< std::string > *strvec)
| Read a directory.
static bool | make_directory (const std::string &path)
| Make a directory.
static bool | remove_directory (const std::string &path)
| Remove a directory.
static std::string | get_current_directory ()
| Get the path of the current working directory.
static bool | set_current_directory (const std::string &path)
| Set the current working directory.
static bool | synchronize_whole ()
| Synchronize the whole of the file system with the device.

## Static Public Attributes

static const char | PATHCHR
| Path delimiter character.
static const char *const | PATHSTR
| Path delimiter string.
static const char | EXTCHR
| Extension delimiter character.
static const char *const | EXTSTR
| Extension delimiter string.
static const char *const | CDIRSTR
| Current directory string.
static const char *const | PDIRSTR
| Parent directory string.

## Detailed Description

Filesystem abstraction.

## Member Enumeration Documentation

enum kyotocabinet::File::OpenMode

Open modes.

Enumerator:

  OREADER | open as a reader
  OWRITER | open as a writer
  OCREATE | writer creating
  OTRUNCATE | writer truncating
  ONOLOCK | open without locking
  OTRYLOCK | lock without blocking

## Constructor & Destructor Documentation

kyotocabinet::File::File | ( |  | ) | `[explicit]`

Default constructor.

kyotocabinet::File::~File | ( |  | ) |

Destructor.

Note:
  If the file is not closed, it is closed implicitly.

## Member Function Documentation

const char* kyotocabinet::File::error | ( |  | ) | const

Get the last happened error information.

Returns:
  the last happened error information.

bool kyotocabinet::File::open | ( | const std::string & | path,
|  | uint32_t | mode = `OWRITER|OCREATE`,
|  | int64_t | msiz = `0` |
| ) |  |  |

Open a file.

Parameters:

  | path | the path of a file.

  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.

  | msiz | the size of the internal memory-mapped region.

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::close | ( |  | ) |

Close the file.

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::write | ( | int64_t | off,
|  | const void * | buf,
|  | size_t | size |
| ) |  |  |

Write data.

Parameters:

  | off | the offset of the destination.
  | buf | the pointer to the data region.
  | size | the size of the data region.

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::write | ( | int64_t | off,
|  | const std::string & | str |
| ) |  |  |

Write data.

Note:
  Equal to the original File::write method except that the sigunature is different.

bool kyotocabinet::File::write_fast | ( | int64_t | off,
|  | const void * | buf,
|  | size_t | size |
| ) |  |  |

Write data with assuring the region does not spill from the file size.

Parameters:

  | off | the offset of the destination.
  | buf | the pointer to the data region.
  | size | the size of the data region.

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::write_fast | ( | int64_t | off,
|  | const std::string & | str |
| ) |  |  |

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 kyotocabinet::File::append | ( | const void * | buf,
|  | size_t | size |
| ) |  |  |

Write data at the end of the file.

Parameters:

  | buf | the pointer to the data region.
  | size | the size of the data region.

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::append | ( | const std::string & | str | ) |

Write data at the end of the file.

Note:
  Equal to the original File::append method except that the sigunature is different.

bool kyotocabinet::File::read | ( | int64_t | off,
|  | void * | buf,
|  | size_t | size |
| ) |  |  |

Read data.

Parameters:

  | off | the offset of the source.
  | buf | the pointer to the destination region.
  | size | the size of the data to be read.

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::read | ( | int64_t | off,
|  | std::string * | buf,
|  | size_t | size |
| ) |  |  |

Read data.

Note:
  Equal to the original File::read method except that the sigunature is different.

bool kyotocabinet::File::read_fast | ( | int64_t | off,
|  | void * | buf,
|  | size_t | size |
| ) |  |  |

Read data with assuring the region does not spill from the file size.

Parameters:

  | off | the offset of the source.
  | buf | the pointer to the destination region.
  | size | the size of the data to be read.

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::read_fast | ( | int64_t | off,
|  | std::string * | buf,
|  | size_t | size |
| ) |  |  |

Read data.

Note:
  Equal to the original File::read method except that the sigunature is different.

bool kyotocabinet::File::truncate | ( | int64_t | size | ) |

Truncate the file.

Parameters:

  | size | the new size of the file.

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::synchronize | ( | bool | hard | ) |

Synchronize updated contents with the file and the device.

Parameters:

  | hard | true for physical synchronization with the device, or false for logical synchronization with the file system.

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::refresh | ( |  | ) |

Refresh the internal state for update by others.

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::begin_transaction | ( | bool | hard,
|  | int64_t | off |
| ) |  |  |

Begin transaction.

Parameters:

  | hard | true for physical synchronization with the device, or false for logical synchronization with the file system.
  | off | the beginning offset of the guarded region

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::end_transaction | ( | bool | commit | ) |

End transaction.

Parameters:

  | commit | true to commit the transaction, or false to abort the transaction.

Returns:
  true on success, or false on failure.

bool kyotocabinet::File::write_transaction | ( | int64_t | off,
|  | size_t | size |
| ) |  |  |

Write a WAL message of transaction explicitly.

Parameters:

  | off | the offset of the source.
  | size | the size of the data to be read.

Returns:
  true on success, or false on failure.

int64_t kyotocabinet::File::size | ( |  | ) | const

Get the size of the file.

Returns:
  the size of the file, or 0 on failure.

std::string kyotocabinet::File::path | ( |  | ) | const

Get the path of the file.

Returns:
  the path of the file in bytes, or an empty string on failure.

bool kyotocabinet::File::recovered | ( |  | ) | const

Check whether the file was recovered or not.

Returns:
  true if recovered, or false if not.

static char* kyotocabinet::File::read_file | ( | const std::string & | path,
|  | int64_t * | sp,
|  | int64_t | limit = `-1` |
| ) |  |  | `[static]`

Read the whole data from a file.

Parameters:

  | path | the path of a file.
  | sp | the pointer to the variable into which the size of the region of the return value is assigned.
  | limit | the limit length to read. If it is nagative, no limit is specified.

Returns:
  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 bool kyotocabinet::File::write_file | ( | const std::string & | path,
|  | const char * | buf,
|  | int64_t | size |
| ) |  |  | `[static]`

Write the whole data into a file.

Parameters:

  | path | the path of a file.
  | buf | the data buffer to write.
  | size | the size of the data buffer.

Returns:
  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 kyotocabinet::File::status | ( | const std::string & | path,
|  | Status * | buf = `NULL` |
| ) |  |  | `[static]`

Get the status information of a file.

Parameters:

  | path | the path of a file.
  | buf | a structure of status information. If it is NULL, it is omitted.

Returns:
  true on success, or false on failure.

static std::string kyotocabinet::File::absolute_path | ( | const std::string & | path | ) | `[static]`

Get the absolute path of a file.

Parameters:

  | path | the path of a file.

Returns:
  the absolute path of the file, or an empty string on failure.

static bool kyotocabinet::File::remove | ( | const std::string & | path | ) | `[static]`

Remove a file.

Parameters:

  | path | the path of a file.

Returns:
  true on success, or false on failure.

static bool kyotocabinet::File::rename | ( | const std::string & | opath,
|  | const std::string & | npath |
| ) |  |  | `[static]`

Change the name or location of a file.

Parameters:

  | opath | the old path of a file.
  | npath | the new path of a file.

Returns:
  true on success, or false on failure.

static bool kyotocabinet::File::read_directory | ( | const std::string & | path,
|  | std::vector< std::string > * | strvec |
| ) |  |  | `[static]`

Read a directory.

Parameters:

  | path | the path of a directory.
  | strvec | a string list to contain the result.

Returns:
  true on success, or false on failure.

static bool kyotocabinet::File::make_directory | ( | const std::string & | path | ) | `[static]`

Make a directory.

Parameters:

  | path | the path of a directory.

Returns:
  true on success, or false on failure.

static bool kyotocabinet::File::remove_directory | ( | const std::string & | path | ) | `[static]`

Remove a directory.

Parameters:

  | path | the path of a directory.

Returns:
  true on success, or false on failure.

static std::string kyotocabinet::File::get_current_directory | ( |  | ) | `[static]`

Get the path of the current working directory.

Returns:
  the path of the current working directory, or an empty string on failure.

static bool kyotocabinet::File::set_current_directory | ( | const std::string & | path | ) | `[static]`

Set the current working directory.

Parameters:

  | path | the path of a directory.

Returns:
  true on success, or false on failure.

static bool kyotocabinet::File::synchronize_whole | ( |  | ) | `[static]`

Synchronize the whole of the file system with the device.

Returns:
  true on success, or false on failure.

## Member Data Documentation

const char kyotocabinet::File::PATHCHR`[static]`

Path delimiter character.

const char* const kyotocabinet::File::PATHSTR`[static]`

Path delimiter string.

const char kyotocabinet::File::EXTCHR`[static]`

Extension delimiter character.

const char* const kyotocabinet::File::EXTSTR`[static]`

Extension delimiter string.

const char* const kyotocabinet::File::CDIRSTR`[static]`

Current directory string.

const char* const kyotocabinet::File::PDIRSTR`[static]`

Parent directory string.