| blob | bf936ec93dcc2f5eed6f0a8a68430ac215f3be1b |
1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
3 /* GIO - GLib Input, Output and Streaming Library
4 *
5 * Copyright (C) 2006-2007 Red Hat, Inc.
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General
18 * Public License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
20 * Boston, MA 02111-1307, USA.
21 *
22 * Author: Alexander Larsson <alexl@redhat.com>
23 */
27 #ifdef __linux__
28 #include <sys/ioctl.h>
29 #include <errno.h>
30 /* See linux.git/fs/btrfs/ioctl.h */
31 #define BTRFS_IOCTL_MAGIC 0x94
32 #define BTRFS_IOC_CLONE _IOW(BTRFS_IOCTL_MAGIC, 9, int)
33 #endif
35 #ifdef HAVE_SPLICE
36 #include <sys/stat.h>
37 #include <unistd.h>
38 #include <fcntl.h>
39 #include <errno.h>
40 #endif
42 #include <string.h>
43 #include <sys/types.h>
44 #ifdef HAVE_PWD_H
45 #include <pwd.h>
46 #endif
50 #ifdef G_OS_UNIX
52 #endif
70 /**
71 * SECTION:gfile
72 * @short_description: File and Directory Handling
73 * @include: gio/gio.h
74 * @see_also: #GFileInfo, #GFileEnumerator
75 *
76 * #GFile is a high level abstraction for manipulating files on a
77 * virtual file system. #GFiles are lightweight, immutable objects
78 * that do no I/O upon creation. It is necessary to understand that
79 * #GFile objects do not represent files, merely an identifier for a
80 * file. All file content I/O is implemented as streaming operations
81 * (see #GInputStream and #GOutputStream).
82 *
83 * To construct a #GFile, you can use:
84 * <simplelist>
85 * <member>g_file_new_for_path() if you have a path.</member>
86 * <member>g_file_new_for_uri() if you have a URI.</member>
87 * <member>g_file_new_for_commandline_arg() for a command line argument.</member>
88 * <member>g_file_new_tmp() to create a temporary file from a template.</member>
89 * <member>g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().</member>
90 * </simplelist>
91 *
92 * One way to think of a #GFile is as an abstraction of a pathname. For
93 * normal files the system pathname is what is stored internally, but as
94 * #GFiles are extensible it could also be something else that corresponds
95 * to a pathname in a userspace implementation of a filesystem.
96 *
97 * #GFiles make up hierarchies of directories and files that correspond to
98 * the files on a filesystem. You can move through the file system with
99 * #GFile using g_file_get_parent() to get an identifier for the parent
100 * directory, g_file_get_child() to get a child within a directory,
101 * g_file_resolve_relative_path() to resolve a relative path between two
102 * #GFiles. There can be multiple hierarchies, so you may not end up at
103 * the same root if you repeatedly call g_file_get_parent() on two different
104 * files.
105 *
106 * All #GFiles have a basename (get with g_file_get_basename()). These names
107 * are byte strings that are used to identify the file on the filesystem
108 * (relative to its parent directory) and there is no guarantees that they
109 * have any particular charset encoding or even make any sense at all. If
110 * you want to use filenames in a user interface you should use the display
111 * name that you can get by requesting the
112 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
113 * This is guaranteed to be in UTF-8 and can be used in a user interface.
114 * But always store the real basename or the #GFile to use to actually
115 * access the file, because there is no way to go from a display name to
116 * the actual name.
117 *
118 * Using #GFile as an identifier has the same weaknesses as using a path
119 * in that there may be multiple aliases for the same file. For instance,
120 * hard or soft links may cause two different #GFiles to refer to the same
121 * file. Other possible causes for aliases are: case insensitive filesystems,
122 * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
123 * check if two #GFiles point to the same file you can query for the
124 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
125 * canonicalization of pathnames passed in, so that trivial differences in
126 * the path string used at creation (duplicated slashes, slash at end of
127 * path, "." or ".." path segments, etc) does not create different #GFiles.
128 *
129 * Many #GFile operations have both synchronous and asynchronous versions
130 * to suit your application. Asynchronous versions of synchronous functions
131 * simply have _async() appended to their function names. The asynchronous
132 * I/O functions call a #GAsyncReadyCallback which is then used to finalize
133 * the operation, producing a GAsyncResult which is then passed to the
134 * function's matching _finish() operation.
135 *
136 * Some #GFile operations do not have synchronous analogs, as they may
137 * take a very long time to finish, and blocking may leave an application
138 * unusable. Notable cases include:
139 * <simplelist>
140 * <member>g_file_mount_mountable() to mount a mountable file.</member>
141 * <member>g_file_unmount_mountable_with_operation() to unmount a mountable file.</member>
142 * <member>g_file_eject_mountable_with_operation() to eject a mountable file.</member>
143 * </simplelist>
144 *
145 * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
146 * One notable feature of #GFiles are entity tags, or "etags" for
147 * short. Entity tags are somewhat like a more abstract version of the
148 * traditional mtime, and can be used to quickly determine if the file has
149 * been modified from the version on the file system. See the HTTP 1.1
150 * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink>
151 * for HTTP Etag headers, which are a very similar concept.
152 * </para>
153 **/
157 GFileQueryInfoFlags flags,
160 GAsyncReadyCallback callback,
161 gpointer user_data);
169 GAsyncReadyCallback callback,
170 gpointer user_data);
176 GFileQueryInfoFlags flags,
179 GAsyncReadyCallback callback,
180 gpointer user_data);
187 GAsyncReadyCallback callback,
188 gpointer user_data);
193 GFileCreateFlags flags,
196 GAsyncReadyCallback callback,
197 gpointer user_data);
202 GFileCreateFlags flags,
205 GAsyncReadyCallback callback,
206 gpointer user_data);
212 gboolean make_backup,
213 GFileCreateFlags flags,
216 GAsyncReadyCallback callback,
217 gpointer user_data);
224 GAsyncReadyCallback callback,
225 gpointer user_data);
232 GAsyncReadyCallback callback,
233 gpointer user_data);
240 GAsyncReadyCallback callback,
241 gpointer user_data);
248 GAsyncReadyCallback callback,
249 gpointer user_data);
254 GFileCreateFlags flags,
257 GAsyncReadyCallback callback,
258 gpointer user_data);
264 gboolean make_backup,
265 GFileCreateFlags flags,
268 GAsyncReadyCallback callback,
269 gpointer user_data);
275 GFileQueryInfoFlags flags,
282 GAsyncReadyCallback callback,
283 gpointer user_data);
289 GFileQueryInfoFlags flags,
292 GAsyncReadyCallback callback,
293 gpointer user_data);
301 GAsyncReadyCallback callback,
302 gpointer user_data);
308 GFileCopyFlags flags,
311 GFileProgressCallback progress_callback,
312 gpointer progress_callback_data,
313 GAsyncReadyCallback callback,
314 gpointer user_data);
320 GFileMeasureFlags flags,
322 GFileMeasureProgressCallback progress_callback,
323 gpointer progress_data,
329 GFileMeasureFlags flags,
330 gint io_priority,
332 GFileMeasureProgressCallback progress_callback,
333 gpointer progress_data,
334 GAsyncReadyCallback callback,
335 gpointer user_data);
346 static void
348 {
387 }
390 /**
391 * g_file_is_native:
392 * @file: input #GFile
393 *
394 * Checks to see if a file is native to the platform.
395 *
396 * A native file s one expressed in the platform-native filename format,
397 * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
398 * as it might be on a locally mounted remote filesystem.
399 *
400 * On some systems non-native files may be available using the native
401 * filesystem via a userspace filesystem (FUSE), in these cases this call
402 * will return %FALSE, but g_file_get_path() will still return a native path.
403 *
404 * This call does no blocking I/O.
405 *
406 * Returns: %TRUE if @file is native
407 */
408 gboolean
410 {
418 }
421 /**
422 * g_file_has_uri_scheme:
423 * @file: input #GFile
424 * @uri_scheme: a string containing a URI scheme
425 *
426 * Checks to see if a #GFile has a given URI scheme.
427 *
428 * This call does no blocking I/O.
429 *
430 * Returns: %TRUE if #GFile's backend supports the
431 * given URI scheme, %FALSE if URI scheme is %NULL,
432 * not supported, or #GFile is invalid.
433 */
434 gboolean
437 {
446 }
449 /**
450 * g_file_get_uri_scheme:
451 * @file: input #GFile
452 *
453 * Gets the URI scheme for a #GFile.
454 * RFC 3986 decodes the scheme as:
455 * <programlisting>
456 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
457 * </programlisting>
458 * Common schemes include "file", "http", "ftp", etc.
459 *
460 * This call does no blocking I/O.
461 *
462 * Returns: a string containing the URI scheme for the given
463 * #GFile. The returned string should be freed with g_free()
464 * when no longer needed.
465 */
468 {
476 }
479 /**
480 * g_file_get_basename:
481 * @file: input #GFile
482 *
483 * Gets the base name (the last component of the path) for a given #GFile.
484 *
485 * If called for the top level of a system (such as the filesystem root
486 * or a uri like sftp://host/) it will return a single directory separator
487 * (and on Windows, possibly a drive letter).
488 *
489 * The base name is a byte string (not UTF-8). It has no defined encoding
490 * or rules other than it may not contain zero bytes. If you want to use
491 * filenames in a user interface you should use the display name that you
492 * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
493 * attribute with g_file_query_info().
494 *
495 * This call does no blocking I/O.
496 *
497 * Returns: string containing the #GFile's base name, or %NULL
498 * if given #GFile is invalid. The returned string should be
499 * freed with g_free() when no longer needed.
500 */
503 {
511 }
513 /**
514 * g_file_get_path:
515 * @file: input #GFile
516 *
517 * Gets the local pathname for #GFile, if one exists.
518 *
519 * This call does no blocking I/O.
520 *
521 * Returns: string containing the #GFile's path, or %NULL if
522 * no such path exists. The returned string should be
523 * freed with g_free() when no longer needed.
524 */
527 {
535 }
537 /**
538 * g_file_get_uri:
539 * @file: input #GFile
540 *
541 * Gets the URI for the @file.
542 *
543 * This call does no blocking I/O.
544 *
545 * Returns: a string containing the #GFile's URI.
546 * The returned string should be freed with g_free()
547 * when no longer needed.
548 */
551 {
559 }
561 /**
562 * g_file_get_parse_name:
563 * @file: input #GFile
564 *
565 * Gets the parse name of the @file.
566 * A parse name is a UTF-8 string that describes the
567 * file such that one can get the #GFile back using
568 * g_file_parse_name().
569 *
570 * This is generally used to show the #GFile as a nice
571 * full-pathname kind of string in a user interface,
572 * like in a location entry.
573 *
574 * For local files with names that can safely be converted
575 * to UTF-8 the pathname is used, otherwise the IRI is used
576 * (a form of URI that allows UTF-8 characters unescaped).
577 *
578 * This call does no blocking I/O.
579 *
580 * Returns: a string containing the #GFile's parse name.
581 * The returned string should be freed with g_free()
582 * when no longer needed.
583 */
586 {
594 }
596 /**
597 * g_file_dup:
598 * @file: input #GFile
599 *
600 * Duplicates a #GFile handle. This operation does not duplicate
601 * the actual file or directory represented by the #GFile; see
602 * g_file_copy() if attempting to copy a file.
603 *
604 * This call does no blocking I/O.
605 *
606 * Returns: (transfer full): a new #GFile that is a duplicate
607 * of the given #GFile.
608 */
609 GFile *
611 {
619 }
621 /**
622 * g_file_hash:
623 * @file: (type GFile): #gconstpointer to a #GFile
624 *
625 * Creates a hash value for a #GFile.
626 *
627 * This call does no blocking I/O.
628 *
629 * Virtual: hash
630 * Returns: 0 if @file is not a valid #GFile, otherwise an
631 * integer that can be used as hash value for the #GFile.
632 * This function is intended for easily hashing a #GFile to
633 * add to a #GHashTable or similar data structure.
634 */
635 guint
637 {
645 }
647 /**
648 * g_file_equal:
649 * @file1: the first #GFile
650 * @file2: the second #GFile
651 *
652 * Checks equality of two given #GFiles.
653 *
654 * Note that two #GFiles that differ can still refer to the same
655 * file on the filesystem due to various forms of filename
656 * aliasing.
657 *
658 * This call does no blocking I/O.
659 *
660 * Returns: %TRUE if @file1 and @file2 are equal.
661 * %FALSE if either is not a #GFile.
662 */
663 gboolean
666 {
678 }
681 /**
682 * g_file_get_parent:
683 * @file: input #GFile
684 *
685 * Gets the parent directory for the @file.
686 * If the @file represents the root directory of the
687 * file system, then %NULL will be returned.
688 *
689 * This call does no blocking I/O.
690 *
691 * Returns: (transfer full): a #GFile structure to the
692 * parent of the given #GFile or %NULL if there is
693 * no parent. Free the returned object with g_object_unref().
694 */
695 GFile *
697 {
705 }
707 /**
708 * g_file_has_parent:
709 * @file: input #GFile
710 * @parent: (allow-none): the parent to check for, or %NULL
711 *
712 * Checks if @file has a parent, and optionally, if it is @parent.
713 *
714 * If @parent is %NULL then this function returns %TRUE if @file has any
715 * parent at all. If @parent is non-%NULL then %TRUE is only returned
716 * if @file is a child of @parent.
717 *
718 * Returns: %TRUE if @file is a child of @parent (or any parent in the
719 * case that @parent is %NULL).
720 *
721 * Since: 2.24
722 */
723 gboolean
726 {
728 gboolean result;
736 {
739 else
743 }
744 else
748 }
750 /**
751 * g_file_get_child:
752 * @file: input #GFile
753 * @name: string containing the child's basename
754 *
755 * Gets a child of @file with basename equal to @name.
756 *
757 * Note that the file with that specific name might not exist, but
758 * you can still have a #GFile that points to it. You can use this
759 * for instance to create that file.
760 *
761 * This call does no blocking I/O.
762 *
763 * Returns: (transfer full): a #GFile to a child specified by @name.
764 * Free the returned object with g_object_unref().
765 */
766 GFile *
769 {
774 }
776 /**
777 * g_file_get_child_for_display_name:
778 * @file: input #GFile
779 * @display_name: string to a possible child
780 * @error: return location for an error
781 *
782 * Gets the child of @file for a given @display_name (i.e. a UTF-8
783 * version of the name). If this function fails, it returns %NULL
784 * and @error will be set. This is very useful when constructing a
785 * #GFile for a new file and the user entered the filename in the
786 * user interface, for instance when you select a directory and
787 * type a filename in the file selector.
788 *
789 * This call does no blocking I/O.
790 *
791 * Returns: (transfer full): a #GFile to the specified child, or
792 * %NULL if the display name couldn't be converted.
793 * Free the returned object with g_object_unref().
794 */
795 GFile *
799 {
808 }
810 /**
811 * g_file_has_prefix:
812 * @file: input #GFile
813 * @prefix: input #GFile
814 *
815 * Checks whether @file has the prefix specified by @prefix.
816 *
817 * In other words, if the names of initial elements of @file's
818 * pathname match @prefix. Only full pathname elements are matched,
819 * so a path like /foo is not considered a prefix of /foobar, only
820 * of /foo/bar.
821 *
822 * This call does no I/O, as it works purely on names. As such it can
823 * sometimes return %FALSE even if @file is inside a @prefix (from a
824 * filesystem point of view), because the prefix of @file is an alias
825 * of @prefix.
826 *
827 * Virtual: prefix_matches
828 * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix,
829 * %FALSE otherwise.
830 */
831 gboolean
834 {
845 /* The vtable function differs in arg order since
846 * we're using the old contains_file call
847 */
849 }
851 /**
852 * g_file_get_relative_path:
853 * @parent: input #GFile
854 * @descendant: input #GFile
855 *
856 * Gets the path for @descendant relative to @parent.
857 *
858 * This call does no blocking I/O.
859 *
860 * Returns: string with the relative path from @descendant
861 * to @parent, or %NULL if @descendant doesn't have @parent
862 * as prefix. The returned string should be freed with g_free()
863 * when no longer needed.
864 */
868 {
880 }
882 /**
883 * g_file_resolve_relative_path:
884 * @file: input #GFile
885 * @relative_path: a given relative path string
886 *
887 * Resolves a relative path for @file to an absolute path.
888 *
889 * This call does no blocking I/O.
890 *
891 * Returns: (transfer full): #GFile to the resolved path.
892 * %NULL if @relative_path is %NULL or if @file is invalid.
893 * Free the returned object with g_object_unref().
894 */
895 GFile *
898 {
907 }
909 /**
910 * g_file_enumerate_children:
911 * @file: input #GFile
912 * @attributes: an attribute query string
913 * @flags: a set of #GFileQueryInfoFlags
914 * @cancellable: (allow-none): optional #GCancellable object,
915 * %NULL to ignore
916 * @error: #GError for error reporting
917 *
918 * Gets the requested information about the files in a directory.
919 * The result is a #GFileEnumerator object that will give out
920 * #GFileInfo objects for all the files in the directory.
921 *
922 * The @attributes value is a string that specifies the file
923 * attributes that should be gathered. It is not an error if
924 * it's not possible to read a particular requested attribute
925 * from a file - it just won't be set. @attributes should
926 * be a comma-separated list of attributes or attribute wildcards.
927 * The wildcard "*" means all attributes, and a wildcard like
928 * "standard::*" means all attributes in the standard namespace.
929 * An example attribute query be "standard::*,owner::user".
930 * The standard attributes are available as defines, like
931 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
932 *
933 * If @cancellable is not %NULL, then the operation can be cancelled
934 * by triggering the cancellable object from another thread. If the
935 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
936 * returned.
937 *
938 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
939 * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
940 * error will be returned. Other errors are possible too.
941 *
942 * Returns: (transfer full): A #GFileEnumerator if successful,
943 * %NULL on error. Free the returned object with g_object_unref().
944 */
945 GFileEnumerator *
948 GFileQueryInfoFlags flags,
951 {
962 {
964 G_IO_ERROR_NOT_SUPPORTED,
967 }
971 }
973 /**
974 * g_file_enumerate_children_async:
975 * @file: input #GFile
976 * @attributes: an attribute query string
977 * @flags: a set of #GFileQueryInfoFlags
978 * @io_priority: the <link linkend="io-priority">I/O priority</link>
979 * of the request
980 * @cancellable: (allow-none): optional #GCancellable object,
981 * %NULL to ignore
982 * @callback: (scope async): a #GAsyncReadyCallback to call when the
983 * request is satisfied
984 * @user_data: (closure): the data to pass to callback function
985 *
986 * Asynchronously gets the requested information about the files
987 * in a directory. The result is a #GFileEnumerator object that will
988 * give out #GFileInfo objects for all the files in the directory.
989 *
990 * For more details, see g_file_enumerate_children() which is
991 * the synchronous version of this call.
992 *
993 * When the operation is finished, @callback will be called. You can
994 * then call g_file_enumerate_children_finish() to get the result of
995 * the operation.
996 */
997 void
1000 GFileQueryInfoFlags flags,
1003 GAsyncReadyCallback callback,
1004 gpointer user_data)
1005 {
1012 attributes,
1013 flags,
1014 io_priority,
1015 cancellable,
1016 callback,
1017 user_data);
1018 }
1020 /**
1021 * g_file_enumerate_children_finish:
1022 * @file: input #GFile
1023 * @res: a #GAsyncResult
1024 * @error: a #GError
1025 *
1026 * Finishes an async enumerate children operation.
1027 * See g_file_enumerate_children_async().
1028 *
1029 * Returns: (transfer full): a #GFileEnumerator or %NULL
1030 * if an error occurred.
1031 * Free the returned object with g_object_unref().
1032 */
1033 GFileEnumerator *
1037 {
1048 }
1050 /**
1051 * g_file_query_exists:
1052 * @file: input #GFile
1053 * @cancellable: (allow-none): optional #GCancellable object,
1054 * %NULL to ignore
1055 *
1056 * Utility function to check if a particular file exists. This is
1057 * implemented using g_file_query_info() and as such does blocking I/O.
1058 *
1059 * Note that in many cases it is racy to first check for file existence
1060 * and then execute something based on the outcome of that, because the
1061 * file might have been created or removed in between the operations. The
1062 * general approach to handling that is to not check, but just do the
1063 * operation and handle the errors as they come.
1064 *
1065 * As an example of race-free checking, take the case of reading a file,
1066 * and if it doesn't exist, creating it. There are two racy versions: read
1067 * it, and on error create it; and: check if it exists, if not create it.
1068 * These can both result in two processes creating the file (with perhaps
1069 * a partially written file as the result). The correct approach is to
1070 * always try to create the file with g_file_create() which will either
1071 * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
1072 *
1073 * However, in many cases an existence check is useful in a user interface,
1074 * for instance to make a menu item sensitive/insensitive, so that you don't
1075 * have to fool users that something is possible and then just show an error
1076 * dialog. If you do this, you should make sure to also handle the errors
1077 * that can happen due to races when you execute the operation.
1078 *
1079 * Returns: %TRUE if the file exists (and can be detected without error),
1080 * %FALSE otherwise (or if cancelled).
1081 */
1082 gboolean
1085 {
1093 {
1096 }
1099 }
1101 /**
1102 * g_file_query_file_type:
1103 * @file: input #GFile
1104 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
1105 * @cancellable: (allow-none): optional #GCancellable object,
1106 * %NULL to ignore
1107 *
1108 * Utility function to inspect the #GFileType of a file. This is
1109 * implemented using g_file_query_info() and as such does blocking I/O.
1110 *
1111 * The primary use case of this method is to check if a file is
1112 * a regular file, directory, or symlink.
1113 *
1114 * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN
1115 * if the file does not exist
1116 *
1117 * Since: 2.18
1118 */
1119 GFileType
1121 GFileQueryInfoFlags flags,
1123 {
1125 GFileType file_type;
1131 {
1134 }
1135 else
1139 }
1141 /**
1142 * g_file_query_info:
1143 * @file: input #GFile
1144 * @attributes: an attribute query string
1145 * @flags: a set of #GFileQueryInfoFlags
1146 * @cancellable: (allow-none): optional #GCancellable object,
1147 * %NULL to ignore
1148 * @error: a #GError
1149 *
1150 * Gets the requested information about specified @file.
1151 * The result is a #GFileInfo object that contains key-value
1152 * attributes (such as the type or size of the file).
1153 *
1154 * The @attributes value is a string that specifies the file
1155 * attributes that should be gathered. It is not an error if
1156 * it's not possible to read a particular requested attribute
1157 * from a file - it just won't be set. @attributes should be a
1158 * comma-separated list of attributes or attribute wildcards.
1159 * The wildcard "*" means all attributes, and a wildcard like
1160 * "standard::*" means all attributes in the standard namespace.
1161 * An example attribute query be "standard::*,owner::user".
1162 * The standard attributes are available as defines, like
1163 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
1164 *
1165 * If @cancellable is not %NULL, then the operation can be cancelled
1166 * by triggering the cancellable object from another thread. If the
1167 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1168 * returned.
1169 *
1170 * For symlinks, normally the information about the target of the
1171 * symlink is returned, rather than information about the symlink
1172 * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
1173 * in @flags the information about the symlink itself will be returned.
1174 * Also, for symlinks that point to non-existing files the information
1175 * about the symlink itself will be returned.
1176 *
1177 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
1178 * returned. Other errors are possible too, and depend on what kind of
1179 * filesystem the file is on.
1180 *
1181 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
1182 * on error. Free the returned object with g_object_unref().
1183 */
1184 GFileInfo *
1187 GFileQueryInfoFlags flags,
1190 {
1201 {
1203 G_IO_ERROR_NOT_SUPPORTED,
1206 }
1209 }
1211 /**
1212 * g_file_query_info_async:
1213 * @file: input #GFile
1214 * @attributes: an attribute query string
1215 * @flags: a set of #GFileQueryInfoFlags
1216 * @io_priority: the <link linkend="io-priority">I/O priority</link>
1217 * of the request
1218 * @cancellable: (allow-none): optional #GCancellable object,
1219 * %NULL to ignore
1220 * @callback: (scope async): a #GAsyncReadyCallback to call when the
1221 * request is satisfied
1222 * @user_data: (closure): the data to pass to callback function
1223 *
1224 * Asynchronously gets the requested information about specified @file.
1225 * The result is a #GFileInfo object that contains key-value attributes
1226 * (such as type or size for the file).
1227 *
1228 * For more details, see g_file_query_info() which is the synchronous
1229 * version of this call.
1230 *
1231 * When the operation is finished, @callback will be called. You can
1232 * then call g_file_query_info_finish() to get the result of the operation.
1233 */
1234 void
1237 GFileQueryInfoFlags flags,
1240 GAsyncReadyCallback callback,
1241 gpointer user_data)
1242 {
1249 attributes,
1250 flags,
1251 io_priority,
1252 cancellable,
1253 callback,
1254 user_data);
1255 }
1257 /**
1258 * g_file_query_info_finish:
1259 * @file: input #GFile
1260 * @res: a #GAsyncResult
1261 * @error: a #GError
1262 *
1263 * Finishes an asynchronous file info query.
1264 * See g_file_query_info_async().
1265 *
1266 * Returns: (transfer full): #GFileInfo for given @file
1267 * or %NULL on error. Free the returned object with
1268 * g_object_unref().
1269 */
1270 GFileInfo *
1274 {
1285 }
1287 /**
1288 * g_file_query_filesystem_info:
1289 * @file: input #GFile
1290 * @attributes: an attribute query string
1291 * @cancellable: (allow-none): optional #GCancellable object,
1292 * %NULL to ignore
1293 * @error: a #GError
1294 *
1295 * Similar to g_file_query_info(), but obtains information
1296 * about the filesystem the @file is on, rather than the file itself.
1297 * For instance the amount of space available and the type of
1298 * the filesystem.
1299 *
1300 * The @attributes value is a string that specifies the attributes
1301 * that should be gathered. It is not an error if it's not possible
1302 * to read a particular requested attribute from a file - it just
1303 * won't be set. @attributes should be a comma-separated list of
1304 * attributes or attribute wildcards. The wildcard "*" means all
1305 * attributes, and a wildcard like "filesystem::*" means all attributes
1306 * in the filesystem namespace. The standard namespace for filesystem
1307 * attributes is "filesystem". Common attributes of interest are
1308 * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
1309 * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
1310 * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
1311 *
1312 * If @cancellable is not %NULL, then the operation can be cancelled
1313 * by triggering the cancellable object from another thread. If the
1314 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1315 * returned.
1316 *
1317 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
1318 * be returned. Other errors are possible too, and depend on what
1319 * kind of filesystem the file is on.
1320 *
1321 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
1322 * Free the returned object with g_object_unref().
1323 */
1324 GFileInfo *
1329 {
1340 {
1342 G_IO_ERROR_NOT_SUPPORTED,
1345 }
1348 }
1350 /**
1351 * g_file_query_filesystem_info_async:
1352 * @file: input #GFile
1353 * @attributes: an attribute query string
1354 * @io_priority: the <link linkend="io-priority">I/O priority</link>
1355 * of the request
1356 * @cancellable: (allow-none): optional #GCancellable object,
1357 * %NULL to ignore
1358 * @callback: (scope async): a #GAsyncReadyCallback to call
1359 * when the request is satisfied
1360 * @user_data: (closure): the data to pass to callback function
1361 *
1362 * Asynchronously gets the requested information about the filesystem
1363 * that the specified @file is on. The result is a #GFileInfo object
1364 * that contains key-value attributes (such as type or size for the
1365 * file).
1366 *
1367 * For more details, see g_file_query_filesystem_info() which is the
1368 * synchronous version of this call.
1369 *
1370 * When the operation is finished, @callback will be called. You can
1371 * then call g_file_query_info_finish() to get the result of the
1372 * operation.
1373 */
1374 void
1379 GAsyncReadyCallback callback,
1380 gpointer user_data)
1381 {
1388 attributes,
1389 io_priority,
1390 cancellable,
1391 callback,
1392 user_data);
1393 }
1395 /**
1396 * g_file_query_filesystem_info_finish:
1397 * @file: input #GFile
1398 * @res: a #GAsyncResult
1399 * @error: a #GError
1400 *
1401 * Finishes an asynchronous filesystem info query.
1402 * See g_file_query_filesystem_info_async().
1403 *
1404 * Returns: (transfer full): #GFileInfo for given @file
1405 * or %NULL on error.
1406 * Free the returned object with g_object_unref().
1407 */
1408 GFileInfo *
1412 {
1423 }
1425 /**
1426 * g_file_find_enclosing_mount:
1427 * @file: input #GFile
1428 * @cancellable: (allow-none): optional #GCancellable object,
1429 * %NULL to ignore
1430 * @error: a #GError
1431 *
1432 * Gets a #GMount for the #GFile.
1433 *
1434 * If the #GFileIface for @file does not have a mount (e.g.
1435 * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
1436 * and %NULL will be returned.
1437 *
1438 * If @cancellable is not %NULL, then the operation can be cancelled by
1439 * triggering the cancellable object from another thread. If the operation
1440 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
1441 *
1442 * Returns: (transfer full): a #GMount where the @file is located
1443 * or %NULL on error.
1444 * Free the returned object with g_object_unref().
1445 */
1446 GMount *
1450 {
1460 {
1463 /* Translators: This is an error message when
1464 * trying to find the enclosing (user visible)
1465 * mount of a file, but none exists.
1466 */
1469 }
1472 }
1474 /**
1475 * g_file_find_enclosing_mount_async:
1476 * @file: a #GFile
1477 * @io_priority: the <link linkend="io-priority">I/O priority</link>
1478 * of the request
1479 * @cancellable: (allow-none): optional #GCancellable object,
1480 * %NULL to ignore
1481 * @callback: (scope async): a #GAsyncReadyCallback to call
1482 * when the request is satisfied
1483 * @user_data: (closure): the data to pass to callback function
1484 *
1485 * Asynchronously gets the mount for the file.
1486 *
1487 * For more details, see g_file_find_enclosing_mount() which is
1488 * the synchronous version of this call.
1489 *
1490 * When the operation is finished, @callback will be called.
1491 * You can then call g_file_find_enclosing_mount_finish() to
1492 * get the result of the operation.
1493 */
1494 void
1498 GAsyncReadyCallback callback,
1499 gpointer user_data)
1500 {
1507 io_priority,
1508 cancellable,
1509 callback,
1510 user_data);
1511 }
1513 /**
1514 * g_file_find_enclosing_mount_finish:
1515 * @file: a #GFile
1516 * @res: a #GAsyncResult
1517 * @error: a #GError
1518 *
1519 * Finishes an asynchronous find mount request.
1520 * See g_file_find_enclosing_mount_async().
1521 *
1522 * Returns: (transfer full): #GMount for given @file or %NULL on error.
1523 * Free the returned object with g_object_unref().
1524 */
1525 GMount *
1529 {
1540 }
1543 /**
1544 * g_file_read:
1545 * @file: #GFile to read
1546 * @cancellable: (allow-none): a #GCancellable
1547 * @error: a #GError, or %NULL
1548 *
1549 * Opens a file for reading. The result is a #GFileInputStream that
1550 * can be used to read the contents of the file.
1551 *
1552 * If @cancellable is not %NULL, then the operation can be cancelled by
1553 * triggering the cancellable object from another thread. If the operation
1554 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
1555 *
1556 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
1557 * returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
1558 * error will be returned. Other errors are possible too, and depend
1559 * on what kind of filesystem the file is on.
1560 *
1561 * Virtual: read_fn
1562 * Returns: (transfer full): #GFileInputStream or %NULL on error.
1563 * Free the returned object with g_object_unref().
1564 */
1565 GFileInputStream *
1569 {
1580 {
1582 G_IO_ERROR_NOT_SUPPORTED,
1585 }
1588 }
1590 /**
1591 * g_file_append_to:
1592 * @file: input #GFile
1593 * @flags: a set of #GFileCreateFlags
1594 * @cancellable: (allow-none): optional #GCancellable object,
1595 * %NULL to ignore
1596 * @error: a #GError, or %NULL
1597 *
1598 * Gets an output stream for appending data to the file.
1599 * If the file doesn't already exist it is created.
1600 *
1601 * By default files created are generally readable by everyone,
1602 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1603 * will be made readable only to the current user, to the level that
1604 * is supported on the target filesystem.
1605 *
1606 * If @cancellable is not %NULL, then the operation can be cancelled
1607 * by triggering the cancellable object from another thread. If the
1608 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1609 * returned.
1610 *
1611 * Some file systems don't allow all file names, and may return an
1612 * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
1613 * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
1614 * possible too, and depend on what kind of filesystem the file is on.
1615 *
1616 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
1617 * Free the returned object with g_object_unref().
1618 */
1619 GFileOutputStream *
1621 GFileCreateFlags flags,
1624 {
1635 {
1637 G_IO_ERROR_NOT_SUPPORTED,
1640 }
1643 }
1645 /**
1646 * g_file_create:
1647 * @file: input #GFile
1648 * @flags: a set of #GFileCreateFlags
1649 * @cancellable: (allow-none): optional #GCancellable object,
1650 * %NULL to ignore
1651 * @error: a #GError, or %NULL
1652 *
1653 * Creates a new file and returns an output stream for writing to it.
1654 * The file must not already exist.
1655 *
1656 * By default files created are generally readable by everyone,
1657 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1658 * will be made readable only to the current user, to the level
1659 * that is supported on the target filesystem.
1660 *
1661 * If @cancellable is not %NULL, then the operation can be cancelled
1662 * by triggering the cancellable object from another thread. If the
1663 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1664 * returned.
1665 *
1666 * If a file or directory with this name already exists the
1667 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
1668 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
1669 * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
1670 * be returned. Other errors are possible too, and depend on what kind
1671 * of filesystem the file is on.
1672 *
1673 * Returns: (transfer full): a #GFileOutputStream for the newly created
1674 * file, or %NULL on error.
1675 * Free the returned object with g_object_unref().
1676 */
1677 GFileOutputStream *
1679 GFileCreateFlags flags,
1682 {
1693 {
1695 G_IO_ERROR_NOT_SUPPORTED,
1698 }
1701 }
1703 /**
1704 * g_file_replace:
1705 * @file: input #GFile
1706 * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link>
1707 * for the current #GFile, or #NULL to ignore
1708 * @make_backup: %TRUE if a backup should be created
1709 * @flags: a set of #GFileCreateFlags
1710 * @cancellable: (allow-none): optional #GCancellable object,
1711 * %NULL to ignore
1712 * @error: a #GError, or %NULL
1713 *
1714 * Returns an output stream for overwriting the file, possibly
1715 * creating a backup copy of the file first. If the file doesn't exist,
1716 * it will be created.
1717 *
1718 * This will try to replace the file in the safest way possible so
1719 * that any errors during the writing will not affect an already
1720 * existing copy of the file. For instance, for local files it
1721 * may write to a temporary file and then atomically rename over
1722 * the destination when the stream is closed.
1723 *
1724 * By default files created are generally readable by everyone,
1725 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1726 * will be made readable only to the current user, to the level that
1727 * is supported on the target filesystem.
1728 *
1729 * If @cancellable is not %NULL, then the operation can be cancelled
1730 * by triggering the cancellable object from another thread. If the
1731 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1732 * returned.
1733 *
1734 * If you pass in a non-%NULL @etag value, then this value is
1735 * compared to the current entity tag of the file, and if they differ
1736 * an %G_IO_ERROR_WRONG_ETAG error is returned. This generally means
1737 * that the file has been changed since you last read it. You can get
1738 * the new etag from g_file_output_stream_get_etag() after you've
1739 * finished writing and closed the #GFileOutputStream. When you load
1740 * a new file you can use g_file_input_stream_query_info() to get
1741 * the etag of the file.
1742 *
1743 * If @make_backup is %TRUE, this function will attempt to make a
1744 * backup of the current file before overwriting it. If this fails
1745 * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
1746 * want to replace anyway, try again with @make_backup set to %FALSE.
1747 *
1748 * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
1749 * be returned, and if the file is some other form of non-regular file
1750 * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
1751 * file systems don't allow all file names, and may return an
1752 * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
1753 * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
1754 * possible too, and depend on what kind of filesystem the file is on.
1755 *
1756 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
1757 * Free the returned object with g_object_unref().
1758 */
1759 GFileOutputStream *
1762 gboolean make_backup,
1763 GFileCreateFlags flags,
1766 {
1777 {
1779 G_IO_ERROR_NOT_SUPPORTED,
1782 }
1784 /* Handle empty tag string as NULL in consistent way. */
1789 }
1791 /**
1792 * g_file_open_readwrite:
1793 * @file: #GFile to open
1794 * @cancellable: (allow-none): a #GCancellable
1795 * @error: a #GError, or %NULL
1796 *
1797 * Opens an existing file for reading and writing. The result is
1798 * a #GFileIOStream that can be used to read and write the contents
1799 * of the file.
1800 *
1801 * If @cancellable is not %NULL, then the operation can be cancelled
1802 * by triggering the cancellable object from another thread. If the
1803 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1804 * returned.
1805 *
1806 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
1807 * be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
1808 * error will be returned. Other errors are possible too, and depend on
1809 * what kind of filesystem the file is on. Note that in many non-local
1810 * file cases read and write streams are not supported, so make sure you
1811 * really need to do read and write streaming, rather than just opening
1812 * for reading or writing.
1813 *
1814 * Returns: (transfer full): #GFileIOStream or %NULL on error.
1815 * Free the returned object with g_object_unref().
1816 *
1817 * Since: 2.22
1818 */
1819 GFileIOStream *
1823 {
1834 {
1836 G_IO_ERROR_NOT_SUPPORTED,
1839 }
1842 }
1844 /**
1845 * g_file_create_readwrite:
1846 * @file: a #GFile
1847 * @flags: a set of #GFileCreateFlags
1848 * @cancellable: (allow-none): optional #GCancellable object,
1849 * %NULL to ignore
1850 * @error: return location for a #GError, or %NULL
1851 *
1852 * Creates a new file and returns a stream for reading and
1853 * writing to it. The file must not already exist.
1854 *
1855 * By default files created are generally readable by everyone,
1856 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1857 * will be made readable only to the current user, to the level
1858 * that is supported on the target filesystem.
1859 *
1860 * If @cancellable is not %NULL, then the operation can be cancelled
1861 * by triggering the cancellable object from another thread. If the
1862 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1863 * returned.
1864 *
1865 * If a file or directory with this name already exists, the
1866 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
1867 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
1868 * error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
1869 * will be returned. Other errors are possible too, and depend on what
1870 * kind of filesystem the file is on.
1871 *
1872 * Note that in many non-local file cases read and write streams are
1873 * not supported, so make sure you really need to do read and write
1874 * streaming, rather than just opening for reading or writing.
1875 *
1876 * Returns: (transfer full): a #GFileIOStream for the newly created
1877 * file, or %NULL on error.
1878 * Free the returned object with g_object_unref().
1879 *
1880 * Since: 2.22
1881 */
1882 GFileIOStream *
1884 GFileCreateFlags flags,
1887 {
1898 {
1900 G_IO_ERROR_NOT_SUPPORTED,
1903 }
1906 }
1908 /**
1909 * g_file_replace_readwrite:
1910 * @file: a #GFile
1911 * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link>
1912 * for the current #GFile, or #NULL to ignore
1913 * @make_backup: %TRUE if a backup should be created
1914 * @flags: a set of #GFileCreateFlags
1915 * @cancellable: (allow-none): optional #GCancellable object,
1916 * %NULL to ignore
1917 * @error: return location for a #GError, or %NULL
1918 *
1919 * Returns an output stream for overwriting the file in readwrite mode,
1920 * possibly creating a backup copy of the file first. If the file doesn't
1921 * exist, it will be created.
1922 *
1923 * For details about the behaviour, see g_file_replace() which does the
1924 * same thing but returns an output stream only.
1925 *
1926 * Note that in many non-local file cases read and write streams are not
1927 * supported, so make sure you really need to do read and write streaming,
1928 * rather than just opening for reading or writing.
1929 *
1930 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
1931 * Free the returned object with g_object_unref().
1932 *
1933 * Since: 2.22
1934 */
1935 GFileIOStream *
1938 gboolean make_backup,
1939 GFileCreateFlags flags,
1942 {
1953 {
1955 G_IO_ERROR_NOT_SUPPORTED,
1958 }
1961 }
1963 /**
1964 * g_file_read_async:
1965 * @file: input #GFile
1966 * @io_priority: the <link linkend="io-priority">I/O priority</link>
1967 * of the request
1968 * @cancellable: (allow-none): optional #GCancellable object,
1969 * %NULL to ignore
1970 * @callback: (scope async): a #GAsyncReadyCallback to call
1971 * when the request is satisfied
1972 * @user_data: (closure): the data to pass to callback function
1973 *
1974 * Asynchronously opens @file for reading.
1975 *
1976 * For more details, see g_file_read() which is
1977 * the synchronous version of this call.
1978 *
1979 * When the operation is finished, @callback will be called.
1980 * You can then call g_file_read_finish() to get the result
1981 * of the operation.
1982 */
1983 void
1987 GAsyncReadyCallback callback,
1988 gpointer user_data)
1989 {
1996 io_priority,
1997 cancellable,
1998 callback,
1999 user_data);
2000 }
2002 /**
2003 * g_file_read_finish:
2004 * @file: input #GFile
2005 * @res: a #GAsyncResult
2006 * @error: a #GError, or %NULL
2007 *
2008 * Finishes an asynchronous file read operation started with
2009 * g_file_read_async().
2010 *
2011 * Returns: (transfer full): a #GFileInputStream or %NULL on error.
2012 * Free the returned object with g_object_unref().
2013 */
2014 GFileInputStream *
2018 {
2029 }
2031 /**
2032 * g_file_append_to_async:
2033 * @file: input #GFile
2034 * @flags: a set of #GFileCreateFlags
2035 * @io_priority: the <link linkend="io-priority">I/O priority</link>
2036 * of the request
2037 * @cancellable: (allow-none): optional #GCancellable object,
2038 * %NULL to ignore
2039 * @callback: (scope async): a #GAsyncReadyCallback to call
2040 * when the request is satisfied
2041 * @user_data: (closure): the data to pass to callback function
2042 *
2043 * Asynchronously opens @file for appending.
2044 *
2045 * For more details, see g_file_append_to() which is
2046 * the synchronous version of this call.
2047 *
2048 * When the operation is finished, @callback will be called.
2049 * You can then call g_file_append_to_finish() to get the result
2050 * of the operation.
2051 */
2052 void
2054 GFileCreateFlags flags,
2057 GAsyncReadyCallback callback,
2058 gpointer user_data)
2059 {
2066 flags,
2067 io_priority,
2068 cancellable,
2069 callback,
2070 user_data);
2071 }
2073 /**
2074 * g_file_append_to_finish:
2075 * @file: input #GFile
2076 * @res: #GAsyncResult
2077 * @error: a #GError, or %NULL
2078 *
2079 * Finishes an asynchronous file append operation started with
2080 * g_file_append_to_async().
2081 *
2082 * Returns: (transfer full): a valid #GFileOutputStream
2083 * or %NULL on error.
2084 * Free the returned object with g_object_unref().
2085 */
2086 GFileOutputStream *
2090 {
2101 }
2103 /**
2104 * g_file_create_async:
2105 * @file: input #GFile
2106 * @flags: a set of #GFileCreateFlags
2107 * @io_priority: the <link linkend="io-priority">I/O priority</link>
2108 * of the request
2109 * @cancellable: (allow-none): optional #GCancellable object,
2110 * %NULL to ignore
2111 * @callback: (scope async): a #GAsyncReadyCallback to call
2112 * when the request is satisfied
2113 * @user_data: (closure): the data to pass to callback function
2114 *
2115 * Asynchronously creates a new file and returns an output stream
2116 * for writing to it. The file must not already exist.
2117 *
2118 * For more details, see g_file_create() which is
2119 * the synchronous version of this call.
2120 *
2121 * When the operation is finished, @callback will be called.
2122 * You can then call g_file_create_finish() to get the result
2123 * of the operation.
2124 */
2125 void
2127 GFileCreateFlags flags,
2130 GAsyncReadyCallback callback,
2131 gpointer user_data)
2132 {
2139 flags,
2140 io_priority,
2141 cancellable,
2142 callback,
2143 user_data);
2144 }
2146 /**
2147 * g_file_create_finish:
2148 * @file: input #GFile
2149 * @res: a #GAsyncResult
2150 * @error: a #GError, or %NULL
2151 *
2152 * Finishes an asynchronous file create operation started with
2153 * g_file_create_async().
2154 *
2155 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
2156 * Free the returned object with g_object_unref().
2157 */
2158 GFileOutputStream *
2162 {
2173 }
2175 /**
2176 * g_file_replace_async:
2177 * @file: input #GFile
2178 * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link>
2179 * for the current #GFile, or NULL to ignore
2180 * @make_backup: %TRUE if a backup should be created
2181 * @flags: a set of #GFileCreateFlags
2182 * @io_priority: the <link linkend="io-priority">I/O priority</link>
2183 * of the request
2184 * @cancellable: (allow-none): optional #GCancellable object,
2185 * %NULL to ignore
2186 * @callback: (scope async): a #GAsyncReadyCallback to call
2187 * when the request is satisfied
2188 * @user_data: (closure): the data to pass to callback function
2189 *
2190 * Asynchronously overwrites the file, replacing the contents,
2191 * possibly creating a backup copy of the file first.
2192 *
2193 * For more details, see g_file_replace() which is
2194 * the synchronous version of this call.
2195 *
2196 * When the operation is finished, @callback will be called.
2197 * You can then call g_file_replace_finish() to get the result
2198 * of the operation.
2199 */
2200 void
2203 gboolean make_backup,
2204 GFileCreateFlags flags,
2207 GAsyncReadyCallback callback,
2208 gpointer user_data)
2209 {
2216 etag,
2217 make_backup,
2218 flags,
2219 io_priority,
2220 cancellable,
2221 callback,
2222 user_data);
2223 }
2225 /**
2226 * g_file_replace_finish:
2227 * @file: input #GFile
2228 * @res: a #GAsyncResult
2229 * @error: a #GError, or %NULL
2230 *
2231 * Finishes an asynchronous file replace operation started with
2232 * g_file_replace_async().
2233 *
2234 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
2235 * Free the returned object with g_object_unref().
2236 */
2237 GFileOutputStream *
2241 {
2252 }
2254 /**
2255 * g_file_open_readwrite_async
2256 * @file: input #GFile
2257 * @io_priority: the <link linkend="io-priority">I/O priority</link>
2258 * of the request
2259 * @cancellable: (allow-none): optional #GCancellable object,
2260 * %NULL to ignore
2261 * @callback: (scope async): a #GAsyncReadyCallback to call
2262 * when the request is satisfied
2263 * @user_data: (closure): the data to pass to callback function
2264 *
2265 * Asynchronously opens @file for reading and writing.
2266 *
2267 * For more details, see g_file_open_readwrite() which is
2268 * the synchronous version of this call.
2269 *
2270 * When the operation is finished, @callback will be called.
2271 * You can then call g_file_open_readwrite_finish() to get
2272 * the result of the operation.
2273 *
2274 * Since: 2.22
2275 */
2276 void
2280 GAsyncReadyCallback callback,
2281 gpointer user_data)
2282 {
2289 io_priority,
2290 cancellable,
2291 callback,
2292 user_data);
2293 }
2295 /**
2296 * g_file_open_readwrite_finish:
2297 * @file: input #GFile
2298 * @res: a #GAsyncResult
2299 * @error: a #GError, or %NULL
2300 *
2301 * Finishes an asynchronous file read operation started with
2302 * g_file_open_readwrite_async().
2303 *
2304 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
2305 * Free the returned object with g_object_unref().
2306 *
2307 * Since: 2.22
2308 */
2309 GFileIOStream *
2313 {
2324 }
2326 /**
2327 * g_file_create_readwrite_async:
2328 * @file: input #GFile
2329 * @flags: a set of #GFileCreateFlags
2330 * @io_priority: the <link linkend="io-priority">I/O priority</link>
2331 * of the request
2332 * @cancellable: (allow-none): optional #GCancellable object,
2333 * %NULL to ignore
2334 * @callback: (scope async): a #GAsyncReadyCallback to call
2335 * when the request is satisfied
2336 * @user_data: (closure): the data to pass to callback function
2337 *
2338 * Asynchronously creates a new file and returns a stream
2339 * for reading and writing to it. The file must not already exist.
2340 *
2341 * For more details, see g_file_create_readwrite() which is
2342 * the synchronous version of this call.
2343 *
2344 * When the operation is finished, @callback will be called.
2345 * You can then call g_file_create_readwrite_finish() to get
2346 * the result of the operation.
2347 *
2348 * Since: 2.22
2349 */
2350 void
2352 GFileCreateFlags flags,
2355 GAsyncReadyCallback callback,
2356 gpointer user_data)
2357 {
2364 flags,
2365 io_priority,
2366 cancellable,
2367 callback,
2368 user_data);
2369 }
2371 /**
2372 * g_file_create_readwrite_finish:
2373 * @file: input #GFile
2374 * @res: a #GAsyncResult
2375 * @error: a #GError, or %NULL
2376 *
2377 * Finishes an asynchronous file create operation started with
2378 * g_file_create_readwrite_async().
2379 *
2380 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
2381 * Free the returned object with g_object_unref().
2382 *
2383 * Since: 2.22
2384 */
2385 GFileIOStream *
2389 {
2400 }
2402 /**
2403 * g_file_replace_readwrite_async:
2404 * @file: input #GFile
2405 * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link>
2406 * for the current #GFile, or NULL to ignore
2407 * @make_backup: %TRUE if a backup should be created
2408 * @flags: a set of #GFileCreateFlags
2409 * @io_priority: the <link linkend="io-priority">I/O priority</link>
2410 * of the request
2411 * @cancellable: (allow-none): optional #GCancellable object,
2412 * %NULL to ignore
2413 * @callback: (scope async): a #GAsyncReadyCallback to call
2414 * when the request is satisfied
2415 * @user_data: (closure): the data to pass to callback function
2416 *
2417 * Asynchronously overwrites the file in read-write mode,
2418 * replacing the contents, possibly creating a backup copy
2419 * of the file first.
2420 *
2421 * For more details, see g_file_replace_readwrite() which is
2422 * the synchronous version of this call.
2423 *
2424 * When the operation is finished, @callback will be called.
2425 * You can then call g_file_replace_readwrite_finish() to get
2426 * the result of the operation.
2427 *
2428 * Since: 2.22
2429 */
2430 void
2433 gboolean make_backup,
2434 GFileCreateFlags flags,
2437 GAsyncReadyCallback callback,
2438 gpointer user_data)
2439 {
2446 etag,
2447 make_backup,
2448 flags,
2449 io_priority,
2450 cancellable,
2451 callback,
2452 user_data);
2453 }
2455 /**
2456 * g_file_replace_readwrite_finish:
2457 * @file: input #GFile
2458 * @res: a #GAsyncResult
2459 * @error: a #GError, or %NULL
2460 *
2461 * Finishes an asynchronous file replace operation started with
2462 * g_file_replace_readwrite_async().
2463 *
2464 * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
2465 * Free the returned object with g_object_unref().
2466 *
2467 * Since: 2.22
2468 */
2469 GFileIOStream *
2473 {
2484 }
2486 static gboolean
2488 GFileCopyFlags flags,
2492 {
2494 gboolean tried_delete;
2496 GFileType file_type;
2500 retry:
2503 {
2504 /* Maybe it already existed, and we want to overwrite? */
2507 {
2510 /* Don't overwrite if the destination is a directory */
2512 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2515 {
2520 {
2524 }
2525 }
2532 }
2533 /* Nah, fail */
2536 }
2539 }
2544 GFileCopyFlags flags,
2547 {
2551 GFileType file_type;
2558 /* There was an error opening the source, try to set a good error for it: */
2560 {
2561 /* The source is a directory, don't fail with WOULD_RECURSE immediately,
2562 * as that is less useful to the app. Better check for errors on the
2563 * target instead.
2564 */
2569 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2573 {
2578 {
2580 {
2584 }
2585 /* continue to would_recurse error */
2586 }
2587 else
2588 {
2592 }
2593 }
2594 else
2595 {
2596 /* Error getting info from target, return that error
2597 * (except for NOT_FOUND, which is no error here)
2598 */
2601 {
2604 }
2606 }
2611 }
2615 }
2617 static gboolean
2619 gboolean copy_all_attributes,
2620 gboolean skip_perms)
2621 {
2628 }
2630 static gboolean
2632 GFileCopyFlags flags,
2636 {
2640 gboolean first;
2642 gboolean copy_all_attributes;
2643 gboolean skip_perms;
2648 /* Ignore errors here, if the target supports no attributes there is
2649 * nothing to copy. We still honor the cancellable though.
2650 */
2666 {
2668 {
2670 {
2673 else
2677 }
2678 }
2679 }
2682 {
2684 {
2686 {
2689 else
2694 }
2695 }
2696 }
2701 out:
2710 }
2712 /**
2713 * g_file_copy_attributes:
2714 * @source: a #GFile with attributes
2715 * @destination: a #GFile to copy attributes to
2716 * @flags: a set of #GFileCopyFlags
2717 * @cancellable: (allow-none): optional #GCancellable object,
2718 * %NULL to ignore
2719 * @error: a #GError, %NULL to ignore
2720 *
2721 * Copies the file attributes from @source to @destination.
2722 *
2723 * Normally only a subset of the file attributes are copied,
2724 * those that are copies in a normal file copy operation
2725 * (which for instance does not include e.g. owner). However
2726 * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
2727 * all the metadata that is possible to copy is copied. This
2728 * is useful when implementing move by copy + delete source.
2729 *
2730 * Returns: %TRUE if the attributes were copied successfully,
2731 * %FALSE otherwise.
2732 */
2733 gboolean
2736 GFileCopyFlags flags,
2739 {
2741 gboolean res;
2743 gboolean source_nofollow_symlinks;
2751 /* Ignore errors here, if we can't read some info (e.g. if it doesn't exist)
2752 * we just don't copy it.
2753 */
2756 cancellable,
2757 NULL);
2763 {
2765 info,
2766 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2767 cancellable,
2768 error);
2770 }
2773 }
2775 static gboolean
2780 GFileProgressCallback progress_callback,
2781 gpointer progress_callback_data,
2783 {
2785 goffset current_size;
2787 gboolean res;
2788 goffset total_size;
2792 /* avoid performance impact of querying total size when it's not needed */
2794 {
2796 G_FILE_ATTRIBUTE_STANDARD_SIZE,
2799 {
2803 }
2806 {
2808 G_FILE_ATTRIBUTE_STANDARD_SIZE,
2809 G_FILE_QUERY_INFO_NONE,
2812 {
2816 }
2817 }
2818 }
2826 {
2829 {
2832 }
2841 {
2844 {
2847 }
2851 }
2858 }
2860 /* Make sure we send full copied size */
2865 }
2867 #ifdef HAVE_SPLICE
2869 static gboolean
2877 {
2880 retry:
2884 {
2892 else
2899 }
2903 }
2905 static gboolean
2909 GFileProgressCallback progress_callback,
2910 gpointer progress_callback_data,
2912 {
2914 gboolean res;
2915 goffset total_size;
2916 loff_t offset_in;
2917 loff_t offset_out;
2927 /* avoid performance impact of querying total size when it's not needed */
2929 {
2934 }
2942 {
2953 {
2956 }
2959 {
2967 }
2971 }
2973 /* Make sure we send full copied size */
2983 out:
2990 }
2991 #endif
2993 #ifdef __linux__
2994 static gboolean
2999 GFileProgressCallback progress_callback,
3000 gpointer progress_callback_data,
3002 {
3003 goffset source_size;
3013 /* Btrfs clone ioctl properties:
3014 * - Works at the inode level
3015 * - Doesn't work with directories
3016 * - Always follows symlinks (source and destination)
3017 *
3018 * By the time we get here, *in and *out are both regular files */
3022 {
3025 G_IO_ERROR_NOT_SUPPORTED,
3029 G_IO_ERROR_NOT_SUPPORTED,
3031 else
3032 /* Most probably something odd happened; retry with fallback */
3034 G_IO_ERROR_NOT_SUPPORTED,
3036 /* We retry with fallback for all error cases because Btrfs is currently
3037 * unstable, and so we can't trust it to do clone properly.
3038 * In addition, any hard errors here would cause the same failure in the
3039 * fallback manual copy as well. */
3041 }
3043 /* Make sure we send full copied size */
3048 }
3049 #endif
3051 static gboolean
3054 GFileCopyFlags flags,
3056 GFileProgressCallback progress_callback,
3057 gpointer progress_callback_data,
3059 {
3069 /* need to know the file type */
3072 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3073 cancellable,
3074 error);
3078 /* Maybe copy the symlink? */
3081 {
3084 {
3090 }
3091 /* ... else fall back on a regular file copy */
3092 }
3093 /* Handle "special" files (pipes, device nodes, ...)? */
3095 {
3096 /* FIXME: could try to recreate device nodes and others? */
3100 }
3102 /* Everything else should just fall back on a regular copy. */
3114 {
3117 /* Ok, ditch the previous lightweight info (on Unix we just
3118 * called lstat()); at this point we gather all the information
3119 * we need about the source from the opened file descriptor.
3120 */
3126 {
3127 /* Not all gvfs backends implement query_info_on_read(), we
3128 * can just fall back to the pathname again.
3129 * https://bugzilla.gnome.org/706254
3130 */
3132 {
3136 }
3137 else
3138 {
3142 }
3143 }
3149 }
3151 /* In the local file path, we pass down the source info which
3152 * includes things like unix::mode, to ensure that the target file
3153 * is not created with different permissions from the source file.
3154 *
3155 * If a future API like g_file_replace_with_info() is added, switch
3156 * this code to use that.
3157 */
3159 {
3161 out = (GOutputStream*)_g_local_file_output_stream_replace (_g_local_file_get_filename (G_LOCAL_FILE (destination)),
3164 G_FILE_CREATE_REPLACE_DESTINATION,
3165 info,
3167 else
3168 out = (GOutputStream*)_g_local_file_output_stream_create (_g_local_file_get_filename (G_LOCAL_FILE (destination)),
3171 }
3173 {
3175 NULL,
3177 G_FILE_CREATE_REPLACE_DESTINATION,
3179 }
3180 else
3181 {
3183 }
3188 #ifdef __linux__
3190 {
3196 {
3198 {
3200 }
3201 else
3202 {
3205 }
3206 }
3207 else
3208 {
3211 }
3212 }
3213 #endif
3215 #ifdef HAVE_SPLICE
3217 {
3223 {
3225 {
3227 }
3228 else
3229 {
3232 }
3233 }
3234 else
3235 {
3238 }
3239 }
3241 #endif
3243 /* A plain read/write loop */
3246 error))
3250 out:
3252 {
3253 /* Don't care about errors in source here */
3256 }
3259 {
3260 /* But write errors on close are bad! */
3264 }
3266 /* Ignore errors here. Failure to copy metadata is not a hard error */
3267 /* TODO: set these attributes /before/ we do the rename() on Unix */
3269 {
3271 info,
3272 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3273 cancellable,
3274 error);
3275 }
3280 }
3282 /**
3283 * g_file_copy:
3284 * @source: input #GFile
3285 * @destination: destination #GFile
3286 * @flags: set of #GFileCopyFlags
3287 * @cancellable: (allow-none): optional #GCancellable object,
3288 * %NULL to ignore
3289 * @progress_callback: (allow-none) (scope call): function to callback with
3290 * progress information, or %NULL if progress information is not needed
3291 * @progress_callback_data: (closure): user data to pass to @progress_callback
3292 * @error: #GError to set on error, or %NULL
3293 *
3294 * Copies the file @source to the location specified by @destination.
3295 * Can not handle recursive copies of directories.
3296 *
3297 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
3298 * existing @destination file is overwritten.
3299 *
3300 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
3301 * will be copied as symlinks, otherwise the target of the
3302 * @source symlink will be copied.
3303 *
3304 * If @cancellable is not %NULL, then the operation can be cancelled by
3305 * triggering the cancellable object from another thread. If the operation
3306 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3307 *
3308 * If @progress_callback is not %NULL, then the operation can be monitored
3309 * by setting this to a #GFileProgressCallback function.
3310 * @progress_callback_data will be passed to this function. It is guaranteed
3311 * that this callback will be called after all data has been transferred with
3312 * the total number of bytes copied during the operation.
3313 *
3314 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
3315 * is returned, independent on the status of the @destination.
3316 *
3317 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
3318 * the error %G_IO_ERROR_EXISTS is returned.
3319 *
3320 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
3321 * error is returned. If trying to overwrite a directory with a directory the
3322 * %G_IO_ERROR_WOULD_MERGE error is returned.
3323 *
3324 * If the source is a directory and the target does not exist, or
3325 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
3326 * %G_IO_ERROR_WOULD_RECURSE error is returned.
3327 *
3328 * If you are interested in copying the #GFile object itself (not the on-disk
3329 * file), see g_file_dup().
3330 *
3331 * Returns: %TRUE on success, %FALSE otherwise.
3332 */
3333 gboolean
3336 GFileCopyFlags flags,
3338 GFileProgressCallback progress_callback,
3339 gpointer progress_callback_data,
3341 {
3344 gboolean res;
3354 {
3365 {
3368 }
3369 else
3371 }
3373 /* If the types are different, and the destination method failed
3374 * also try the source method
3375 */
3377 {
3381 {
3392 {
3395 }
3396 else
3398 }
3399 }
3403 error);
3404 }
3406 /**
3407 * g_file_copy_async: (skip)
3408 * @source: input #GFile
3409 * @destination: destination #GFile
3410 * @flags: set of #GFileCopyFlags
3411 * @io_priority: the <link linkend="io-priority">I/O priority</link>
3412 * of the request
3413 * @cancellable: (allow-none): optional #GCancellable object,
3414 * %NULL to ignore
3415 * @progress_callback: (allow-none): function to callback with progress
3416 * information, or %NULL if progress information is not needed
3417 * @progress_callback_data: (closure): user data to pass to @progress_callback
3418 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
3419 * @user_data: the data to pass to callback function
3420 *
3421 * Copies the file @source to the location specified by @destination
3422 * asynchronously. For details of the behaviour, see g_file_copy().
3423 *
3424 * If @progress_callback is not %NULL, then that function that will be called
3425 * just like in g_file_copy(), however the callback will run in the main loop,
3426 * not in the thread that is doing the I/O operation.
3427 *
3428 * When the operation is finished, @callback will be called. You can then call
3429 * g_file_copy_finish() to get the result of the operation.
3430 */
3431 void
3434 GFileCopyFlags flags,
3437 GFileProgressCallback progress_callback,
3438 gpointer progress_callback_data,
3439 GAsyncReadyCallback callback,
3440 gpointer user_data)
3441 {
3449 destination,
3450 flags,
3451 io_priority,
3452 cancellable,
3453 progress_callback,
3454 progress_callback_data,
3455 callback,
3456 user_data);
3457 }
3459 /**
3460 * g_file_copy_finish:
3461 * @file: input #GFile
3462 * @res: a #GAsyncResult
3463 * @error: a #GError, or %NULL
3464 *
3465 * Finishes copying the file started with g_file_copy_async().
3466 *
3467 * Returns: a %TRUE on success, %FALSE on error.
3468 */
3469 gboolean
3473 {
3484 }
3486 /**
3487 * g_file_move:
3488 * @source: #GFile pointing to the source location
3489 * @destination: #GFile pointing to the destination location
3490 * @flags: set of #GFileCopyFlags
3491 * @cancellable: (allow-none): optional #GCancellable object,
3492 * %NULL to ignore
3493 * @progress_callback: (allow-none) (scope call): #GFileProgressCallback
3494 * function for updates
3495 * @progress_callback_data: (closure): gpointer to user data for
3496 * the callback function
3497 * @error: #GError for returning error conditions, or %NULL
3498 *
3499 * Tries to move the file or directory @source to the location specified
3500 * by @destination. If native move operations are supported then this is
3501 * used, otherwise a copy + delete fallback is used. The native
3502 * implementation may support moving directories (for instance on moves
3503 * inside the same filesystem), but the fallback code does not.
3504 *
3505 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
3506 * existing @destination file is overwritten.
3507 *
3508 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
3509 * will be copied as symlinks, otherwise the target of the
3510 * @source symlink will be copied.
3511 *
3512 * If @cancellable is not %NULL, then the operation can be cancelled by
3513 * triggering the cancellable object from another thread. If the operation
3514 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3515 *
3516 * If @progress_callback is not %NULL, then the operation can be monitored
3517 * by setting this to a #GFileProgressCallback function.
3518 * @progress_callback_data will be passed to this function. It is
3519 * guaranteed that this callback will be called after all data has been
3520 * transferred with the total number of bytes copied during the operation.
3521 *
3522 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
3523 * error is returned, independent on the status of the @destination.
3524 *
3525 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
3526 * then the error %G_IO_ERROR_EXISTS is returned.
3527 *
3528 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
3529 * error is returned. If trying to overwrite a directory with a directory the
3530 * %G_IO_ERROR_WOULD_MERGE error is returned.
3531 *
3532 * If the source is a directory and the target does not exist, or
3533 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then
3534 * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
3535 * move operation isn't available).
3536 *
3537 * Returns: %TRUE on successful move, %FALSE otherwise.
3538 */
3539 gboolean
3542 GFileCopyFlags flags,
3544 GFileProgressCallback progress_callback,
3545 gpointer progress_callback_data,
3547 {
3550 gboolean res;
3560 {
3571 {
3574 }
3575 }
3577 /* If the types are different, and the destination method failed
3578 * also try the source method
3579 */
3581 {
3585 {
3596 {
3599 }
3600 }
3601 }
3604 {
3606 G_IO_ERROR_NOT_SUPPORTED,
3609 }
3614 error))
3618 }
3620 /**
3621 * g_file_make_directory:
3622 * @file: input #GFile
3623 * @cancellable: (allow-none): optional #GCancellable object,
3624 * %NULL to ignore
3625 * @error: a #GError, or %NULL
3626 *
3627 * Creates a directory. Note that this will only create a child directory
3628 * of the immediate parent directory of the path or URI given by the #GFile.
3629 * To recursively create directories, see g_file_make_directory_with_parents().
3630 * This function will fail if the parent directory does not exist, setting
3631 * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
3632 * creating directories, this function will fail, setting @error to
3633 * %G_IO_ERROR_NOT_SUPPORTED.
3634 *
3635 * For a local #GFile the newly created directory will have the default
3636 * (current) ownership and permissions of the current process.
3637 *
3638 * If @cancellable is not %NULL, then the operation can be cancelled by
3639 * triggering the cancellable object from another thread. If the operation
3640 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3641 *
3642 * Returns: %TRUE on successful creation, %FALSE otherwise.
3643 */
3644 gboolean
3648 {
3659 {
3661 G_IO_ERROR_NOT_SUPPORTED,
3664 }
3667 }
3669 /**
3670 * g_file_make_directory_async:
3671 * @file: input #GFile
3672 * @io_priority: the <link linkend="io-priority">I/O priority</link>
3673 * of the request
3674 * @cancellable: (allow-none): optional #GCancellable object,
3675 * %NULL to ignore
3676 * @callback: a #GAsyncReadyCallback to call
3677 * when the request is satisfied
3678 * @user_data: the data to pass to callback function
3679 *
3680 * Asynchronously creates a directory.
3681 *
3682 * Virtual: make_directory_async
3683 * Since: 2.38
3684 */
3685 void
3689 GAsyncReadyCallback callback,
3690 gpointer user_data)
3691 {
3698 io_priority,
3699 cancellable,
3700 callback,
3701 user_data);
3702 }
3704 /**
3705 * g_file_make_directory_finish:
3706 * @file: input #GFile
3707 * @result: a #GAsyncResult
3708 * @error: a #GError, or %NULL
3709 *
3710 * Finishes an asynchronous directory creation, started with
3711 * g_file_make_directory_async().
3712 *
3713 * Virtual: make_directory_finish
3714 * Returns: %TRUE on successful directory creation, %FALSE otherwise.
3715 * Since: 2.38
3716 */
3717 gboolean
3721 {
3729 }
3731 /**
3732 * g_file_make_directory_with_parents:
3733 * @file: input #GFile
3734 * @cancellable: (allow-none): optional #GCancellable object,
3735 * %NULL to ignore
3736 * @error: a #GError, or %NULL
3737 *
3738 * Creates a directory and any parent directories that may not
3739 * exist similar to 'mkdir -p'. If the file system does not support
3740 * creating directories, this function will fail, setting @error to
3741 * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
3742 * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
3743 * the similar g_mkdir_with_parents().
3744 *
3745 * For a local #GFile the newly created directories will have the default
3746 * (current) ownership and permissions of the current process.
3747 *
3748 * If @cancellable is not %NULL, then the operation can be cancelled by
3749 * triggering the cancellable object from another thread. If the operation
3750 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3751 *
3752 * Returns: %TRUE if all directories have been successfully created, %FALSE
3753 * otherwise.
3754 *
3755 * Since: 2.18
3756 */
3757 gboolean
3761 {
3773 {
3777 }
3782 {
3797 else
3799 }
3802 {
3804 }
3809 /* Clean up */
3811 {
3814 }
3817 {
3820 }
3823 }
3825 /**
3826 * g_file_make_symbolic_link:
3827 * @file: a #GFile with the name of the symlink to create
3828 * @symlink_value: a string with the path for the target of the new symlink
3829 * @cancellable: (allow-none): optional #GCancellable object,
3830 * %NULL to ignore
3831 * @error: a #GError
3832 *
3833 * Creates a symbolic link named @file which contains the string
3834 * @symlink_value.
3835 *
3836 * If @cancellable is not %NULL, then the operation can be cancelled by
3837 * triggering the cancellable object from another thread. If the operation
3838 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3839 *
3840 * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
3841 */
3842 gboolean
3847 {
3857 {
3859 G_IO_ERROR_INVALID_ARGUMENT,
3862 }
3867 {
3869 G_IO_ERROR_NOT_SUPPORTED,
3872 }
3875 }
3877 /**
3878 * g_file_delete:
3879 * @file: input #GFile
3880 * @cancellable: (allow-none): optional #GCancellable object,
3881 * %NULL to ignore
3882 * @error: a #GError, or %NULL
3883 *
3884 * Deletes a file. If the @file is a directory, it will only be
3885 * deleted if it is empty. This has the same semantics as g_unlink().
3886 *
3887 * If @cancellable is not %NULL, then the operation can be cancelled by
3888 * triggering the cancellable object from another thread. If the operation
3889 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3890 *
3891 * Virtual: delete_file
3892 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
3893 */
3894 gboolean
3898 {
3909 {
3911 G_IO_ERROR_NOT_SUPPORTED,
3914 }
3917 }
3919 /**
3920 * g_file_delete_async:
3921 * @file: input #GFile
3922 * @io_priority: the <link linkend="io-priority">I/O priority</link>
3923 * of the request
3924 * @cancellable: (allow-none): optional #GCancellable object,
3925 * %NULL to ignore
3926 * @callback: a #GAsyncReadyCallback to call
3927 * when the request is satisfied
3928 * @user_data: the data to pass to callback function
3929 *
3930 * Asynchronously delete a file. If the @file is a directory, it will
3931 * only be deleted if it is empty. This has the same semantics as
3932 * g_unlink().
3933 *
3934 * Virtual: delete_file_async
3935 * Since: 2.34
3936 */
3937 void
3941 GAsyncReadyCallback callback,
3942 gpointer user_data)
3943 {
3950 io_priority,
3951 cancellable,
3952 callback,
3953 user_data);
3954 }
3956 /**
3957 * g_file_delete_finish:
3958 * @file: input #GFile
3959 * @result: a #GAsyncResult
3960 * @error: a #GError, or %NULL
3961 *
3962 * Finishes deleting a file started with g_file_delete_async().
3963 *
3964 * Virtual: delete_file_finish
3965 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
3966 * Since: 2.34
3967 **/
3968 gboolean
3972 {
3983 }
3985 /**
3986 * g_file_trash:
3987 * @file: #GFile to send to trash
3988 * @cancellable: (allow-none): optional #GCancellable object,
3989 * %NULL to ignore
3990 * @error: a #GError, or %NULL
3991 *
3992 * Sends @file to the "Trashcan", if possible. This is similar to
3993 * deleting it, but the user can recover it before emptying the trashcan.
3994 * Not all file systems support trashing, so this call can return the
3995 * %G_IO_ERROR_NOT_SUPPORTED error.
3996 *
3997 * If @cancellable is not %NULL, then the operation can be cancelled by
3998 * triggering the cancellable object from another thread. If the operation
3999 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4000 *
4001 * Virtual: trash
4002 * Returns: %TRUE on successful trash, %FALSE otherwise.
4003 */
4004 gboolean
4008 {
4019 {
4024 }
4027 }
4029 /**
4030 * g_file_trash_async:
4031 * @file: input #GFile
4032 * @io_priority: the <link linkend="io-priority">I/O priority</link>
4033 * of the request
4034 * @cancellable: (allow-none): optional #GCancellable object,
4035 * %NULL to ignore
4036 * @callback: a #GAsyncReadyCallback to call
4037 * when the request is satisfied
4038 * @user_data: the data to pass to callback function
4039 *
4040 * Asynchronously sends @file to the Trash location, if possible.
4041 *
4042 * Virtual: trash_async
4043 * Since: 2.38
4044 */
4045 void
4049 GAsyncReadyCallback callback,
4050 gpointer user_data)
4051 {
4058 io_priority,
4059 cancellable,
4060 callback,
4061 user_data);
4062 }
4064 /**
4065 * g_file_trash_finish:
4066 * @file: input #GFile
4067 * @result: a #GAsyncResult
4068 * @error: a #GError, or %NULL
4069 *
4070 * Finishes an asynchronous file trashing operation, started with
4071 * g_file_trash_async().
4072 *
4073 * Virtual: trash_finish
4074 * Returns: %TRUE on successful trash, %FALSE otherwise.
4075 * Since: 2.38
4076 */
4077 gboolean
4081 {
4089 }
4091 /**
4092 * g_file_set_display_name:
4093 * @file: input #GFile
4094 * @display_name: a string
4095 * @cancellable: (allow-none): optional #GCancellable object,
4096 * %NULL to ignore
4097 * @error: a #GError, or %NULL
4098 *
4099 * Renames @file to the specified display name.
4100 *
4101 * The display name is converted from UTF-8 to the correct encoding
4102 * for the target filesystem if possible and the @file is renamed to this.
4103 *
4104 * If you want to implement a rename operation in the user interface the
4105 * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
4106 * initial value in the rename widget, and then the result after editing
4107 * should be passed to g_file_set_display_name().
4108 *
4109 * On success the resulting converted filename is returned.
4110 *
4111 * If @cancellable is not %NULL, then the operation can be cancelled by
4112 * triggering the cancellable object from another thread. If the operation
4113 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4114 *
4115 * Returns: (transfer full): a #GFile specifying what @file was renamed to,
4116 * or %NULL if there was an error.
4117 * Free the returned object with g_object_unref().
4118 */
4119 GFile *
4124 {
4131 {
4133 G_IO_ERROR,
4134 G_IO_ERROR_INVALID_ARGUMENT,
4137 }
4145 }
4147 /**
4148 * g_file_set_display_name_async:
4149 * @file: input #GFile
4150 * @display_name: a string
4151 * @io_priority: the <link linkend="io-priority">I/O priority</link>
4152 * of the request
4153 * @cancellable: (allow-none): optional #GCancellable object,
4154 * %NULL to ignore
4155 * @callback: (scope async): a #GAsyncReadyCallback to call
4156 * when the request is satisfied
4157 * @user_data: (closure): the data to pass to callback function
4158 *
4159 * Asynchronously sets the display name for a given #GFile.
4160 *
4161 * For more details, see g_file_set_display_name() which is
4162 * the synchronous version of this call.
4163 *
4164 * When the operation is finished, @callback will be called.
4165 * You can then call g_file_set_display_name_finish() to get
4166 * the result of the operation.
4167 */
4168 void
4171 gint io_priority,
4173 GAsyncReadyCallback callback,
4174 gpointer user_data)
4175 {
4183 display_name,
4184 io_priority,
4185 cancellable,
4186 callback,
4187 user_data);
4188 }
4190 /**
4191 * g_file_set_display_name_finish:
4192 * @file: input #GFile
4193 * @res: a #GAsyncResult
4194 * @error: a #GError, or %NULL
4195 *
4196 * Finishes setting a display name started with
4197 * g_file_set_display_name_async().
4198 *
4199 * Returns: (transfer full): a #GFile or %NULL on error.
4200 * Free the returned object with g_object_unref().
4201 */
4202 GFile *
4206 {
4217 }
4219 /**
4220 * g_file_query_settable_attributes:
4221 * @file: input #GFile
4222 * @cancellable: (allow-none): optional #GCancellable object,
4223 * %NULL to ignore
4224 * @error: a #GError, or %NULL
4225 *
4226 * Obtain the list of settable attributes for the file.
4227 *
4228 * Returns the type and full attribute name of all the attributes
4229 * that can be set on this file. This doesn't mean setting it will
4230 * always succeed though, you might get an access failure, or some
4231 * specific file may not support a specific attribute.
4232 *
4233 * If @cancellable is not %NULL, then the operation can be cancelled by
4234 * triggering the cancellable object from another thread. If the operation
4235 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4236 *
4237 * Returns: a #GFileAttributeInfoList describing the settable attributes.
4238 * When you are done with it, release it with
4239 * g_file_attribute_info_list_unref()
4240 */
4241 GFileAttributeInfoList *
4245 {
4264 {
4266 {
4269 }
4270 else
4272 }
4275 }
4277 /**
4278 * g_file_query_writable_namespaces:
4279 * @file: input #GFile
4280 * @cancellable: (allow-none): optional #GCancellable object,
4281 * %NULL to ignore
4282 * @error: a #GError, or %NULL
4283 *
4284 * Obtain the list of attribute namespaces where new attributes
4285 * can be created by a user. An example of this is extended
4286 * attributes (in the "xattr" namespace).
4287 *
4288 * If @cancellable is not %NULL, then the operation can be cancelled by
4289 * triggering the cancellable object from another thread. If the operation
4290 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4291 *
4292 * Returns: a #GFileAttributeInfoList describing the writable namespaces.
4293 * When you are done with it, release it with
4294 * g_file_attribute_info_list_unref()
4295 */
4296 GFileAttributeInfoList *
4300 {
4319 {
4321 {
4324 }
4325 else
4327 }
4330 }
4332 /**
4333 * g_file_set_attribute:
4334 * @file: input #GFile
4335 * @attribute: a string containing the attribute's name
4336 * @type: The type of the attribute
4337 * @value_p: (allow-none): a pointer to the value (or the pointer
4338 * itself if the type is a pointer type)
4339 * @flags: a set of #GFileQueryInfoFlags
4340 * @cancellable: (allow-none): optional #GCancellable object,
4341 * %NULL to ignore
4342 * @error: a #GError, or %NULL
4343 *
4344 * Sets an attribute in the file with attribute name @attribute to @value.
4345 *
4346 * Some attributes can be unset by setting @attribute to
4347 * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
4348 *
4349 * If @cancellable is not %NULL, then the operation can be cancelled by
4350 * triggering the cancellable object from another thread. If the operation
4351 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4352 *
4353 * Returns: %TRUE if the attribute was set, %FALSE otherwise.
4354 */
4355 gboolean
4358 GFileAttributeType type,
4359 gpointer value_p,
4360 GFileQueryInfoFlags flags,
4363 {
4375 {
4377 G_IO_ERROR_NOT_SUPPORTED,
4380 }
4383 }
4385 /**
4386 * g_file_set_attributes_from_info:
4387 * @file: input #GFile
4388 * @info: a #GFileInfo
4389 * @flags: #GFileQueryInfoFlags
4390 * @cancellable: (allow-none): optional #GCancellable object,
4391 * %NULL to ignore
4392 * @error: a #GError, or %NULL
4393 *
4394 * Tries to set all attributes in the #GFileInfo on the target
4395 * values, not stopping on the first error.
4396 *
4397 * If there is any error during this operation then @error will
4398 * be set to the first error. Error on particular fields are flagged
4399 * by setting the "status" field in the attribute value to
4400 * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
4401 * also detect further errors.
4402 *
4403 * If @cancellable is not %NULL, then the operation can be cancelled by
4404 * triggering the cancellable object from another thread. If the operation
4405 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4406 *
4407 * Returns: %FALSE if there was any error, %TRUE otherwise.
4408 */
4409 gboolean
4412 GFileQueryInfoFlags flags,
4415 {
4429 info,
4430 flags,
4431 cancellable,
4432 error);
4433 }
4435 static gboolean
4438 GFileQueryInfoFlags flags,
4441 {
4444 gboolean res;
4452 {
4461 {
4464 /* Don't set error multiple times */
4466 }
4467 else
4469 }
4474 }
4476 /**
4477 * g_file_set_attributes_async:
4478 * @file: input #GFile
4479 * @info: a #GFileInfo
4480 * @flags: a #GFileQueryInfoFlags
4481 * @io_priority: the <link linkend="io-priority">I/O priority</link>
4482 * of the request
4483 * @cancellable: (allow-none): optional #GCancellable object,
4484 * %NULL to ignore
4485 * @callback: (scope async): a #GAsyncReadyCallback
4486 * @user_data: (closure): a #gpointer
4487 *
4488 * Asynchronously sets the attributes of @file with @info.
4489 *
4490 * For more details, see g_file_set_attributes_from_info(),
4491 * which is the synchronous version of this call.
4492 *
4493 * When the operation is finished, @callback will be called.
4494 * You can then call g_file_set_attributes_finish() to get
4495 * the result of the operation.
4496 */
4497 void
4500 GFileQueryInfoFlags flags,
4503 GAsyncReadyCallback callback,
4504 gpointer user_data)
4505 {
4513 info,
4514 flags,
4515 io_priority,
4516 cancellable,
4517 callback,
4518 user_data);
4519 }
4521 /**
4522 * g_file_set_attributes_finish:
4523 * @file: input #GFile
4524 * @result: a #GAsyncResult
4525 * @info: (out) (transfer full): a #GFileInfo
4526 * @error: a #GError, or %NULL
4527 *
4528 * Finishes setting an attribute started in g_file_set_attributes_async().
4529 *
4530 * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
4531 */
4532 gboolean
4537 {
4543 /* No standard handling of errors here, as we must set info even
4544 * on errors
4545 */
4548 }
4550 /**
4551 * g_file_set_attribute_string:
4552 * @file: input #GFile
4553 * @attribute: a string containing the attribute's name
4554 * @value: a string containing the attribute's value
4555 * @flags: #GFileQueryInfoFlags
4556 * @cancellable: (allow-none): optional #GCancellable object,
4557 * %NULL to ignore
4558 * @error: a #GError, or %NULL
4559 *
4560 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
4561 * If @attribute is of a different type, this operation will fail.
4562 *
4563 * If @cancellable is not %NULL, then the operation can be cancelled by
4564 * triggering the cancellable object from another thread. If the operation
4565 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4566 *
4567 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
4568 */
4569 gboolean
4573 GFileQueryInfoFlags flags,
4576 {
4580 }
4582 /**
4583 * g_file_set_attribute_byte_string:
4584 * @file: input #GFile
4585 * @attribute: a string containing the attribute's name
4586 * @value: a string containing the attribute's new value
4587 * @flags: a #GFileQueryInfoFlags
4588 * @cancellable: (allow-none): optional #GCancellable object,
4589 * %NULL to ignore
4590 * @error: a #GError, or %NULL
4591 *
4592 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
4593 * If @attribute is of a different type, this operation will fail,
4594 * returning %FALSE.
4595 *
4596 * If @cancellable is not %NULL, then the operation can be cancelled by
4597 * triggering the cancellable object from another thread. If the operation
4598 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4599 *
4600 * Returns: %TRUE if the @attribute was successfully set to @value
4601 * in the @file, %FALSE otherwise.
4602 */
4603 gboolean
4607 GFileQueryInfoFlags flags,
4610 {
4614 }
4616 /**
4617 * g_file_set_attribute_uint32:
4618 * @file: input #GFile
4619 * @attribute: a string containing the attribute's name
4620 * @value: a #guint32 containing the attribute's new value
4621 * @flags: a #GFileQueryInfoFlags
4622 * @cancellable: (allow-none): optional #GCancellable object,
4623 * %NULL to ignore
4624 * @error: a #GError, or %NULL
4625 *
4626 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
4627 * If @attribute is of a different type, this operation will fail.
4628 *
4629 * If @cancellable is not %NULL, then the operation can be cancelled by
4630 * triggering the cancellable object from another thread. If the operation
4631 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4632 *
4633 * Returns: %TRUE if the @attribute was successfully set to @value
4634 * in the @file, %FALSE otherwise.
4635 */
4636 gboolean
4639 guint32 value,
4640 GFileQueryInfoFlags flags,
4643 {
4647 }
4649 /**
4650 * g_file_set_attribute_int32:
4651 * @file: input #GFile
4652 * @attribute: a string containing the attribute's name
4653 * @value: a #gint32 containing the attribute's new value
4654 * @flags: a #GFileQueryInfoFlags
4655 * @cancellable: (allow-none): optional #GCancellable object,
4656 * %NULL to ignore
4657 * @error: a #GError, or %NULL
4658 *
4659 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
4660 * If @attribute is of a different type, this operation will fail.
4661 *
4662 * If @cancellable is not %NULL, then the operation can be cancelled by
4663 * triggering the cancellable object from another thread. If the operation
4664 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4665 *
4666 * Returns: %TRUE if the @attribute was successfully set to @value
4667 * in the @file, %FALSE otherwise.
4668 */
4669 gboolean
4672 gint32 value,
4673 GFileQueryInfoFlags flags,
4676 {
4680 }
4682 /**
4683 * g_file_set_attribute_uint64:
4684 * @file: input #GFile
4685 * @attribute: a string containing the attribute's name
4686 * @value: a #guint64 containing the attribute's new value
4687 * @flags: a #GFileQueryInfoFlags
4688 * @cancellable: (allow-none): optional #GCancellable object,
4689 * %NULL to ignore
4690 * @error: a #GError, or %NULL
4691 *
4692 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
4693 * If @attribute is of a different type, this operation will fail.
4694 *
4695 * If @cancellable is not %NULL, then the operation can be cancelled by
4696 * triggering the cancellable object from another thread. If the operation
4697 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4698 *
4699 * Returns: %TRUE if the @attribute was successfully set to @value
4700 * in the @file, %FALSE otherwise.
4701 */
4702 gboolean
4705 guint64 value,
4706 GFileQueryInfoFlags flags,
4709 {
4713 }
4715 /**
4716 * g_file_set_attribute_int64:
4717 * @file: input #GFile
4718 * @attribute: a string containing the attribute's name
4719 * @value: a #guint64 containing the attribute's new value
4720 * @flags: a #GFileQueryInfoFlags
4721 * @cancellable: (allow-none): optional #GCancellable object,
4722 * %NULL to ignore
4723 * @error: a #GError, or %NULL
4724 *
4725 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
4726 * If @attribute is of a different type, this operation will fail.
4727 *
4728 * If @cancellable is not %NULL, then the operation can be cancelled by
4729 * triggering the cancellable object from another thread. If the operation
4730 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4731 *
4732 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
4733 */
4734 gboolean
4737 gint64 value,
4738 GFileQueryInfoFlags flags,
4741 {
4745 }
4747 /**
4748 * g_file_mount_mountable:
4749 * @file: input #GFile
4750 * @flags: flags affecting the operation
4751 * @mount_operation: (allow-none): a #GMountOperation,
4752 * or %NULL to avoid user interaction
4753 * @cancellable: (allow-none): optional #GCancellable object,
4754 * %NULL to ignore
4755 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4756 * when the request is satisfied, or %NULL
4757 * @user_data: (closure): the data to pass to callback function
4758 *
4759 * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
4760 * Using @mount_operation, you can request callbacks when, for instance,
4761 * passwords are needed during authentication.
4762 *
4763 * If @cancellable is not %NULL, then the operation can be cancelled by
4764 * triggering the cancellable object from another thread. If the operation
4765 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4766 *
4767 * When the operation is finished, @callback will be called.
4768 * You can then call g_file_mount_mountable_finish() to get
4769 * the result of the operation.
4770 */
4771 void
4773 GMountMountFlags flags,
4776 GAsyncReadyCallback callback,
4777 gpointer user_data)
4778 {
4786 {
4788 g_file_mount_mountable,
4792 }
4795 flags,
4796 mount_operation,
4797 cancellable,
4798 callback,
4799 user_data);
4800 }
4802 /**
4803 * g_file_mount_mountable_finish:
4804 * @file: input #GFile
4805 * @result: a #GAsyncResult
4806 * @error: a #GError, or %NULL
4807 *
4808 * Finishes a mount operation. See g_file_mount_mountable() for details.
4809 *
4810 * Finish an asynchronous mount operation that was started
4811 * with g_file_mount_mountable().
4812 *
4813 * Returns: (transfer full): a #GFile or %NULL on error.
4814 * Free the returned object with g_object_unref().
4815 */
4816 GFile *
4820 {
4833 }
4835 /**
4836 * g_file_unmount_mountable:
4837 * @file: input #GFile
4838 * @flags: flags affecting the operation
4839 * @cancellable: (allow-none): optional #GCancellable object,
4840 * %NULL to ignore
4841 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4842 * when the request is satisfied, or %NULL
4843 * @user_data: (closure): the data to pass to callback function
4844 *
4845 * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
4846 *
4847 * If @cancellable is not %NULL, then the operation can be cancelled by
4848 * triggering the cancellable object from another thread. If the operation
4849 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4850 *
4851 * When the operation is finished, @callback will be called.
4852 * You can then call g_file_unmount_mountable_finish() to get
4853 * the result of the operation.
4854 *
4855 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
4856 */
4857 void
4859 GMountUnmountFlags flags,
4861 GAsyncReadyCallback callback,
4862 gpointer user_data)
4863 {
4871 {
4873 g_file_unmount_mountable_with_operation,
4877 }
4880 flags,
4881 cancellable,
4882 callback,
4883 user_data);
4884 }
4886 /**
4887 * g_file_unmount_mountable_finish:
4888 * @file: input #GFile
4889 * @result: a #GAsyncResult
4890 * @error: a #GError, or %NULL
4891 *
4892 * Finishes an unmount operation, see g_file_unmount_mountable() for details.
4893 *
4894 * Finish an asynchronous unmount operation that was started
4895 * with g_file_unmount_mountable().
4896 *
4897 * Returns: %TRUE if the operation finished successfully.
4898 * %FALSE otherwise.
4899 *
4900 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish()
4901 * instead.
4902 */
4903 gboolean
4907 {
4920 }
4922 /**
4923 * g_file_unmount_mountable_with_operation:
4924 * @file: input #GFile
4925 * @flags: flags affecting the operation
4926 * @mount_operation: (allow-none): a #GMountOperation,
4927 * or %NULL to avoid user interaction
4928 * @cancellable: (allow-none): optional #GCancellable object,
4929 * %NULL to ignore
4930 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4931 * when the request is satisfied, or %NULL
4932 * @user_data: (closure): the data to pass to callback function
4933 *
4934 * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
4935 *
4936 * If @cancellable is not %NULL, then the operation can be cancelled by
4937 * triggering the cancellable object from another thread. If the operation
4938 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4939 *
4940 * When the operation is finished, @callback will be called.
4941 * You can then call g_file_unmount_mountable_finish() to get
4942 * the result of the operation.
4943 *
4944 * Since: 2.22
4945 */
4946 void
4948 GMountUnmountFlags flags,
4951 GAsyncReadyCallback callback,
4952 gpointer user_data)
4953 {
4961 {
4963 g_file_unmount_mountable_with_operation,
4967 }
4971 flags,
4972 mount_operation,
4973 cancellable,
4974 callback,
4975 user_data);
4976 else
4978 flags,
4979 cancellable,
4980 callback,
4981 user_data);
4982 }
4984 /**
4985 * g_file_unmount_mountable_with_operation_finish:
4986 * @file: input #GFile
4987 * @result: a #GAsyncResult
4988 * @error: a #GError, or %NULL
4989 *
4990 * Finishes an unmount operation,
4991 * see g_file_unmount_mountable_with_operation() for details.
4992 *
4993 * Finish an asynchronous unmount operation that was started
4994 * with g_file_unmount_mountable_with_operation().
4995 *
4996 * Returns: %TRUE if the operation finished successfully.
4997 * %FALSE otherwise.
4998 *
4999 * Since: 2.22
5000 */
5001 gboolean
5005 {
5019 else
5021 }
5023 /**
5024 * g_file_eject_mountable:
5025 * @file: input #GFile
5026 * @flags: flags affecting the operation
5027 * @cancellable: (allow-none): optional #GCancellable object,
5028 * %NULL to ignore
5029 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
5030 * when the request is satisfied, or %NULL
5031 * @user_data: (closure): the data to pass to callback function
5032 *
5033 * Starts an asynchronous eject on a mountable.
5034 * When this operation has completed, @callback will be called with
5035 * @user_user data, and the operation can be finalized with
5036 * g_file_eject_mountable_finish().
5037 *
5038 * If @cancellable is not %NULL, then the operation can be cancelled by
5039 * triggering the cancellable object from another thread. If the operation
5040 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5041 *
5042 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
5043 */
5044 void
5046 GMountUnmountFlags flags,
5048 GAsyncReadyCallback callback,
5049 gpointer user_data)
5050 {
5058 {
5060 g_file_eject_mountable_with_operation,
5064 }
5067 flags,
5068 cancellable,
5069 callback,
5070 user_data);
5071 }
5073 /**
5074 * g_file_eject_mountable_finish:
5075 * @file: input #GFile
5076 * @result: a #GAsyncResult
5077 * @error: a #GError, or %NULL
5078 *
5079 * Finishes an asynchronous eject operation started by
5080 * g_file_eject_mountable().
5081 *
5082 * Returns: %TRUE if the @file was ejected successfully.
5083 * %FALSE otherwise.
5084 *
5085 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
5086 * instead.
5087 */
5088 gboolean
5092 {
5105 }
5107 /**
5108 * g_file_eject_mountable_with_operation:
5109 * @file: input #GFile
5110 * @flags: flags affecting the operation
5111 * @mount_operation: (allow-none): a #GMountOperation,
5112 * or %NULL to avoid user interaction
5113 * @cancellable: (allow-none): optional #GCancellable object,
5114 * %NULL to ignore
5115 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
5116 * when the request is satisfied, or %NULL
5117 * @user_data: (closure): the data to pass to callback function
5118 *
5119 * Starts an asynchronous eject on a mountable.
5120 * When this operation has completed, @callback will be called with
5121 * @user_user data, and the operation can be finalized with
5122 * g_file_eject_mountable_with_operation_finish().
5123 *
5124 * If @cancellable is not %NULL, then the operation can be cancelled by
5125 * triggering the cancellable object from another thread. If the operation
5126 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5127 *
5128 * Since: 2.22
5129 */
5130 void
5132 GMountUnmountFlags flags,
5135 GAsyncReadyCallback callback,
5136 gpointer user_data)
5137 {
5145 {
5147 g_file_eject_mountable_with_operation,
5151 }
5155 flags,
5156 mount_operation,
5157 cancellable,
5158 callback,
5159 user_data);
5160 else
5162 flags,
5163 cancellable,
5164 callback,
5165 user_data);
5166 }
5168 /**
5169 * g_file_eject_mountable_with_operation_finish:
5170 * @file: input #GFile
5171 * @result: a #GAsyncResult
5172 * @error: a #GError, or %NULL
5173 *
5174 * Finishes an asynchronous eject operation started by
5175 * g_file_eject_mountable_with_operation().
5176 *
5177 * Returns: %TRUE if the @file was ejected successfully.
5178 * %FALSE otherwise.
5179 *
5180 * Since: 2.22
5181 */
5182 gboolean
5186 {
5200 else
5202 }
5204 /**
5205 * g_file_monitor_directory:
5206 * @file: input #GFile
5207 * @flags: a set of #GFileMonitorFlags
5208 * @cancellable: (allow-none): optional #GCancellable object,
5209 * %NULL to ignore
5210 * @error: a #GError, or %NULL
5211 *
5212 * Obtains a directory monitor for the given file.
5213 * This may fail if directory monitoring is not supported.
5214 *
5215 * If @cancellable is not %NULL, then the operation can be cancelled by
5216 * triggering the cancellable object from another thread. If the operation
5217 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5218 *
5219 * It does not make sense for @flags to contain
5220 * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
5221 * directories. It is not possible to monitor all the files in a
5222 * directory for changes made via hard links; if you want to do this then
5223 * you must register individual watches with g_file_monitor().
5224 *
5225 * Virtual: monitor_dir
5226 * Returns: (transfer full): a #GFileMonitor for the given @file,
5227 * or %NULL on error.
5228 * Free the returned object with g_object_unref().
5229 */
5230 GFileMonitor *
5232 GFileMonitorFlags flags,
5235 {
5247 {
5249 G_IO_ERROR_NOT_SUPPORTED,
5252 }
5255 }
5257 /**
5258 * g_file_monitor_file:
5259 * @file: input #GFile
5260 * @flags: a set of #GFileMonitorFlags
5261 * @cancellable: (allow-none): optional #GCancellable object,
5262 * %NULL to ignore
5263 * @error: a #GError, or %NULL
5264 *
5265 * Obtains a file monitor for the given file. If no file notification
5266 * mechanism exists, then regular polling of the file is used.
5267 *
5268 * If @cancellable is not %NULL, then the operation can be cancelled by
5269 * triggering the cancellable object from another thread. If the operation
5270 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5271 *
5272 * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
5273 * will also attempt to report changes made to the file via another
5274 * filename (ie, a hard link). Without this flag, you can only rely on
5275 * changes made through the filename contained in @file to be
5276 * reported. Using this flag may result in an increase in resource
5277 * usage, and may not have any effect depending on the #GFileMonitor
5278 * backend and/or filesystem type.
5279 *
5280 * Returns: (transfer full): a #GFileMonitor for the given @file,
5281 * or %NULL on error.
5282 * Free the returned object with g_object_unref().
5283 */
5284 GFileMonitor *
5286 GFileMonitorFlags flags,
5289 {
5305 /* Fallback to polling */
5310 }
5312 /**
5313 * g_file_monitor:
5314 * @file: input #GFile
5315 * @flags: a set of #GFileMonitorFlags
5316 * @cancellable: (allow-none): optional #GCancellable object,
5317 * %NULL to ignore
5318 * @error: a #GError, or %NULL
5319 *
5320 * Obtains a file or directory monitor for the given file,
5321 * depending on the type of the file.
5322 *
5323 * If @cancellable is not %NULL, then the operation can be cancelled by
5324 * triggering the cancellable object from another thread. If the operation
5325 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5326 *
5327 * Returns: (transfer full): a #GFileMonitor for the given @file,
5328 * or %NULL on error.
5329 * Free the returned object with g_object_unref().
5330 *
5331 * Since: 2.18
5332 */
5333 GFileMonitor *
5335 GFileMonitorFlags flags,
5338 {
5343 else
5345 }
5347 /********************************************
5348 * Default implementation of async ops *
5349 ********************************************/
5353 GFileQueryInfoFlags flags;
5356 static void
5358 {
5361 }
5363 static void
5365 gpointer object,
5366 gpointer task_data,
5368 {
5373 info = g_file_query_info (G_FILE (object), data->attributes, data->flags, cancellable, &error);
5376 else
5378 }
5380 static void
5383 GFileQueryInfoFlags flags,
5386 GAsyncReadyCallback callback,
5387 gpointer user_data)
5388 {
5401 }
5407 {
5411 }
5413 static void
5415 gpointer object,
5416 gpointer task_data,
5418 {
5426 else
5428 }
5430 static void
5435 GAsyncReadyCallback callback,
5436 gpointer user_data)
5437 {
5445 }
5451 {
5455 }
5457 static void
5459 gpointer object,
5460 gpointer task_data,
5462 {
5467 enumerator = g_file_enumerate_children (G_FILE (object), data->attributes, data->flags, cancellable, &error);
5470 else
5472 }
5474 static void
5477 GFileQueryInfoFlags flags,
5480 GAsyncReadyCallback callback,
5481 gpointer user_data)
5482 {
5495 }
5501 {
5505 }
5507 static void
5509 gpointer object,
5510 gpointer task_data,
5512 {
5519 else
5521 }
5523 static void
5527 GAsyncReadyCallback callback,
5528 gpointer user_data)
5529 {
5536 }
5542 {
5546 }
5548 static void
5550 gpointer source_object,
5551 gpointer task_data,
5553 {
5561 else
5563 }
5565 static void
5567 GFileCreateFlags flags,
5570 GAsyncReadyCallback callback,
5571 gpointer user_data)
5572 {
5585 }
5591 {
5595 }
5597 static void
5599 gpointer source_object,
5600 gpointer task_data,
5602 {
5610 else
5612 }
5614 static void
5616 GFileCreateFlags flags,
5619 GAsyncReadyCallback callback,
5620 gpointer user_data)
5621 {
5634 }
5640 {
5644 }
5649 gboolean make_backup;
5650 GFileCreateFlags flags;
5653 static void
5655 {
5660 }
5662 static void
5664 gpointer source_object,
5665 gpointer task_data,
5667 {
5676 cancellable,
5681 else
5683 }
5685 static void
5688 gboolean make_backup,
5689 GFileCreateFlags flags,
5692 GAsyncReadyCallback callback,
5693 gpointer user_data)
5694 {
5709 }
5715 {
5719 }
5721 static void
5723 gpointer object,
5724 gpointer task_data,
5726 {
5731 else
5733 }
5735 static void
5739 GAsyncReadyCallback callback,
5740 gpointer user_data)
5741 {
5748 }
5750 static gboolean
5754 {
5758 }
5760 static void
5762 gpointer object,
5763 gpointer task_data,
5765 {
5770 else
5772 }
5774 static void
5778 GAsyncReadyCallback callback,
5779 gpointer user_data)
5780 {
5787 }
5789 static gboolean
5793 {
5797 }
5799 static void
5801 gpointer object,
5802 gpointer task_data,
5804 {
5809 else
5811 }
5813 static void
5817 GAsyncReadyCallback callback,
5818 gpointer user_data)
5819 {
5826 }
5828 static gboolean
5832 {
5836 }
5838 static void
5840 gpointer object,
5841 gpointer task_data,
5843 {
5851 else
5853 }
5855 static void
5859 GAsyncReadyCallback callback,
5860 gpointer user_data)
5861 {
5869 }
5875 {
5879 }
5881 static void
5883 gpointer object,
5884 gpointer task_data,
5886 {
5895 else
5897 }
5899 static void
5901 GFileCreateFlags flags,
5904 GAsyncReadyCallback callback,
5905 gpointer user_data)
5906 {
5919 }
5925 {
5929 }
5933 gboolean make_backup;
5934 GFileCreateFlags flags;
5937 static void
5939 {
5942 }
5944 static void
5946 gpointer object,
5947 gpointer task_data,
5949 {
5958 cancellable,
5963 else
5965 }
5967 static void
5970 gboolean make_backup,
5971 GFileCreateFlags flags,
5974 GAsyncReadyCallback callback,
5975 gpointer user_data)
5976 {
5991 }
5997 {
6001 }
6003 static void
6005 gpointer object,
6006 gpointer task_data,
6008 {
6017 else
6019 }
6021 static void
6026 GAsyncReadyCallback callback,
6027 gpointer user_data)
6028 {
6037 }
6043 {
6047 }
6050 GFileQueryInfoFlags flags;
6052 gboolean res;
6056 static void
6058 {
6064 }
6066 static void
6068 gpointer object,
6069 gpointer task_data,
6071 {
6078 cancellable,
6080 }
6082 static void
6085 GFileQueryInfoFlags flags,
6088 GAsyncReadyCallback callback,
6089 gpointer user_data)
6090 {
6104 }
6106 static gboolean
6111 {
6125 }
6127 static void
6129 gpointer object,
6130 gpointer task_data,
6132 {
6140 else
6142 }
6144 static void
6148 GAsyncReadyCallback callback,
6149 gpointer user_data)
6150 {
6158 }
6164 {
6168 }
6174 GFileCopyFlags flags;
6175 GFileProgressCallback progress_cb;
6176 gpointer progress_cb_data;
6179 static void
6181 {
6185 }
6189 goffset current_num_bytes;
6190 goffset total_num_bytes;
6193 static gboolean
6195 {
6204 }
6206 static void
6208 goffset total_num_bytes,
6209 gpointer user_data)
6210 {
6222 copy_async_progress_in_main,
6223 progress,
6224 g_free);
6225 }
6227 static void
6229 gpointer source,
6230 gpointer task_data,
6232 {
6234 gboolean result;
6240 cancellable,
6242 task,
6246 else
6248 }
6250 static void
6253 GFileCopyFlags flags,
6256 GFileProgressCallback progress_callback,
6257 gpointer progress_callback_data,
6258 GAsyncReadyCallback callback,
6259 gpointer user_data)
6260 {
6276 }
6278 static gboolean
6282 {
6286 }
6289 /********************************************
6290 * Default VFS operations *
6291 ********************************************/
6293 /**
6294 * g_file_new_for_path:
6295 * @path: a string containing a relative or absolute path.
6296 * The string must be encoded in the glib filename encoding.
6297 *
6298 * Constructs a #GFile for a given path. This operation never
6299 * fails, but the returned object might not support any I/O
6300 * operation if @path is malformed.
6301 *
6302 * Returns: (transfer full): a new #GFile for the given @path.
6303 * Free the returned object with g_object_unref().
6304 */
6305 GFile *
6307 {
6311 }
6313 /**
6314 * g_file_new_for_uri:
6315 * @uri: a UTF-8 string containing a URI
6316 *
6317 * Constructs a #GFile for a given URI. This operation never
6318 * fails, but the returned object might not support any I/O
6319 * operation if @uri is malformed or if the uri type is
6320 * not supported.
6321 *
6322 * Returns: (transfer full): a new #GFile for the given @uri.
6323 * Free the returned object with g_object_unref().
6324 */
6325 GFile *
6327 {
6331 }
6333 /**
6334 * g_file_new_tmp:
6335 * @tmpl: (type filename) (allow-none): Template for the file
6336 * name, as in g_file_open_tmp(), or %NULL for a default template
6337 * @iostream: (out): on return, a #GFileIOStream for the created file
6338 * @error: a #GError, or %NULL
6339 *
6340 * Opens a file in the preferred directory for temporary files (as
6341 * returned by g_get_tmp_dir()) and returns a #GFile and
6342 * #GFileIOStream pointing to it.
6343 *
6344 * @tmpl should be a string in the GLib file name encoding
6345 * containing a sequence of six 'X' characters, and containing no
6346 * directory components. If it is %NULL, a default template is used.
6347 *
6348 * Unlike the other #GFile constructors, this will return %NULL if
6349 * a temporary file could not be created.
6350 *
6351 * Returns: (transfer full): a new #GFile.
6352 * Free the returned object with g_object_unref().
6353 *
6354 * Since: 2.32
6355 */
6356 GFile *
6360 {
6361 gint fd;
6381 }
6383 /**
6384 * g_file_parse_name:
6385 * @parse_name: a file name or path to be parsed
6386 *
6387 * Constructs a #GFile with the given @parse_name (i.e. something
6388 * given by g_file_get_parse_name()). This operation never fails,
6389 * but the returned object might not support any I/O operation if
6390 * the @parse_name cannot be parsed.
6391 *
6392 * Returns: (transfer full): a new #GFile.
6393 */
6394 GFile *
6396 {
6400 }
6402 static gboolean
6404 {
6406 }
6408 /* Following RFC 2396, valid schemes are built like:
6409 * scheme = alpha *( alpha | digit | "+" | "-" | "." )
6410 */
6411 static gboolean
6413 {
6422 p++;
6426 }
6431 {
6442 {
6448 }
6449 else
6456 }
6458 /**
6459 * g_file_new_for_commandline_arg:
6460 * @arg: a command line string
6461 *
6462 * Creates a #GFile with the given argument from the command line.
6463 * The value of @arg can be either a URI, an absolute path or a
6464 * relative path resolved relative to the current working directory.
6465 * This operation never fails, but the returned object might not
6466 * support any I/O operation if @arg points to a malformed path.
6467 *
6468 * Returns: (transfer full): a new #GFile.
6469 * Free the returned object with g_object_unref().
6470 */
6471 GFile *
6473 {
6477 }
6479 /**
6480 * g_file_new_for_commandline_arg_and_cwd:
6481 * @arg: a command line string
6482 * @cwd: the current working directory of the commandline
6483 *
6484 * Creates a #GFile with the given argument from the command line.
6485 *
6486 * This function is similar to g_file_new_for_commandline_arg() except
6487 * that it allows for passing the current working directory as an
6488 * argument instead of using the current working directory of the
6489 * process.
6490 *
6491 * This is useful if the commandline argument was given in a context
6492 * other than the invocation of the current process.
6493 *
6494 * See also g_application_command_line_create_file_for_arg().
6495 *
6496 * Returns: (transfer full): a new #GFile
6497 *
6498 * Since: 2.36
6499 **/
6500 GFile *
6503 {
6508 }
6510 /**
6511 * g_file_mount_enclosing_volume:
6512 * @location: input #GFile
6513 * @flags: flags affecting the operation
6514 * @mount_operation: (allow-none): a #GMountOperation
6515 * or %NULL to avoid user interaction
6516 * @cancellable: (allow-none): optional #GCancellable object,
6517 * %NULL to ignore
6518 * @callback: (allow-none): a #GAsyncReadyCallback to call
6519 * when the request is satisfied, or %NULL
6520 * @user_data: the data to pass to callback function
6521 *
6522 * Starts a @mount_operation, mounting the volume that contains
6523 * the file @location.
6524 *
6525 * When this operation has completed, @callback will be called with
6526 * @user_user data, and the operation can be finalized with
6527 * g_file_mount_enclosing_volume_finish().
6528 *
6529 * If @cancellable is not %NULL, then the operation can be cancelled by
6530 * triggering the cancellable object from another thread. If the operation
6531 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6532 */
6533 void
6535 GMountMountFlags flags,
6538 GAsyncReadyCallback callback,
6539 gpointer user_data)
6540 {
6548 {
6550 g_file_mount_enclosing_volume,
6554 }
6556 (* iface->mount_enclosing_volume) (location, flags, mount_operation, cancellable, callback, user_data);
6558 }
6560 /**
6561 * g_file_mount_enclosing_volume_finish:
6562 * @location: input #GFile
6563 * @result: a #GAsyncResult
6564 * @error: a #GError, or %NULL
6565 *
6566 * Finishes a mount operation started by g_file_mount_enclosing_volume().
6567 *
6568 * Returns: %TRUE if successful. If an error has occurred,
6569 * this function will return %FALSE and set @error
6570 * appropriately if present.
6571 */
6572 gboolean
6576 {
6590 }
6592 /********************************************
6593 * Utility functions *
6594 ********************************************/
6596 /**
6597 * g_file_query_default_handler:
6598 * @file: a #GFile to open
6599 * @cancellable: optional #GCancellable object, %NULL to ignore
6600 * @error: a #GError, or %NULL
6601 *
6602 * Returns the #GAppInfo that is registered as the default
6603 * application to handle the file specified by @file.
6604 *
6605 * If @cancellable is not %NULL, then the operation can be cancelled by
6606 * triggering the cancellable object from another thread. If the operation
6607 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6608 *
6609 * Returns: (transfer full): a #GAppInfo if the handle was found,
6610 * %NULL if there were errors.
6611 * When you are done with it, release it with g_object_unref()
6612 */
6613 GAppInfo *
6617 {
6626 {
6632 }
6635 G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE,
6637 cancellable,
6638 error);
6646 {
6647 /* Don't use is_native(), as we want to support fuse paths if available */
6652 }
6660 G_IO_ERROR_NOT_SUPPORTED,
6663 }
6665 #define GET_CONTENT_BLOCK_SIZE 8192
6667 /**
6668 * g_file_load_contents:
6669 * @file: input #GFile
6670 * @cancellable: optional #GCancellable object, %NULL to ignore
6671 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
6672 * @length: (out) (allow-none): a location to place the length of the contents of the file,
6673 * or %NULL if the length is not needed
6674 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
6675 * or %NULL if the entity tag is not needed
6676 * @error: a #GError, or %NULL
6677 *
6678 * Loads the content of the file into memory. The data is always
6679 * zero-terminated, but this is not included in the resultant @length.
6680 * The returned @content should be freed with g_free() when no longer
6681 * needed.
6682 *
6683 * If @cancellable is not %NULL, then the operation can be cancelled by
6684 * triggering the cancellable object from another thread. If the operation
6685 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6686 *
6687 * Returns: %TRUE if the @file's contents were successfully loaded.
6688 * %FALSE if there were errors.
6689 */
6690 gboolean
6697 {
6700 gsize pos;
6701 gssize res;
6717 GET_CONTENT_BLOCK_SIZE,
6719 {
6722 }
6725 {
6729 G_FILE_ATTRIBUTE_ETAG_VALUE,
6730 cancellable,
6731 NULL);
6733 {
6736 }
6737 }
6739 /* Ignore errors on close */
6744 {
6745 /* error is set already */
6748 }
6753 /* Zero terminate (we got an extra byte allocated for this */
6759 }
6763 GFileReadMoreCallback read_more_callback;
6765 gsize pos;
6770 static void
6772 {
6777 }
6779 static void
6782 gpointer user_data)
6783 {
6787 /* Ignore errors here, we're only reading anyway */
6793 }
6795 static void
6798 gpointer user_data)
6799 {
6807 {
6810 }
6815 }
6817 static void
6820 gpointer user_data)
6821 {
6825 gssize read_size;
6830 {
6834 /* Close the file ignoring any error */
6837 }
6839 {
6841 G_FILE_ATTRIBUTE_ETAG_VALUE,
6844 load_contents_fstat_callback,
6845 data);
6846 }
6848 {
6859 G_FILE_ATTRIBUTE_ETAG_VALUE,
6862 load_contents_fstat_callback,
6863 data);
6864 else
6867 GET_CONTENT_BLOCK_SIZE,
6870 load_contents_read_callback,
6871 data);
6872 }
6873 }
6875 static void
6878 gpointer user_data)
6879 {
6888 {
6893 GET_CONTENT_BLOCK_SIZE,
6896 load_contents_read_callback,
6897 data);
6898 }
6899 else
6900 {
6903 }
6904 }
6906 /**
6907 * g_file_load_partial_contents_async: (skip)
6908 * @file: input #GFile
6909 * @cancellable: optional #GCancellable object, %NULL to ignore
6910 * @read_more_callback: a #GFileReadMoreCallback to receive partial data
6911 * and to specify whether further data should be read
6912 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
6913 * @user_data: the data to pass to the callback functions
6914 *
6915 * Reads the partial contents of a file. A #GFileReadMoreCallback should
6916 * be used to stop reading from the file when appropriate, else this
6917 * function will behave exactly as g_file_load_contents_async(). This
6918 * operation can be finished by g_file_load_partial_contents_finish().
6919 *
6920 * Users of this function should be aware that @user_data is passed to
6921 * both the @read_more_callback and the @callback.
6922 *
6923 * If @cancellable is not %NULL, then the operation can be cancelled by
6924 * triggering the cancellable object from another thread. If the operation
6925 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6926 */
6927 void
6930 GFileReadMoreCallback read_more_callback,
6931 GAsyncReadyCallback callback,
6932 gpointer user_data)
6933 {
6948 load_contents_open_callback,
6949 data);
6950 }
6952 /**
6953 * g_file_load_partial_contents_finish:
6954 * @file: input #GFile
6955 * @res: a #GAsyncResult
6956 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
6957 * @length: (out) (allow-none): a location to place the length of the contents of the file,
6958 * or %NULL if the length is not needed
6959 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
6960 * or %NULL if the entity tag is not needed
6961 * @error: a #GError, or %NULL
6962 *
6963 * Finishes an asynchronous partial load operation that was started
6964 * with g_file_load_partial_contents_async(). The data is always
6965 * zero-terminated, but this is not included in the resultant @length.
6966 * The returned @content should be freed with g_free() when no longer
6967 * needed.
6968 *
6969 * Returns: %TRUE if the load was successful. If %FALSE and @error is
6970 * present, it will be set appropriately.
6971 */
6972 gboolean
6979 {
6990 {
6994 }
7002 {
7005 }
7007 /* Zero terminate */
7015 }
7017 /**
7018 * g_file_load_contents_async:
7019 * @file: input #GFile
7020 * @cancellable: optional #GCancellable object, %NULL to ignore
7021 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7022 * @user_data: the data to pass to callback function
7023 *
7024 * Starts an asynchronous load of the @file's contents.
7025 *
7026 * For more details, see g_file_load_contents() which is
7027 * the synchronous version of this call.
7028 *
7029 * When the load operation has completed, @callback will be called
7030 * with @user data. To finish the operation, call
7031 * g_file_load_contents_finish() with the #GAsyncResult returned by
7032 * the @callback.
7033 *
7034 * If @cancellable is not %NULL, then the operation can be cancelled by
7035 * triggering the cancellable object from another thread. If the operation
7036 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7037 */
7038 void
7041 GAsyncReadyCallback callback,
7042 gpointer user_data)
7043 {
7045 cancellable,
7046 NULL,
7048 }
7050 /**
7051 * g_file_load_contents_finish:
7052 * @file: input #GFile
7053 * @res: a #GAsyncResult
7054 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
7055 * @length: (out) (allow-none): a location to place the length of the contents of the file,
7056 * or %NULL if the length is not needed
7057 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
7058 * or %NULL if the entity tag is not needed
7059 * @error: a #GError, or %NULL
7060 *
7061 * Finishes an asynchronous load of the @file's contents.
7062 * The contents are placed in @contents, and @length is set to the
7063 * size of the @contents string. The @content should be freed with
7064 * g_free() when no longer needed. If @etag_out is present, it will be
7065 * set to the new entity tag for the @file.
7066 *
7067 * Returns: %TRUE if the load was successful. If %FALSE and @error is
7068 * present, it will be set appropriately.
7069 */
7070 gboolean
7077 {
7079 res,
7080 contents,
7081 length,
7082 etag_out,
7083 error);
7084 }
7086 /**
7087 * g_file_replace_contents:
7088 * @file: input #GFile
7089 * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
7090 * @length: the length of @contents in bytes
7091 * @etag: (allow-none): the old <link linkend="gfile-etag">entity tag</link>
7092 * for the document, or %NULL
7093 * @make_backup: %TRUE if a backup should be created
7094 * @flags: a set of #GFileCreateFlags
7095 * @new_etag: (allow-none) (out): a location to a new <link linkend="gfile-etag">entity tag</link>
7096 * for the document. This should be freed with g_free() when no longer
7097 * needed, or %NULL
7098 * @cancellable: optional #GCancellable object, %NULL to ignore
7099 * @error: a #GError, or %NULL
7100 *
7101 * Replaces the contents of @file with @contents of @length bytes.
7102 *
7103 * If @etag is specified (not %NULL), any existing file must have that etag,
7104 * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
7105 *
7106 * If @make_backup is %TRUE, this function will attempt to make a backup
7107 * of @file.
7108 *
7109 * If @cancellable is not %NULL, then the operation can be cancelled by
7110 * triggering the cancellable object from another thread. If the operation
7111 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7112 *
7113 * The returned @new_etag can be used to verify that the file hasn't
7114 * changed the next time it is saved over.
7115 *
7116 * Returns: %TRUE if successful. If an error has occurred, this function
7117 * will return %FALSE and set @error appropriately if present.
7118 */
7119 gboolean
7122 gsize length,
7124 gboolean make_backup,
7125 GFileCreateFlags flags,
7129 {
7132 gssize res;
7133 gboolean ret;
7148 cancellable,
7150 {
7153 }
7156 {
7157 /* Ignore errors on close */
7161 /* error is set already */
7163 }
7173 }
7178 gsize length;
7179 gsize pos;
7181 gboolean failed;
7184 static void
7186 {
7189 }
7191 static void
7194 gpointer user_data)
7195 {
7199 /* Ignore errors here, we're only reading anyway */
7204 {
7207 }
7209 }
7211 static void
7214 gpointer user_data)
7215 {
7219 gssize write_size;
7224 {
7225 /* Error or EOF, close the file */
7227 {
7230 }
7234 }
7236 {
7243 else
7249 replace_contents_write_callback,
7250 data);
7251 }
7252 }
7254 static void
7257 gpointer user_data)
7258 {
7267 {
7273 replace_contents_write_callback,
7274 data);
7275 }
7276 else
7277 {
7280 }
7281 }
7283 /**
7284 * g_file_replace_contents_async:
7285 * @file: input #GFile
7286 * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
7287 * @length: the length of @contents in bytes
7288 * @etag: (allow-none): a new <link linkend="gfile-etag">entity tag</link> for the @file, or %NULL
7289 * @make_backup: %TRUE if a backup should be created
7290 * @flags: a set of #GFileCreateFlags
7291 * @cancellable: optional #GCancellable object, %NULL to ignore
7292 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7293 * @user_data: the data to pass to callback function
7294 *
7295 * Starts an asynchronous replacement of @file with the given
7296 * @contents of @length bytes. @etag will replace the document's
7297 * current entity tag.
7298 *
7299 * When this operation has completed, @callback will be called with
7300 * @user_user data, and the operation can be finalized with
7301 * g_file_replace_contents_finish().
7302 *
7303 * If @cancellable is not %NULL, then the operation can be cancelled by
7304 * triggering the cancellable object from another thread. If the operation
7305 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7306 *
7307 * If @make_backup is %TRUE, this function will attempt to
7308 * make a backup of @file.
7309 */
7310 void
7313 gsize length,
7315 gboolean make_backup,
7316 GFileCreateFlags flags,
7318 GAsyncReadyCallback callback,
7319 gpointer user_data)
7320 {
7335 etag,
7336 make_backup,
7337 flags,
7340 replace_contents_open_callback,
7341 data);
7342 }
7344 /**
7345 * g_file_replace_contents_finish:
7346 * @file: input #GFile
7347 * @res: a #GAsyncResult
7348 * @new_etag: (out) (allow-none): a location of a new <link linkend="gfile-etag">entity tag</link>
7349 * for the document. This should be freed with g_free() when it is no
7350 * longer needed, or %NULL
7351 * @error: a #GError, or %NULL
7352 *
7353 * Finishes an asynchronous replace of the given @file. See
7354 * g_file_replace_contents_async(). Sets @new_etag to the new entity
7355 * tag for the document, if present.
7356 *
7357 * Returns: %TRUE on success, %FALSE on failure.
7358 */
7359 gboolean
7364 {
7379 {
7382 }
7385 }
7387 gboolean
7389 GFileMeasureFlags flags,
7391 GFileMeasureProgressCallback progress_callback,
7392 gpointer progress_data,
7397 {
7401 }
7404 {
7405 GFileMeasureFlags flags;
7406 GFileMeasureProgressCallback progress_callback;
7407 gpointer progress_data;
7411 {
7412 guint64 disk_usage;
7413 guint64 num_dirs;
7414 guint64 num_files;
7418 {
7419 GFileMeasureProgressCallback callback;
7420 gpointer user_data;
7421 gboolean reporting;
7422 guint64 current_size;
7423 guint64 num_dirs;
7424 guint64 num_files;
7427 static gboolean
7429 {
7437 }
7439 static void
7441 guint64 current_size,
7442 guint64 num_dirs,
7443 guint64 num_files,
7444 gpointer user_data)
7445 {
7446 MeasureProgress progress;
7461 measure_disk_usage_invoke_progress,
7463 g_free);
7464 }
7466 static void
7468 gpointer source_object,
7469 gpointer task_data,
7471 {
7474 MeasureResult result;
7481 else
7483 }
7485 static void
7487 GFileMeasureFlags flags,
7488 gint io_priority,
7490 GFileMeasureProgressCallback progress_callback,
7491 gpointer progress_data,
7492 GAsyncReadyCallback callback,
7493 gpointer user_data)
7494 {
7495 MeasureTaskData data;
7508 }
7510 static gboolean
7517 {
7539 }
7541 /**
7542 * g_file_measure_disk_usage:
7543 * @file: a #GFile
7544 * @flags: #GFileMeasureFlags
7545 * @cancellable: (allow-none): optional #GCancellable
7546 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
7547 * @progress_data: user_data for @progress_callback
7548 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
7549 * @num_dirs: (allow-none) (out): the number of directories encountered
7550 * @num_files: (allow-none) (out): the number of non-directories encountered
7551 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
7552 *
7553 * Recursively measures the disk usage of @file.
7554 *
7555 * This is essentially an analog of the '<literal>du</literal>' command,
7556 * but it also reports the number of directories and non-directory files
7557 * encountered (including things like symbolic links).
7558 *
7559 * By default, errors are only reported against the toplevel file
7560 * itself. Errors found while recursing are silently ignored, unless
7561 * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
7562 *
7563 * The returned size, @disk_usage, is in bytes and should be formatted
7564 * with g_format_size() in order to get something reasonable for showing
7565 * in a user interface.
7566 *
7567 * @progress_callback and @progress_data can be given to request
7568 * periodic progress updates while scanning. See the documentation for
7569 * #GFileMeasureProgressCallback for information about when and how the
7570 * callback will be invoked.
7571 *
7572 * Returns: %TRUE if successful, with the out parameters set.
7573 * %FALSE otherwise, with @error set.
7574 *
7575 * Since: 2.38
7576 **/
7577 gboolean
7579 GFileMeasureFlags flags,
7581 GFileMeasureProgressCallback progress_callback,
7582 gpointer progress_data,
7587 {
7595 error);
7596 }
7598 /**
7599 * g_file_measure_disk_usage_async:
7600 * @file: a #GFile
7601 * @flags: #GFileMeasureFlags
7602 * @io_priority: the <link linkend="io-priority">I/O priority</link>
7603 * of the request
7604 * @cancellable: (allow-none): optional #GCancellable
7605 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
7606 * @progress_data: user_data for @progress_callback
7607 * @callback: (allow-none): a #GAsyncReadyCallback to call when complete
7608 * @user_data: the data to pass to callback function
7609 *
7610 * Recursively measures the disk usage of @file.
7611 *
7612 * This is the asynchronous version of g_file_measure_disk_usage(). See
7613 * there for more information.
7614 *
7615 * Since: 2.38
7616 **/
7617 void
7619 GFileMeasureFlags flags,
7620 gint io_priority,
7622 GFileMeasureProgressCallback progress_callback,
7623 gpointer progress_data,
7624 GAsyncReadyCallback callback,
7625 gpointer user_data)
7626 {
7630 return G_FILE_GET_IFACE (file)->measure_disk_usage_async (file, flags, io_priority, cancellable,
7633 }
7635 /**
7636 * g_file_measure_disk_usage_finish:
7637 * @file: a #GFile
7638 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
7639 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
7640 * @num_dirs: (allow-none) (out): the number of directories encountered
7641 * @num_files: (allow-none) (out): the number of non-directories encountered
7642 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
7643 *
7644 * Collects the results from an earlier call to
7645 * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for
7646 * more information.
7647 *
7648 * Returns: %TRUE if successful, with the out parameters set.
7649 * %FALSE otherwise, with @error set.
7650 *
7651 * Since: 2.38
7652 **/
7653 gboolean
7660 {
7664 return G_FILE_GET_IFACE (file)->measure_disk_usage_finish (file, result, disk_usage, num_dirs, num_files, error);
7665 }
7667 /**
7668 * g_file_start_mountable:
7669 * @file: input #GFile
7670 * @flags: flags affecting the operation
7671 * @start_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
7672 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
7673 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
7674 * @user_data: the data to pass to callback function
7675 *
7676 * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
7677 * Using @start_operation, you can request callbacks when, for instance,
7678 * passwords are needed during authentication.
7679 *
7680 * If @cancellable is not %NULL, then the operation can be cancelled by
7681 * triggering the cancellable object from another thread. If the operation
7682 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7683 *
7684 * When the operation is finished, @callback will be called.
7685 * You can then call g_file_mount_mountable_finish() to get
7686 * the result of the operation.
7687 *
7688 * Since: 2.22
7689 */
7690 void
7692 GDriveStartFlags flags,
7695 GAsyncReadyCallback callback,
7696 gpointer user_data)
7697 {
7705 {
7707 g_file_start_mountable,
7711 }
7714 flags,
7715 start_operation,
7716 cancellable,
7717 callback,
7718 user_data);
7719 }
7721 /**
7722 * g_file_start_mountable_finish:
7723 * @file: input #GFile
7724 * @result: a #GAsyncResult
7725 * @error: a #GError, or %NULL
7726 *
7727 * Finishes a start operation. See g_file_start_mountable() for details.
7728 *
7729 * Finish an asynchronous start operation that was started
7730 * with g_file_start_mountable().
7731 *
7732 * Returns: %TRUE if the operation finished successfully. %FALSE
7733 * otherwise.
7734 *
7735 * Since: 2.22
7736 */
7737 gboolean
7741 {
7754 }
7756 /**
7757 * g_file_stop_mountable:
7758 * @file: input #GFile
7759 * @flags: flags affecting the operation
7760 * @mount_operation: (allow-none): a #GMountOperation,
7761 * or %NULL to avoid user interaction.
7762 * @cancellable: (allow-none): optional #GCancellable object,
7763 * %NULL to ignore
7764 * @callback: (allow-none): a #GAsyncReadyCallback to call
7765 * when the request is satisfied, or %NULL
7766 * @user_data: the data to pass to callback function
7767 *
7768 * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
7769 *
7770 * If @cancellable is not %NULL, then the operation can be cancelled by
7771 * triggering the cancellable object from another thread. If the operation
7772 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7773 *
7774 * When the operation is finished, @callback will be called.
7775 * You can then call g_file_stop_mountable_finish() to get
7776 * the result of the operation.
7777 *
7778 * Since: 2.22
7779 */
7780 void
7782 GMountUnmountFlags flags,
7785 GAsyncReadyCallback callback,
7786 gpointer user_data)
7787 {
7795 {
7797 g_file_stop_mountable,
7801 }
7804 flags,
7805 mount_operation,
7806 cancellable,
7807 callback,
7808 user_data);
7809 }
7811 /**
7812 * g_file_stop_mountable_finish:
7813 * @file: input #GFile
7814 * @result: a #GAsyncResult
7815 * @error: a #GError, or %NULL
7816 *
7817 * Finishes an stop operation, see g_file_stop_mountable() for details.
7818 *
7819 * Finish an asynchronous stop operation that was started
7820 * with g_file_stop_mountable().
7821 *
7822 * Returns: %TRUE if the operation finished successfully.
7823 * %FALSE otherwise.
7824 *
7825 * Since: 2.22
7826 */
7827 gboolean
7831 {
7844 }
7846 /**
7847 * g_file_poll_mountable:
7848 * @file: input #GFile
7849 * @cancellable: optional #GCancellable object, %NULL to ignore
7850 * @callback: (allow-none): a #GAsyncReadyCallback to call
7851 * when the request is satisfied, or %NULL
7852 * @user_data: the data to pass to callback function
7853 *
7854 * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
7855 *
7856 * If @cancellable is not %NULL, then the operation can be cancelled by
7857 * triggering the cancellable object from another thread. If the operation
7858 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7859 *
7860 * When the operation is finished, @callback will be called.
7861 * You can then call g_file_mount_mountable_finish() to get
7862 * the result of the operation.
7863 *
7864 * Since: 2.22
7865 */
7866 void
7869 GAsyncReadyCallback callback,
7870 gpointer user_data)
7871 {
7879 {
7881 g_file_poll_mountable,
7885 }
7888 cancellable,
7889 callback,
7890 user_data);
7891 }
7893 /**
7894 * g_file_poll_mountable_finish:
7895 * @file: input #GFile
7896 * @result: a #GAsyncResult
7897 * @error: a #GError, or %NULL
7898 *
7899 * Finishes a poll operation. See g_file_poll_mountable() for details.
7900 *
7901 * Finish an asynchronous poll operation that was polled
7902 * with g_file_poll_mountable().
7903 *
7904 * Returns: %TRUE if the operation finished successfully. %FALSE
7905 * otherwise.
7906 *
7907 * Since: 2.22
7908 */
7909 gboolean
7913 {
7926 }
7928 /**
7929 * g_file_supports_thread_contexts:
7930 * @file: a #GFile
7931 *
7932 * Checks if @file supports <link
7933 * linkend="g-main-context-push-thread-default-context">thread-default
7934 * contexts</link>. If this returns %FALSE, you cannot perform
7935 * asynchronous operations on @file in a thread that has a
7936 * thread-default context.
7937 *
7938 * Returns: Whether or not @file supports thread-default contexts.
7939 *
7940 * Since: 2.22
7941 */
7942 gboolean
7944 {
7951 }