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