source: appstream-generator/build/girepo/glib/FileUtils.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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