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