1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY! 2 #ifndef _GLIBMM_FILEUTILS_H 3 #define _GLIBMM_FILEUTILS_H 4 5 6 /* Copyright (C) 2002 The gtkmm Development Team 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 23 #ifndef DOXYGEN_SHOULD_SKIP_THIS 24 extern "C" { typedef struct _GDir GDir; } 25 #endif 26 27 #include <glibmm/error.h> 28 #include <iterator> 29 #include <string> 30 31 namespace Glib 32 { 33 34 /** @addtogroup glibmmEnums glibmm Enums and Flags */ 35 36 /** 37 * @var FileTest FILE_TEST_IS_REGULAR 38 * <tt>true</tt> if the file is a regular file 39 * (not a directory). Note that this test will also return <tt>true</tt> 40 * if the tested file is a symlink to a regular file. 41 * 42 * @var FileTest FILE_TEST_IS_SYMLINK 43 * <tt>true</tt> if the file is a symlink. 44 * 45 * @var FileTest FILE_TEST_IS_DIR 46 * <tt>true</tt> if the file is a directory. 47 * 48 * @var FileTest FILE_TEST_IS_EXECUTABLE 49 * <tt>true</tt> if the file is executable. 50 * 51 * @var FileTest FILE_TEST_EXISTS 52 * <tt>true</tt> if the file exists. It may or may not 53 * be a regular file. 54 * 55 * @enum FileTest 56 * 57 * A test to perform on a file using g_file_test(). 58 * 59 * @ingroup glibmmEnums 60 * @par Bitwise operators: 61 * <tt>%FileTest operator|(FileTest, FileTest)</tt><br> 62 * <tt>%FileTest operator&(FileTest, FileTest)</tt><br> 63 * <tt>%FileTest operator^(FileTest, FileTest)</tt><br> 64 * <tt>%FileTest operator~(FileTest)</tt><br> 65 * <tt>%FileTest& operator|=(FileTest&, FileTest)</tt><br> 66 * <tt>%FileTest& operator&=(FileTest&, FileTest)</tt><br> 67 * <tt>%FileTest& operator^=(FileTest&, FileTest)</tt><br> 68 */ 69 enum FileTest 70 { 71 FILE_TEST_IS_REGULAR = 1 << 0, 72 FILE_TEST_IS_SYMLINK = 1 << 1, 73 FILE_TEST_IS_DIR = 1 << 2, 74 FILE_TEST_IS_EXECUTABLE = 1 << 3, 75 FILE_TEST_EXISTS = 1 << 4 76 }; 77 78 /** @ingroup glibmmEnums */ 79 inline FileTest operator|(FileTest lhs, FileTest rhs) 80 { return static_cast<FileTest>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); } 81 82 /** @ingroup glibmmEnums */ 83 inline FileTest operator&(FileTest lhs, FileTest rhs) 84 { return static_cast<FileTest>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); } 85 86 /** @ingroup glibmmEnums */ 87 inline FileTest operator^(FileTest lhs, FileTest rhs) 88 { return static_cast<FileTest>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); } 89 90 /** @ingroup glibmmEnums */ 91 inline FileTest operator~(FileTest flags) 92 { return static_cast<FileTest>(~static_cast<unsigned>(flags)); } 93 94 /** @ingroup glibmmEnums */ 95 inline FileTest& operator|=(FileTest& lhs, FileTest rhs) 96 { return (lhs = static_cast<FileTest>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); } 97 98 /** @ingroup glibmmEnums */ 99 inline FileTest& operator&=(FileTest& lhs, FileTest rhs) 100 { return (lhs = static_cast<FileTest>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); } 101 102 /** @ingroup glibmmEnums */ 103 inline FileTest& operator^=(FileTest& lhs, FileTest rhs) 104 { return (lhs = static_cast<FileTest>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); } 105 106 107 /** @defgroup FileUtils File Utilities 108 * Various file-related classes and functions. 109 */ 110 111 /** %Exception class for file-related errors. 112 * @ingroup FileUtils 113 */ 114 class GLIBMM_API FileError : public Glib::Error 115 { 116 public: 117 /** @var Code EXISTS 118 * Operation not permitted; only the owner of 119 * the file (or other resource) or processes with special privileges 120 * can perform the operation. 121 * 122 * @var Code IS_DIRECTORY 123 * File is a directory; you cannot open a directory 124 * for writing, or create or remove hard links to it. 125 * 126 * @var Code ACCESS_DENIED 127 * Permission denied; the file permissions do not 128 * allow the attempted operation. 129 * 130 * @var Code NAME_TOO_LONG 131 * Filename too long. 132 * 133 * @var Code NO_SUCH_ENTITY 134 * No such file or directory. This is a "file 135 * doesn't exist" error for ordinary files that are referenced in 136 * contexts where they are expected to already exist. 137 * 138 * @var Code NOT_DIRECTORY 139 * A file that isn't a directory was specified when 140 * a directory is required. 141 * 142 * @var Code NO_SUCH_DEVICE 143 * No such device or address. The system tried to 144 * use the device represented by a file you specified, and it 145 * couldn't find the device. This can mean that the device file was 146 * installed incorrectly, or that the physical device is missing or 147 * not correctly attached to the computer. 148 * 149 * @var Code NOT_DEVICE 150 * The underlying file system of the specified file 151 * does not support memory mapping. 152 * 153 * @var Code READONLY_FILESYSTEM 154 * The directory containing the new link can't be 155 * modified because it's on a read-only file system. 156 * 157 * @var Code TEXT_FILE_BUSY 158 * Text file busy. 159 * 160 * @var Code FAULTY_ADDRESS 161 * You passed in a pointer to bad memory. 162 * (GLib won't reliably return this, don't pass in pointers to bad 163 * memory.). 164 * 165 * @var Code SYMLINK_LOOP 166 * Too many levels of symbolic links were encountered 167 * in looking up a file name. This often indicates a cycle of symbolic 168 * links. 169 * 170 * @var Code NO_SPACE_LEFT 171 * No space left on device; write operation on a 172 * file failed because the disk is full. 173 * 174 * @var Code NOT_ENOUGH_MEMORY 175 * No memory available. The system cannot allocate 176 * more virtual memory because its capacity is full. 177 * 178 * @var Code TOO_MANY_OPEN_FILES 179 * The current process has too many files open and 180 * can't open any more. Duplicate descriptors do count toward this 181 * limit. 182 * 183 * @var Code FILE_TABLE_OVERFLOW 184 * There are too many distinct file openings in the 185 * entire system. 186 * 187 * @var Code BAD_FILE_DESCRIPTOR 188 * Bad file descriptor; for example, I/O on a 189 * descriptor that has been closed or reading from a descriptor open 190 * only for writing (or vice versa). 191 * 192 * @var Code INVALID_ARGUMENT 193 * Invalid argument. This is used to indicate 194 * various kinds of problems with passing the wrong argument to a 195 * library function. 196 * 197 * @var Code BROKEN_PIPE 198 * Broken pipe; there is no process reading from the 199 * other end of a pipe. Every library function that returns this 200 * error code also generates a 'SIGPIPE' signal; this signal 201 * terminates the program if not handled or blocked. Thus, your 202 * program will never actually see this code unless it has handled 203 * or blocked 'SIGPIPE'. 204 * 205 * @var Code TRYAGAIN 206 * Resource temporarily unavailable; the call might 207 * work if you try again later. 208 * 209 * @var Code INTERRUPTED 210 * Interrupted function call; an asynchronous signal 211 * occurred and prevented completion of the call. When this 212 * happens, you should try the call again. 213 * 214 * @var Code IO_ERROR 215 * Input/output error; usually used for physical read 216 * or write errors. i.e. the disk or other physical device hardware 217 * is returning errors. 218 * 219 * @var Code NOT_OWNER 220 * Operation not permitted; only the owner of the 221 * file (or other resource) or processes with special privileges can 222 * perform the operation. 223 * 224 * @var Code NOSYS 225 * Function not implemented; this indicates that 226 * the system is missing some functionality. 227 * 228 * @var Code FAILED 229 * Does not correspond to a UNIX error code; this 230 * is the standard "failed for unspecified reason" error code present 231 * in all Error error code enumerations. Returned if no specific 232 * code applies. 233 * 234 * @enum Code 235 * 236 * Values corresponding to @a errno codes returned from file operations 237 * on UNIX. Unlike @a errno codes, GFileError values are available on 238 * all systems, even Windows. The exact meaning of each code depends 239 * on what sort of file operation you were performing; the UNIX 240 * documentation gives more details. The following error code descriptions 241 * come from the GNU C Library manual, and are under the copyright 242 * of that manual. 243 * 244 * It's not very portable to make detailed assumptions about exactly 245 * which errors will be returned from a given operation. Some errors 246 * don't occur on some systems, etc., sometimes there are subtle 247 * differences in when a system will report a given error, etc. 248 */ 249 enum Code 250 { 251 EXISTS, 252 IS_DIRECTORY, 253 ACCESS_DENIED, 254 NAME_TOO_LONG, 255 NO_SUCH_ENTITY, 256 NOT_DIRECTORY, 257 NO_SUCH_DEVICE, 258 NOT_DEVICE, 259 READONLY_FILESYSTEM, 260 TEXT_FILE_BUSY, 261 FAULTY_ADDRESS, 262 SYMLINK_LOOP, 263 NO_SPACE_LEFT, 264 NOT_ENOUGH_MEMORY, 265 TOO_MANY_OPEN_FILES, 266 FILE_TABLE_OVERFLOW, 267 BAD_FILE_DESCRIPTOR, 268 INVALID_ARGUMENT, 269 BROKEN_PIPE, 270 TRYAGAIN, 271 INTERRUPTED, 272 IO_ERROR, 273 NOT_OWNER, 274 NOSYS, 275 FAILED 276 }; 277 278 FileError(Code error_code, const Glib::ustring& error_message); 279 explicit FileError(GError* gobject); 280 Code code() const; 281 282 #ifndef DOXYGEN_SHOULD_SKIP_THIS 283 private: 284 285 static void throw_func(GError* gobject); 286 287 friend GLIBMM_API void wrap_init(); // uses throw_func() 288 289 #endif //DOXYGEN_SHOULD_SKIP_THIS 290 }; 291 292 293 /** @enum FileError::Code 294 * Values corresponding to <tt>errno</tt> codes returned from file operations 295 * on UNIX. 296 * Unlike <tt>errno</tt> codes, FileError::Code values are available on all 297 * systems, even Windows. The exact meaning of each code depends on what sort 298 * of file operation you were performing; the UNIX documentation gives more 299 * details. The following error code descriptions come from the GNU C Library 300 * manual, and are under the copyright of that manual. 301 * 302 * It's not very portable to make detailed assumptions about exactly which 303 * errors will be returned from a given operation. Some errors don't occur on 304 * some systems, etc., sometimes there are subtle differences in when a system 305 * will report a given error, etc. 306 */ 307 308 /** @var FileError::Code FileError::EXISTS 309 * <tt>(EEXIST)</tt> Operation not permitted; only the owner of the file (or 310 * other resource) or processes with special privileges can perform the operation. 311 * <br><br> 312 */ 313 /** @var FileError::Code FileError::IS_DIRECTORY 314 * <tt>(EISDIR)</tt> File is a directory; you cannot open a directory for writing, 315 * or create or remove hard links to it. 316 * <br><br> 317 */ 318 /** @var FileError::Code FileError::ACCESS_DENIED 319 * <tt>(EACCES)</tt> Permission denied; the file permissions do not allow the 320 * attempted operation. 321 * <br><br> 322 */ 323 /** @var FileError::Code FileError::NAME_TOO_LONG 324 * <tt>(ENAMETOOLONG)</tt> Filename too long. 325 * <br><br> 326 */ 327 /** @var FileError::Code FileError::NO_SUCH_ENTITY 328 * <tt>(ENOENT)</tt> No such file or directory. This is a "file doesn't exist" 329 * error for ordinary files that are referenced in contexts where they are expected 330 * to already exist. 331 * <br><br> 332 */ 333 /** @var FileError::Code FileError::NOT_DIRECTORY 334 * <tt>(ENOTDIR)</tt> A file that isn't a directory was specified when a directory 335 * is required. 336 * <br><br> 337 */ 338 /** @var FileError::Code FileError::NO_SUCH_DEVICE 339 * <tt>(ENXIO)</tt> No such device or address. The system tried to use the device 340 * represented by a file you specified, and it couldn't find the device. This can 341 * mean that the device file was installed incorrectly, or that the physical device 342 * is missing or not correctly attached to the computer. 343 * <br><br> 344 */ 345 /** @var FileError::Code FileError::NOT_DEVICE 346 * <tt>(ENODEV)</tt> This file is of a type that doesn't support mapping. 347 * <br><br> 348 */ 349 /** @var FileError::Code FileError::READONLY_FILESYSTEM 350 * <tt>(EROFS)</tt> The directory containing the new link can't be modified 351 * because it's on a read-only file system. 352 * <br><br> 353 */ 354 /** @var FileError::Code FileError::TEXT_FILE_BUSY 355 * <tt>(ETXTBSY)</tt> Text file busy. 356 * <br><br> 357 */ 358 /** @var FileError::Code FileError::FAULTY_ADDRESS 359 * <tt>(EFAULT)</tt> You passed in a pointer to bad memory. (Glib won't 360 * reliably return this, don't pass in pointers to bad memory.) 361 * <br><br> 362 */ 363 /** @var FileError::Code FileError::SYMLINK_LOOP 364 * <tt>(ELOOP)</tt> Too many levels of symbolic links were encountered in 365 * looking up a file name. This often indicates a cycle of symbolic links. 366 * <br><br> 367 */ 368 /** @var FileError::Code FileError::NO_SPACE_LEFT 369 * <tt>(ENOSPC)</tt> No space left on device; write operation on a file failed 370 * because the disk is full. 371 * <br><br> 372 */ 373 /** @var FileError::Code FileError::NOT_ENOUGH_MEMORY 374 * <tt>(ENOMEM)</tt> No memory available. The system cannot allocate more 375 * virtual memory because its capacity is full. 376 * <br><br> 377 */ 378 /** @var FileError::Code FileError::TOO_MANY_OPEN_FILES 379 * <tt>(EMFILE)</tt> The current process has too many files open and can't 380 * open any more. Duplicate descriptors do count toward this limit. 381 * <br><br> 382 */ 383 /** @var FileError::Code FileError::FILE_TABLE_OVERFLOW 384 * <tt>(ENFILE)</tt> There are too many distinct file openings in the 385 * entire system. 386 * <br><br> 387 */ 388 /** @var FileError::Code FileError::BAD_FILE_DESCRIPTOR 389 * <tt>(EBADF)</tt> Bad file descriptor; for example, I/O on a descriptor 390 * that has been closed or reading from a descriptor open only for writing 391 * (or vice versa). 392 * <br><br> 393 */ 394 /** @var FileError::Code FileError::INVALID_ARGUMENT 395 * <tt>(EINVAL)</tt> Invalid argument. This is used to indicate various kinds 396 * of problems with passing the wrong argument to a library function. 397 * <br><br> 398 */ 399 /** @var FileError::Code FileError::BROKEN_PIPE 400 * <tt>(EPIPE)</tt> Broken pipe; there is no process reading from the other 401 * end of a pipe. Every library function that returns this error code also 402 * generates a <tt>SIGPIPE</tt> signal; this signal terminates the program 403 * if not handled or blocked. Thus, your program will never actually see 404 * this code unless it has handled or blocked <tt>SIGPIPE</tt>. 405 * <br><br> 406 */ 407 /** @var FileError::Code FileError::TRYAGAIN 408 * <tt>(EAGAIN)</tt> Resource temporarily unavailable; the call might work 409 * if you try again later. 410 * We used TRYAGAIN instead of TRY_AGAIN, because that is a defined as a macro by a Unix header. 411 * <br><br> 412 */ 413 /** @var FileError::Code FileError::INTERRUPTED 414 * <tt>(EINTR)</tt> Interrupted function call; an asynchronous signal occurred 415 * and prevented completion of the call. When this happens, you should try 416 * the call again. 417 * <br><br> 418 */ 419 /** @var FileError::Code FileError::IO_ERROR 420 * <tt>(EIO)</tt> Input/output error; usually used for physical read or write 421 * errors. I.e. the disk or other physical device hardware is returning errors. 422 * <br><br> 423 */ 424 /** @var FileError::Code FileError::NOT_OWNER 425 * <tt>(EPERM)</tt> Operation not permitted; only the owner of the file (or other 426 * resource) or processes with special privileges can perform the operation. 427 * <br><br> 428 */ 429 /** @var FileError::Code FileError::FAILED 430 * Does not correspond to a UNIX error code; this is the standard "failed for 431 * unspecified reason" error code present in all Glib::Error error code 432 * enumerations. Returned if no specific code applies. 433 */ 434 435 class GLIBMM_API Dir; 436 437 /** The iterator type of Glib::Dir. 438 * @ingroup FileUtils 439 */ 440 class GLIBMM_API DirIterator 441 { 442 public: 443 typedef std::input_iterator_tag iterator_category; 444 typedef std::string value_type; 445 typedef int difference_type; 446 typedef value_type reference; 447 typedef void pointer; 448 449 DirIterator(); 450 451 #ifndef DOXYGEN_SHOULD_SKIP_THIS 452 DirIterator(GDir* gobject, const char* current); 453 #endif 454 455 std::string operator*() const; 456 DirIterator& operator++(); 457 458 /** @note DirIterator has input iterator semantics, which means real 459 * postfix increment is impossible. The return type is @c void to 460 * prevent surprising behaviour. 461 */ 462 void operator++(int); 463 464 bool operator==(const DirIterator& rhs) const; 465 bool operator!=(const DirIterator& rhs) const; 466 467 private: 468 GDir* gobject_; 469 const char* current_; 470 }; 471 472 473 /** Utility class representing an open directory. 474 * @ingroup FileUtils 475 * It's highly recommended to use the iterator interface. With iterators, 476 * reading an entire directory into a STL container is really easy: 477 * @code 478 * Glib::Dir dir (directory_path); 479 * std::list<std::string> entries (dir.begin(), dir.end()); 480 * @endcode 481 * @note The encoding of the directory entries isn't necessarily UTF-8. 482 * Use Glib::filename_to_utf8() if you need to display them. 483 */ 484 class GLIBMM_API Dir 485 { 486 public: 487 using iterator = DirIterator; 488 using const_iterator = DirIterator; 489 490 /** Opens a directory for reading. The names of the files in the 491 * directory can then be retrieved using read_name(). 492 * @param path The path to the directory you are interested in. 493 * @throw Glib::FileError 494 */ 495 explicit Dir(const std::string& path); 496 497 #ifndef DOXYGEN_SHOULD_SKIP_THIS 498 explicit Dir(GDir* gobject); 499 #endif 500 501 Dir(const Dir&) = delete; 502 Dir& operator=(const Dir&) = delete; 503 504 /** Closes the directory and deallocates all related resources. 505 */ 506 ~Dir(); 507 508 /** Retrieves the name of the next entry in the directory. 509 * The <tt>'.'</tt> and <tt>'..'</tt> entries are omitted. 510 * @return The entry's name or <tt>""</tt> if there are no more entries. 511 * @see begin(), end() 512 */ 513 std::string read_name(); 514 515 /** Resets the directory. The next call to 516 * read_name() will return the first entry again. 517 */ 518 void rewind(); 519 520 /** Closes the directory and deallocates all related resources. 521 * Note that close() is implicitely called by ~Dir(). Thus you don't 522 * need to call close() yourself unless you want to close the directory 523 * before the destructor runs. 524 */ 525 void close(); 526 527 /** Get the begin of an input iterator sequence. 528 * @return An input iterator pointing to the first directory entry. 529 */ 530 DirIterator begin(); 531 532 /** Get the end of an input iterator sequence. 533 * @return An input iterator pointing behind the last directory entry. 534 */ 535 DirIterator end(); 536 537 private: 538 GDir* gobject_; 539 }; 540 541 542 /** Returns @c true if any of the tests in the bitfield @a test are true. 543 * @ingroup FileUtils 544 * For example, <tt>(Glib::FILE_TEST_EXISTS | Glib::FILE_TEST_IS_DIR)</tt> will 545 * return @c true if the file exists; the check whether it's a directory 546 * doesn't matter since the existence test is true. With the current set of 547 * available tests, there's no point passing in more than one test at a time. 548 * 549 * Apart from <tt>Glib::FILE_TEST_IS_SYMLINK</tt> all tests follow symbolic 550 * links, so for a symbolic link to a regular file file_test() will return 551 * @c true for both <tt>Glib::FILE_TEST_IS_SYMLINK</tt> and 552 * <tt>Glib::FILE_TEST_IS_REGULAR</tt>. 553 * 554 * @note For a dangling symbolic link file_test() will return @c true for 555 * <tt>Glib::FILE_TEST_IS_SYMLINK</tt> and @c false for all other flags. 556 * 557 * @param filename A filename to test. 558 * @param test Bitfield of Glib::FileTest flags. 559 * @return Whether a test was true. 560 */ 561 GLIBMM_API 562 bool file_test(const std::string& filename, FileTest test); 563 564 /** Opens a temporary file. 565 * @ingroup FileUtils 566 * See the %mkstemp() documentation on most UNIX-like systems. This is a 567 * portability wrapper, which simply calls %mkstemp() on systems that have 568 * it, and implements it in GLib otherwise. 569 * @param filename_template A string that should match the rules for 570 * %mkstemp(), i.e. end in <tt>"XXXXXX"</tt>. The <tt>X</tt> string 571 * will be modified to form the name of a file that didn't exist. 572 * @return A file handle (as from open()) to the file opened for reading 573 * and writing. The file is opened in binary mode on platforms where there 574 * is a difference. The file handle should be closed with close(). In 575 * case of errors, <tt>-1</tt> is returned. 576 */ 577 GLIBMM_API 578 int mkstemp(std::string& filename_template); 579 580 /** Opens a file for writing in the preferred directory for temporary files 581 * (as returned by Glib::get_tmp_dir()). 582 * @ingroup FileUtils 583 * @a prefix should a basename template; it'll be suffixed by 6 characters 584 * in order to form a unique filename. No directory components are allowed. 585 * 586 * The actual name used is returned in @a name_used. 587 * 588 * @param[out] name_used The actual name used. 589 * @param prefix Template for file name, basename only. 590 * @return A file handle (as from <tt>open()</tt>) to the file opened for reading 591 * and writing. The file is opened in binary mode on platforms where there is a 592 * difference. The file handle should be closed with <tt>close()</tt>. 593 * @throw Glib::FileError 594 */ 595 GLIBMM_API 596 int file_open_tmp(std::string& name_used, const std::string& prefix); 597 598 /** Opens a file for writing in the preferred directory for temporary files 599 * (as returned by Glib::get_tmp_dir()). 600 * @ingroup FileUtils 601 * This function works like file_open_tmp(std::string&, const std::string&) 602 * but uses a default basename prefix. 603 * 604 * @param[out] name_used The actual name used. 605 * @return A file handle (as from <tt>open()</tt>) to the file opened for reading 606 * and writing. The file is opened in binary mode on platforms where there is a 607 * difference. The file handle should be closed with <tt>close()</tt>. 608 * @throw Glib::FileError 609 */ 610 GLIBMM_API 611 int file_open_tmp(std::string& name_used); 612 613 /** Reads an entire file into a string, with good error checking. 614 * @ingroup FileUtils 615 * @param filename A file to read contents from. 616 * @return The file contents. 617 * @throw Glib::FileError 618 */ 619 GLIBMM_API 620 std::string file_get_contents(const std::string& filename); 621 622 /** Writes all of @a contents to a file named @a filename, with good error checking. 623 * 624 * @param filename name of a file to write @a contents to, in the GLib file name 625 * encoding 626 * @param contents string to write to the file 627 * @param length length of @a contents, or -1 if @a contents is a nul-terminated string 628 * 629 * If a file called @a filename already exists it will be overwritten. 630 * 631 * This write is atomic in the sense that it is first written to a temporary 632 * file which is then renamed to the final name. Notes: 633 * <ol> 634 * <li> 635 * On Unix, if @a filename already exists hard links to @a filename will break. 636 * Also since the file is recreated, existing permissions, access control 637 * lists, metadata etc. may be lost. If @a filename is a symbolic link, 638 * the link itself will be replaced, not the linked file. 639 * </li> 640 * <li> 641 * On Windows renaming a file will not remove an existing file with the 642 * new name, so on Windows there is a race condition between the existing 643 * file being removed and the temporary file being renamed. 644 * </li> 645 * <li> 646 * On Windows there is no way to remove a file that is open to some 647 * process, or mapped into memory. Thus, this function will fail if 648 * @a filename already exists and is open. 649 * </li> 650 * </ol> 651 * 652 * If the call was not successful, an exception is thrown. 653 * Possible error codes are those in the FileError enumeration. 654 * 655 * @newin{2,22} 656 **/ 657 GLIBMM_API 658 void file_set_contents (const std::string& filename, const gchar *contents, gssize length); 659 /** A variant of file_set_contents which accepts a standard C++ string 660 * 661 * @newin{2,22} 662 * */ 663 GLIBMM_API 664 void file_set_contents (const std::string& filename, const std::string& contents); 665 666 } // namespace Glib 667 668 669 #endif /* _GLIBMM_FILEUTILS_H */ 670 671