File: kcfile.h

package info (click to toggle)
kyotocabinet 1.2.76-4
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 8,492 kB
  • ctags: 3,561
  • sloc: cpp: 59,347; ansic: 1,478; makefile: 1,207; ruby: 523; sh: 190; awk: 91; perl: 61
file content (388 lines) | stat: -rw-r--r-- 13,360 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
/*************************************************************************************************
 * 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