libs/glibmm2/glib/src/fileutils.hg

   1 /* $Id: fileutils.hg,v 1.3 2004/01/22 18:38:12 murrayc Exp $ */
   2
   3 /* Copyright (C) 2002 The gtkmm Development Team
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the Free
  17  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18  */
  19
  20 _DEFS(glibmm,glib)
  21
  22 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  23 extern "C" { typedef struct _GDir GDir; }
  24 #endif
  25
  26 #include <iterator>
  27 #include <string>
  28
  29 #include <glibmmconfig.h>
  30 #include <glibmm/error.h>
  31
  32 GLIBMM_USING_STD(input_iterator_tag)
  33 GLIBMM_USING_STD(string)
  34
  35
  36 namespace Glib
  37 {
  38
  39 _WRAP_ENUM(FileTest, GFileTest, NO_GTYPE)
  40
  41 /** @defgroup FileUtils File Utilities
  42  * Various file-related classes and functions.
  43  */
  44
  45 /** Exception class for file-related errors.
  46  * @ingroup FileUtils
  47  */
  48 _WRAP_GERROR(FileError, GFileError, G_FILE_ERROR, NO_GTYPE,
  49     s#^EXIST$#EXISTS#,
  50     s#^ISDIR$#IS_DIRECTORY#,
  51     s#^ACCES$#ACCESS_DENIED#,
  52     s#^NAMETOOLONG$#NAME_TOO_LONG#,
  53     s#^NOENT$#NO_SUCH_ENTITY#,
  54     s#^NOTDIR$#NOT_DIRECTORY#,
  55     s#^NXIO$#NO_SUCH_DEVICE#,
  56     s#^NODEV$#NOT_DEVICE#,
  57     s#^ROFS$#READONLY_FILESYSTEM#,
  58     s#^TXTBSY$#TEXT_FILE_BUSY#,
  59     s#^FAULT$#FAULTY_ADDRESS#,
  60     s#^LOOP$#SYMLINK_LOOP#,
  61     s#^NOSPC$#NO_SPACE_LEFT#,
  62     s#^NOMEM$#NOT_ENOUGH_MEMORY#,
  63     s#^MFILE$#TOO_MANY_OPEN_FILES#,
  64     s#^NFILE$#FILE_TABLE_OVERFLOW#,
  65     s#^BADF$#BAD_FILE_DESCRIPTOR#,
  66     s#^INVAL$#INVALID_ARGUMENT#,
  67     s#^PIPE$#BROKEN_PIPE#,
  68     s#^AGAIN$#TRYAGAIN#,
  69     s#^INTR$#INTERRUPTED#,
  70     s#^IO$#IO_ERROR#,
  71     s#^PERM$#NOT_OWNER#
  72 )
  73
  74 /** @enum FileError::Code
  75  * Values corresponding to <tt>errno</tt> codes returned from file operations
  76  * on UNIX.
  77  * Unlike <tt>errno</tt> codes, FileError::Code values are available on all
  78  * systems, even Windows. The exact meaning of each code depends on what sort
  79  * of file operation you were performing; the UNIX documentation gives more
  80  * details.  The following error code descriptions come from the GNU C Library
  81  * manual, and are under the copyright of that manual.
  82  *
  83  * It's not very portable to make detailed assumptions about exactly which
  84  * errors will be returned from a given operation. Some errors don't occur on
  85  * some systems, etc., sometimes there are subtle differences in when a system
  86  * will report a given error, etc.
  87  */
  88
  89 /** @var FileError::Code FileError::EXISTS
  90  * <tt>(EEXIST)</tt> Operation not permitted; only the owner of the file (or
  91  * other resource) or processes with special privileges can perform the operation.
  92  * <br><br>
  93  */
  94 /** @var FileError::Code FileError::IS_DIRECTORY
  95  * <tt>(EISDIR)</tt> File is a directory; you cannot open a directory for writing,
  96  * or create or remove hard links to it.
  97  * <br><br>
  98  */
  99 /** @var FileError::Code FileError::ACCESS_DENIED
 100  * <tt>(EACCES)</tt> Permission denied; the file permissions do not allow the
 101  * attempted operation.
 102  * <br><br>
 103  */
 104 /** @var FileError::Code FileError::NAME_TOO_LONG
 105  * <tt>(ENAMETOOLONG)</tt> Filename too long.
 106  * <br><br>
 107  */
 108 /** @var FileError::Code FileError::NO_SUCH_ENTITY
 109  * <tt>(ENOENT)</tt> No such file or directory.  This is a "file doesn't exist"
 110  * error for ordinary files that are referenced in contexts where they are expected
 111  * to already exist.
 112  * <br><br>
 113  */
 114 /** @var FileError::Code FileError::NOT_DIRECTORY
 115  * <tt>(ENOTDIR)</tt> A file that isn't a directory was specified when a directory
 116  * is required.
 117  * <br><br>
 118  */
 119 /** @var FileError::Code FileError::NO_SUCH_DEVICE
 120  * <tt>(ENXIO)</tt> No such device or address.  The system tried to use the device
 121  * represented by a file you specified, and it couldn't find the device. This can
 122  * mean that the device file was installed incorrectly, or that the physical device
 123  * is missing or not correctly attached to the computer.
 124  * <br><br>
 125  */
 126 /** @var FileError::Code FileError::NOT_DEVICE
 127  * <tt>(ENODEV)</tt> This file is of a type that doesn't support mapping.
 128  * <br><br>
 129  */
 130 /** @var FileError::Code FileError::READONLY_FILESYSTEM
 131  * <tt>(EROFS)</tt> The directory containing the new link can't be modified
 132  * because it's on a read-only file system.
 133  * <br><br>
 134  */
 135 /** @var FileError::Code FileError::TEXT_FILE_BUSY
 136  * <tt>(ETXTBSY)</tt> Text file busy.
 137  * <br><br>
 138  */
 139 /** @var FileError::Code FileError::FAULTY_ADDRESS
 140  * <tt>(EFAULT)</tt> You passed in a pointer to bad memory.  (Glib won't
 141  * reliably return this, don't pass in pointers to bad memory.)
 142  * <br><br>
 143  */
 144 /** @var FileError::Code FileError::SYMLINK_LOOP
 145  * <tt>(ELOOP)</tt> Too many levels of symbolic links were encountered in
 146  * looking up a file name.  This often indicates a cycle of symbolic links.
 147  * <br><br>
 148  */
 149 /** @var FileError::Code FileError::NO_SPACE_LEFT
 150  * <tt>(ENOSPC)</tt> No space left on device; write operation on a file failed
 151  * because the disk is full.
 152  * <br><br>
 153  */
 154 /** @var FileError::Code FileError::NOT_ENOUGH_MEMORY
 155  * <tt>(ENOMEM)</tt> No memory available.  The system cannot allocate more
 156  * virtual memory because its capacity is full.
 157  * <br><br>
 158  */
 159 /** @var FileError::Code FileError::TOO_MANY_OPEN_FILES
 160  * <tt>(EMFILE)</tt> The current process has too many files open and can't
 161  * open any more.  Duplicate descriptors do count toward this limit.
 162  * <br><br>
 163  */
 164 /** @var FileError::Code FileError::FILE_TABLE_OVERFLOW
 165  * <tt>(ENFILE)</tt> There are too many distinct file openings in the
 166  * entire system.
 167  * <br><br>
 168  */
 169 /** @var FileError::Code FileError::BAD_FILE_DESCRIPTOR
 170  * <tt>(EBADF)</tt> Bad file descriptor; for example, I/O on a descriptor
 171  * that has been closed or reading from a descriptor open only for writing
 172  * (or vice versa).
 173  * <br><br>
 174  */
 175 /** @var FileError::Code FileError::INVALID_ARGUMENT
 176  * <tt>(EINVAL)</tt> Invalid argument. This is used to indicate various kinds
 177  * of problems with passing the wrong argument to a library function.
 178  * <br><br>
 179  */
 180 /** @var FileError::Code FileError::BROKEN_PIPE
 181  * <tt>(EPIPE)</tt> Broken pipe; there is no process reading from the other
 182  * end of a pipe.  Every library function that returns this error code also
 183  * generates a <tt>SIGPIPE</tt> signal; this signal terminates the program
 184  * if not handled or blocked.  Thus, your program will never actually see
 185  * this code unless it has handled or blocked <tt>SIGPIPE</tt>.
 186  * <br><br>
 187  */
 188 /** @var FileError::Code FileError::TRYAGAIN
 189  * <tt>(EAGAIN)</tt> Resource temporarily unavailable; the call might work
 190  * if you try again later.
 191  * We used TRYAGAIN instead of TRY_AGAIN, because that is a defined as a macro by a Unix header.
 192  * <br><br>
 193  */
 194 /** @var FileError::Code FileError::INTERRUPTED
 195  * <tt>(EINTR)</tt> Interrupted function call; an asynchronous signal occurred
 196  * and prevented completion of the call.  When this happens, you should try
 197  * the call again.
 198  * <br><br>
 199  */
 200 /** @var FileError::Code FileError::IO_ERROR
 201  * <tt>(EIO)</tt> Input/output error; usually used for physical read or write
 202  * errors.  I.e. the disk or other physical device hardware is returning errors.
 203  * <br><br>
 204  */
 205 /** @var FileError::Code FileError::NOT_OWNER
 206  * <tt>(EPERM)</tt> Operation not permitted; only the owner of the file (or other
 207  * resource) or processes with special privileges can perform the operation.
 208  * <br><br>
 209  */
 210 /** @var FileError::Code FileError::FAILED
 211  * Does not correspond to a UNIX error code; this is the standard "failed for
 212  * unspecified reason" error code present in all Glib::Error error code
 213  * enumerations.  Returned if no specific code applies.
 214  */
 215
 216 class Dir;
 217
 218 /** The iterator type of Glib::Dir.
 219  * @ingroup FileUtils
 220  */
 221 class DirIterator
 222 {
 223 public:
 224   typedef std::input_iterator_tag   iterator_category;
 225   typedef std::string               value_type;
 226   typedef int                       difference_type;
 227   typedef value_type                reference;
 228   typedef void                      pointer;
 229
 230   DirIterator();
 231
 232 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 233   DirIterator(GDir* gobject, const char* current);
 234 #endif
 235
 236   std::string  operator*() const;
 237   DirIterator& operator++();
 238
 239   /** @note DirIterator has input iterator semantics, which means real
 240    * postfix increment is impossible. The return type is @c void to
 241    * prevent surprising behaviour.
 242    */
 243   void operator++(int);
 244
 245   bool operator==(const DirIterator& rhs) const;
 246   bool operator!=(const DirIterator& rhs) const;
 247
 248 private:
 249   GDir*       gobject_;
 250   const char* current_;
 251 };
 252
 253
 254 /** Utility class representing an open directory.
 255  * @ingroup FileUtils
 256  * It's highly recommended to use the iterator interface.  With iterators,
 257  * reading an entire directory into a STL container is really easy:
 258  * @code
 259  * Glib::Dir dir (directory_path);
 260  * std::list<std::string> entries (dir.begin(), dir.end());
 261  * @endcode
 262  * @note The encoding of the directory entries isn't necessarily UTF-8.
 263  * Use Glib::filename_to_utf8() if you need to display them.
 264  */
 265 class Dir
 266 {
 267 public:
 268   typedef DirIterator iterator;
 269   typedef DirIterator const_iterator;
 270
 271   /** Opens a directory for reading. The names of the files in the
 272    * directory can then be retrieved using read_name().
 273    * @param path The path to the directory you are interested in.
 274    * @throw Glib::FileError
 275    */
 276   explicit Dir(const std::string& path);
 277
 278 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 279   explicit Dir(GDir* gobject);
 280 #endif
 281
 282   /** Closes the directory and deallocates all related resources.
 283    */
 284   ~Dir();
 285
 286   /** Retrieves the name of the next entry in the directory.
 287    * The <tt>'.'</tt> and <tt>'..'</tt> entries are omitted.
 288    * @return The entry's name or <tt>""</tt> if there are no more entries.
 289    * @see begin(), end()
 290    */
 291   std::string read_name();
 292
 293   /** Resets the directory.  The next call to
 294    * read_name() will return the first entry again.
 295    */
 296   void rewind();
 297
 298   /** Closes the directory and deallocates all related resources.
 299    * Note that close() is implicitely called by ~Dir().  Thus you don't
 300    * need to call close() yourself unless you want to close the directory
 301    * before the destructor runs.
 302    */
 303   void close();
 304
 305   /** Get the begin of an input iterator sequence.
 306    * @return An input iterator pointing to the first directory entry.
 307    */
 308   DirIterator begin();
 309
 310   /** Get the end of an input iterator sequence.
 311    * @return An input iterator pointing behind the last directory entry.
 312    */
 313   DirIterator end();
 314
 315 private:
 316   GDir* gobject_;
 317
 318   // noncopyable
 319   Dir(const Dir&);
 320   Dir& operator=(const Dir&);
 321 };
 322
 323
 324 /** Returns @c true if any of the tests in the bitfield @a test are true.
 325  * @ingroup FileUtils
 326  * For example, <tt>(Glib::FILE_TEST_EXISTS | Glib::FILE_TEST_IS_DIR)</tt> will
 327  * return @c true if the file exists; the check whether it's a directory
 328  * doesn't matter since the existence test is true. With the current set of
 329  * available tests, there's no point passing in more than one test at a time.
 330  *
 331  * Apart from <tt>Glib::FILE_TEST_IS_SYMLINK</tt> all tests follow symbolic
 332  * links, so for a symbolic link to a regular file file_test() will return
 333  * @c true for both <tt>Glib::FILE_TEST_IS_SYMLINK</tt> and
 334  * <tt>Glib::FILE_TEST_IS_REGULAR</tt>.
 335  *
 336  * @note For a dangling symbolic link file_test() will return @c true for
 337  * <tt>Glib::FILE_TEST_IS_SYMLINK</tt> and @c false for all other flags.
 338  *
 339  * @param filename A filename to test.
 340  * @param test Bitfield of Glib::FileTest flags.
 341  * @return Whether a test was true.
 342  */
 343 bool file_test(const std::string& filename, FileTest test);
 344
 345 /** Opens a temporary file.
 346  * @ingroup FileUtils
 347  * See the %mkstemp() documentation on most UNIX-like systems. This is a
 348  * portability wrapper, which simply calls %mkstemp() on systems that have
 349  * it, and implements it in GLib otherwise.
 350  * @param filename_template A string that should match the rules for
 351  *   %mkstemp(), i.e. end in <tt>"XXXXXX"</tt>. The <tt>X</tt> string
 352  *   will be modified to form the name of a file that didn't exist.
 353  * @return A file handle (as from open()) to the file opened for reading
 354  *   and writing. The file is opened in binary mode on platforms where there
 355  *   is a difference. The file handle should be closed with close(). In
 356  *   case of errors, <tt>-1</tt> is returned.
 357  */
 358 int mkstemp(std::string& filename_template);
 359
 360 /** Opens a file for writing in the preferred directory for temporary files
 361  * (as returned by Glib::get_tmp_dir()).
 362  * @ingroup FileUtils
 363  * @a prefix should a basename template; it'll be suffixed by 6 characters
 364  * in order to form a unique filename.  No directory components are allowed.
 365  *
 366  * The actual name used is returned in @a name_used.
 367  *
 368  * @param prefix Template for file name, basename only.
 369  * @retval name_used The actual name used.
 370  * @return A file handle (as from <tt>open()</tt>) to the file opened for reading
 371  * and writing. The file is opened in binary mode on platforms where there is a
 372  * difference. The file handle should be closed with <tt>close()</tt>.
 373  * @throw Glib::FileError
 374  */
 375 int file_open_tmp(std::string& name_used, const std::string& prefix);
 376
 377 /** Opens a file for writing in the preferred directory for temporary files
 378  * (as returned by Glib::get_tmp_dir()).
 379  * @ingroup FileUtils
 380  * This function works like file_open_tmp(std::string&, const std::string&)
 381  * but uses a default basename prefix.
 382  *
 383  * @retval name_used The actual name used.
 384  * @return A file handle (as from <tt>open()</tt>) to the file opened for reading
 385  * and writing. The file is opened in binary mode on platforms where there is a
 386  * difference. The file handle should be closed with <tt>close()</tt>.
 387  * @throw Glib::FileError
 388  */
 389 int file_open_tmp(std::string& name_used);
 390
 391 /** Reads an entire file into a string, with good error checking.
 392  * @ingroup FileUtils
 393  * @param filename A file to read contents from.
 394  * @return The file contents.
 395  * @throw Glib::FileError
 396  */
 397 std::string file_get_contents(const std::string& filename);
 398
 399 } // namespace Glib
 400