1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD 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 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module glib.FileUtils; 26 27 private import glib.ErrorG; 28 private import glib.GException; 29 private import glib.Str; 30 private import gtkc.glib; 31 public import gtkc.glibtypes; 32 33 34 public struct FileUtils 35 { 36 /** 37 */ 38 39 /** 40 * A wrapper for the POSIX access() function. This function is used to 41 * test a pathname for one or several of read, write or execute 42 * permissions, or just existence. 43 * 44 * On Windows, the file protection mechanism is not at all POSIX-like, 45 * and the underlying function in the C library only checks the 46 * FAT-style READONLY attribute, and does not look at the ACL of a 47 * file at all. This function is this in practise almost useless on 48 * Windows. Software that needs to handle file permissions on Windows 49 * more exactly should use the Win32 API. 50 * 51 * See your C library manual for more details about access(). 52 * 53 * Params: 54 * filename = a pathname in the GLib file name encoding (UTF-8 on Windows) 55 * mode = as in access() 56 * 57 * Return: zero if the pathname refers to an existing file system 58 * object that has all the tested permissions, or -1 otherwise 59 * or on error. 60 * 61 * Since: 2.8 62 */ 63 public static int access(string filename, int mode) 64 { 65 return g_access(Str.toStringz(filename), mode); 66 } 67 68 /** 69 * A wrapper for the POSIX chdir() function. The function changes the 70 * current directory of the process to @path. 71 * 72 * See your C library manual for more details about chdir(). 73 * 74 * Params: 75 * path = a pathname in the GLib file name encoding (UTF-8 on Windows) 76 * 77 * Return: 0 on success, -1 if an error occurred. 78 * 79 * Since: 2.8 80 */ 81 public static int chdir(string path) 82 { 83 return g_chdir(Str.toStringz(path)); 84 } 85 86 /** 87 * This wraps the close() call; in case of error, %errno will be 88 * preserved, but the error will also be stored as a #GError in @error. 89 * 90 * Besides using #GError, there is another major reason to prefer this 91 * function over the call provided by the system; on Unix, it will 92 * attempt to correctly handle %EINTR, which has platform-specific 93 * semantics. 94 * 95 * Params: 96 * fd = A file descriptor 97 * 98 * Return: %TRUE on success, %FALSE if there was an error. 99 * 100 * Since: 2.36 101 * 102 * Throws: GException on failure. 103 */ 104 public static bool close(int fd) 105 { 106 GError* err = null; 107 108 auto p = g_close(fd, &err) != 0; 109 110 if (err !is null) 111 { 112 throw new GException( new ErrorG(err) ); 113 } 114 115 return p; 116 } 117 118 /** 119 * Gets a #GFileError constant based on the passed-in @err_no. 120 * For example, if you pass in `EEXIST` this function returns 121 * #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably 122 * assume that all #GFileError values will exist. 123 * 124 * Normally a #GFileError value goes into a #GError returned 125 * from a function that manipulates files. So you would use 126 * g_file_error_from_errno() when constructing a #GError. 127 * 128 * Params: 129 * errNo = an "errno" value 130 * 131 * Return: #GFileError corresponding to the given @errno 132 */ 133 public static GFileError fileErrorFromErrno(int errNo) 134 { 135 return g_file_error_from_errno(errNo); 136 } 137 138 public static GQuark fileErrorQuark() 139 { 140 return g_file_error_quark(); 141 } 142 143 /** 144 * Reads an entire file into allocated memory, with good error 145 * checking. 146 * 147 * If the call was successful, it returns %TRUE and sets @contents to the file 148 * contents and @length to the length of the file contents in bytes. The string 149 * stored in @contents will be nul-terminated, so for text files you can pass 150 * %NULL for the @length argument. If the call was not successful, it returns 151 * %FALSE and sets @error. The error domain is #G_FILE_ERROR. Possible error 152 * codes are those in the #GFileError enumeration. In the error case, 153 * @contents is set to %NULL and @length is set to zero. 154 * 155 * Params: 156 * filename = name of a file to read contents from, in the GLib file name encoding 157 * contents = location to store an allocated string, use g_free() to free 158 * the returned string 159 * length = location to store length in bytes of the contents, or %NULL 160 * 161 * Return: %TRUE on success, %FALSE if an error occurred 162 * 163 * Throws: GException on failure. 164 */ 165 public static bool fileGetContents(string filename, out string contents) 166 { 167 char* outcontents = null; 168 size_t length; 169 GError* err = null; 170 171 auto p = g_file_get_contents(Str.toStringz(filename), &outcontents, &length, &err) != 0; 172 173 if (err !is null) 174 { 175 throw new GException( new ErrorG(err) ); 176 } 177 178 contents = Str.toString(outcontents, length); 179 180 return p; 181 } 182 183 /** 184 * Opens a file for writing in the preferred directory for temporary 185 * files (as returned by g_get_tmp_dir()). 186 * 187 * @tmpl should be a string in the GLib file name encoding containing 188 * a sequence of six 'X' characters, as the parameter to g_mkstemp(). 189 * However, unlike these functions, the template should only be a 190 * basename, no directory components are allowed. If template is 191 * %NULL, a default template is used. 192 * 193 * Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not 194 * modified, and might thus be a read-only literal string. 195 * 196 * Upon success, and if @name_used is non-%NULL, the actual name used 197 * is returned in @name_used. This string should be freed with g_free() 198 * when not needed any longer. The returned name is in the GLib file 199 * name encoding. 200 * 201 * Params: 202 * tmpl = Template for file name, as in 203 * g_mkstemp(), basename only, or %NULL for a default template 204 * nameUsed = location to store actual name used, 205 * or %NULL 206 * 207 * Return: A file handle (as from open()) to the file opened for 208 * reading and writing. The file is opened in binary mode on platforms 209 * where there is a difference. The file handle should be closed with 210 * close(). In case of errors, -1 is returned and @error will be set. 211 * 212 * Throws: GException on failure. 213 */ 214 public static int fileOpenTmp(string tmpl, out string nameUsed) 215 { 216 char* outnameUsed = null; 217 GError* err = null; 218 219 auto p = g_file_open_tmp(Str.toStringz(tmpl), &outnameUsed, &err); 220 221 if (err !is null) 222 { 223 throw new GException( new ErrorG(err) ); 224 } 225 226 nameUsed = Str.toString(outnameUsed); 227 228 return p; 229 } 230 231 /** 232 * Reads the contents of the symbolic link @filename like the POSIX 233 * readlink() function. The returned string is in the encoding used 234 * for filenames. Use g_filename_to_utf8() to convert it to UTF-8. 235 * 236 * Params: 237 * filename = the symbolic link 238 * 239 * Return: A newly-allocated string with the contents of the symbolic link, 240 * or %NULL if an error occurred. 241 * 242 * Since: 2.4 243 * 244 * Throws: GException on failure. 245 */ 246 public static string fileReadLink(string filename) 247 { 248 GError* err = null; 249 250 auto p = g_file_read_link(Str.toStringz(filename), &err); 251 252 if (err !is null) 253 { 254 throw new GException( new ErrorG(err) ); 255 } 256 257 return Str.toString(p); 258 } 259 260 /** 261 * Writes all of @contents to a file named @filename, with good error checking. 262 * If a file called @filename already exists it will be overwritten. 263 * 264 * This write is atomic in the sense that it is first written to a temporary 265 * file which is then renamed to the final name. Notes: 266 * 267 * - On UNIX, if @filename already exists hard links to @filename will break. 268 * Also since the file is recreated, existing permissions, access control 269 * lists, metadata etc. may be lost. If @filename is a symbolic link, 270 * the link itself will be replaced, not the linked file. 271 * 272 * - On Windows renaming a file will not remove an existing file with the 273 * new name, so on Windows there is a race condition between the existing 274 * file being removed and the temporary file being renamed. 275 * 276 * - On Windows there is no way to remove a file that is open to some 277 * process, or mapped into memory. Thus, this function will fail if 278 * @filename already exists and is open. 279 * 280 * If the call was successful, it returns %TRUE. If the call was not successful, 281 * it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR. 282 * Possible error codes are those in the #GFileError enumeration. 283 * 284 * Note that the name for the temporary file is constructed by appending up 285 * to 7 characters to @filename. 286 * 287 * Params: 288 * filename = name of a file to write @contents to, in the GLib file name 289 * encoding 290 * contents = string to write to the file 291 * length = length of @contents, or -1 if @contents is a nul-terminated string 292 * 293 * Return: %TRUE on success, %FALSE if an error occurred 294 * 295 * Since: 2.8 296 * 297 * Throws: GException on failure. 298 */ 299 public static bool fileSetContents(string filename, string contents) 300 { 301 GError* err = null; 302 303 auto p = g_file_set_contents(Str.toStringz(filename), Str.toStringz(contents), cast(ptrdiff_t)contents.length, &err) != 0; 304 305 if (err !is null) 306 { 307 throw new GException( new ErrorG(err) ); 308 } 309 310 return p; 311 } 312 313 /** 314 * Returns %TRUE if any of the tests in the bitfield @test are 315 * %TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)` 316 * will return %TRUE if the file exists; the check whether it's a 317 * directory doesn't matter since the existence test is %TRUE. With 318 * the current set of available tests, there's no point passing in 319 * more than one test at a time. 320 * 321 * Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links, 322 * so for a symbolic link to a regular file g_file_test() will return 323 * %TRUE for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR. 324 * 325 * Note, that for a dangling symbolic link g_file_test() will return 326 * %TRUE for %G_FILE_TEST_IS_SYMLINK and %FALSE for all other flags. 327 * 328 * You should never use g_file_test() to test whether it is safe 329 * to perform an operation, because there is always the possibility 330 * of the condition changing before you actually perform the operation. 331 * For example, you might think you could use %G_FILE_TEST_IS_SYMLINK 332 * to know whether it is safe to write to a file without being 333 * tricked into writing into a different location. It doesn't work! 334 * |[<!-- language="C" --> 335 * // DON'T DO THIS 336 * if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) 337 * { 338 * fd = g_open (filename, O_WRONLY); 339 * // write to fd 340 * } 341 * ]| 342 * 343 * Another thing to note is that %G_FILE_TEST_EXISTS and 344 * %G_FILE_TEST_IS_EXECUTABLE are implemented using the access() 345 * system call. This usually doesn't matter, but if your program 346 * is setuid or setgid it means that these tests will give you 347 * the answer for the real user ID and group ID, rather than the 348 * effective user ID and group ID. 349 * 350 * On Windows, there are no symlinks, so testing for 351 * %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for 352 * %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and 353 * its name indicates that it is executable, checking for well-known 354 * extensions and those listed in the `PATHEXT` environment variable. 355 * 356 * Params: 357 * filename = a filename to test in the GLib file name encoding 358 * test = bitfield of #GFileTest flags 359 * 360 * Return: whether a test was %TRUE 361 */ 362 public static bool fileTest(string filename, GFileTest test) 363 { 364 return g_file_test(Str.toStringz(filename), test) != 0; 365 } 366 367 /** 368 * Create a directory if it doesn't already exist. Create intermediate 369 * parent directories as needed, too. 370 * 371 * Params: 372 * pathname = a pathname in the GLib file name encoding 373 * mode = permissions to use for newly created directories 374 * 375 * Return: 0 if the directory already exists, or was successfully 376 * created. Returns -1 if an error occurred, with errno set. 377 * 378 * Since: 2.8 379 */ 380 public static int mkdirWithParents(string pathname, int mode) 381 { 382 return g_mkdir_with_parents(Str.toStringz(pathname), mode); 383 } 384 385 /** 386 * Creates a temporary directory. See the mkdtemp() documentation 387 * on most UNIX-like systems. 388 * 389 * The parameter is a string that should follow the rules for 390 * mkdtemp() templates, i.e. contain the string "XXXXXX". 391 * g_mkdtemp() is slightly more flexible than mkdtemp() in that the 392 * sequence does not have to occur at the very end of the template 393 * and you can pass a @mode and additional @flags. The X string will 394 * be modified to form the name of a directory that didn't exist. 395 * The string should be in the GLib file name encoding. Most importantly, 396 * on Windows it should be in UTF-8. 397 * 398 * Params: 399 * tmpl = template directory name 400 * 401 * Return: A pointer to @tmpl, which has been modified 402 * to hold the directory name. In case of errors, %NULL is 403 * returned and %errno will be set. 404 * 405 * Since: 2.30 406 */ 407 public static string mkdtemp(string tmpl) 408 { 409 return Str.toString(g_mkdtemp(Str.toStringz(tmpl))); 410 } 411 412 /** 413 * Creates a temporary directory. See the mkdtemp() documentation 414 * on most UNIX-like systems. 415 * 416 * The parameter is a string that should follow the rules for 417 * mkdtemp() templates, i.e. contain the string "XXXXXX". 418 * g_mkdtemp() is slightly more flexible than mkdtemp() in that the 419 * sequence does not have to occur at the very end of the template 420 * and you can pass a @mode. The X string will be modified to form 421 * the name of a directory that didn't exist. The string should be 422 * in the GLib file name encoding. Most importantly, on Windows it 423 * should be in UTF-8. 424 * 425 * Params: 426 * tmpl = template directory name 427 * mode = permissions to create the temporary directory with 428 * 429 * Return: A pointer to @tmpl, which has been modified 430 * to hold the directory name. In case of errors, %NULL is 431 * returned, and %errno will be set. 432 * 433 * Since: 2.30 434 */ 435 public static string mkdtempFull(string tmpl, int mode) 436 { 437 return Str.toString(g_mkdtemp_full(Str.toStringz(tmpl), mode)); 438 } 439 440 /** 441 * Opens a temporary file. See the mkstemp() documentation 442 * on most UNIX-like systems. 443 * 444 * The parameter is a string that should follow the rules for 445 * mkstemp() templates, i.e. contain the string "XXXXXX". 446 * g_mkstemp() is slightly more flexible than mkstemp() in that the 447 * sequence does not have to occur at the very end of the template. 448 * The X string will be modified to form the name of a file that 449 * didn't exist. The string should be in the GLib file name encoding. 450 * Most importantly, on Windows it should be in UTF-8. 451 * 452 * Params: 453 * tmpl = template filename 454 * 455 * Return: A file handle (as from open()) to the file 456 * opened for reading and writing. The file is opened in binary 457 * mode on platforms where there is a difference. The file handle 458 * should be closed with close(). In case of errors, -1 is 459 * returned and %errno will be set. 460 */ 461 public static int mkstemp(string tmpl) 462 { 463 return g_mkstemp(Str.toStringz(tmpl)); 464 } 465 466 /** 467 * Opens a temporary file. See the mkstemp() documentation 468 * on most UNIX-like systems. 469 * 470 * The parameter is a string that should follow the rules for 471 * mkstemp() templates, i.e. contain the string "XXXXXX". 472 * g_mkstemp_full() is slightly more flexible than mkstemp() 473 * in that the sequence does not have to occur at the very end of the 474 * template and you can pass a @mode and additional @flags. The X 475 * string will be modified to form the name of a file that didn't exist. 476 * The string should be in the GLib file name encoding. Most importantly, 477 * on Windows it should be in UTF-8. 478 * 479 * Params: 480 * tmpl = template filename 481 * flags = flags to pass to an open() call in addition to O_EXCL 482 * and O_CREAT, which are passed automatically 483 * mode = permissions to create the temporary file with 484 * 485 * Return: A file handle (as from open()) to the file 486 * opened for reading and writing. The file handle should be 487 * closed with close(). In case of errors, -1 is returned 488 * and %errno will be set. 489 * 490 * Since: 2.22 491 */ 492 public static int mkstempFull(string tmpl, int flags, int mode) 493 { 494 return g_mkstemp_full(Str.toStringz(tmpl), flags, mode); 495 } 496 497 /** 498 * A wrapper for the POSIX rmdir() function. The rmdir() function 499 * deletes a directory from the filesystem. 500 * 501 * See your C library manual for more details about how rmdir() works 502 * on your system. 503 * 504 * Params: 505 * filename = a pathname in the GLib file name encoding (UTF-8 on Windows) 506 * 507 * Return: 0 if the directory was successfully removed, -1 if an error 508 * occurred 509 * 510 * Since: 2.6 511 */ 512 public static int rmdir(string filename) 513 { 514 return g_rmdir(Str.toStringz(filename)); 515 } 516 517 /** 518 * A wrapper for the POSIX unlink() function. The unlink() function 519 * deletes a name from the filesystem. If this was the last link to the 520 * file and no processes have it opened, the diskspace occupied by the 521 * file is freed. 522 * 523 * See your C library manual for more details about unlink(). Note 524 * that on Windows, it is in general not possible to delete files that 525 * are open to some process, or mapped into memory. 526 * 527 * Params: 528 * filename = a pathname in the GLib file name encoding (UTF-8 on Windows) 529 * 530 * Return: 0 if the name was successfully deleted, -1 if an error 531 * occurred 532 * 533 * Since: 2.6 534 */ 535 public static int unlink(string filename) 536 { 537 return g_unlink(Str.toStringz(filename)); 538 } 539 }