| blob | 3e9123f3745945439265742231ad8dc2576ab0cb |
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, see <http://www.gnu.org/licenses/>.
19 *
20 * Author: Alexander Larsson <alexl@redhat.com>
21 */
25 #ifdef __linux__
26 #include <sys/ioctl.h>
27 #include <errno.h>
28 /* See linux.git/fs/btrfs/ioctl.h */
29 #define BTRFS_IOCTL_MAGIC 0x94
30 #define BTRFS_IOC_CLONE _IOW(BTRFS_IOCTL_MAGIC, 9, int)
31 #endif
33 #ifdef HAVE_SPLICE
34 #include <sys/stat.h>
35 #include <unistd.h>
36 #include <fcntl.h>
37 #include <errno.h>
38 #endif
40 #include <string.h>
41 #include <sys/types.h>
45 #ifdef G_OS_UNIX
47 #endif
65 /**
66 * SECTION:gfile
67 * @short_description: File and Directory Handling
68 * @include: gio/gio.h
69 * @see_also: #GFileInfo, #GFileEnumerator
70 *
71 * #GFile is a high level abstraction for manipulating files on a
72 * virtual file system. #GFiles are lightweight, immutable objects
73 * that do no I/O upon creation. It is necessary to understand that
74 * #GFile objects do not represent files, merely an identifier for a
75 * file. All file content I/O is implemented as streaming operations
76 * (see #GInputStream and #GOutputStream).
77 *
78 * To construct a #GFile, you can use:
79 * - g_file_new_for_path() if you have a path.
80 * - g_file_new_for_uri() if you have a URI.
81 * - g_file_new_for_commandline_arg() for a command line argument.
82 * - g_file_new_tmp() to create a temporary file from a template.
83 * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
84 *
85 * One way to think of a #GFile is as an abstraction of a pathname. For
86 * normal files the system pathname is what is stored internally, but as
87 * #GFiles are extensible it could also be something else that corresponds
88 * to a pathname in a userspace implementation of a filesystem.
89 *
90 * #GFiles make up hierarchies of directories and files that correspond to
91 * the files on a filesystem. You can move through the file system with
92 * #GFile using g_file_get_parent() to get an identifier for the parent
93 * directory, g_file_get_child() to get a child within a directory,
94 * g_file_resolve_relative_path() to resolve a relative path between two
95 * #GFiles. There can be multiple hierarchies, so you may not end up at
96 * the same root if you repeatedly call g_file_get_parent() on two different
97 * files.
98 *
99 * All #GFiles have a basename (get with g_file_get_basename()). These names
100 * are byte strings that are used to identify the file on the filesystem
101 * (relative to its parent directory) and there is no guarantees that they
102 * have any particular charset encoding or even make any sense at all. If
103 * you want to use filenames in a user interface you should use the display
104 * name that you can get by requesting the
105 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
106 * This is guaranteed to be in UTF-8 and can be used in a user interface.
107 * But always store the real basename or the #GFile to use to actually
108 * access the file, because there is no way to go from a display name to
109 * the actual name.
110 *
111 * Using #GFile as an identifier has the same weaknesses as using a path
112 * in that there may be multiple aliases for the same file. For instance,
113 * hard or soft links may cause two different #GFiles to refer to the same
114 * file. Other possible causes for aliases are: case insensitive filesystems,
115 * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
116 * check if two #GFiles point to the same file you can query for the
117 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
118 * canonicalization of pathnames passed in, so that trivial differences in
119 * the path string used at creation (duplicated slashes, slash at end of
120 * path, "." or ".." path segments, etc) does not create different #GFiles.
121 *
122 * Many #GFile operations have both synchronous and asynchronous versions
123 * to suit your application. Asynchronous versions of synchronous functions
124 * simply have _async() appended to their function names. The asynchronous
125 * I/O functions call a #GAsyncReadyCallback which is then used to finalize
126 * the operation, producing a GAsyncResult which is then passed to the
127 * function's matching _finish() operation.
128 *
129 * Some #GFile operations do not have synchronous analogs, as they may
130 * take a very long time to finish, and blocking may leave an application
131 * unusable. Notable cases include:
132 * - g_file_mount_mountable() to mount a mountable file.
133 * - g_file_unmount_mountable_with_operation() to unmount a mountable file.
134 * - g_file_eject_mountable_with_operation() to eject a mountable file.
135 *
136 * ## Entity Tags # {#gfile-etag}
137 *
138 * One notable feature of #GFiles are entity tags, or "etags" for
139 * short. Entity tags are somewhat like a more abstract version of the
140 * traditional mtime, and can be used to quickly determine if the file
141 * has been modified from the version on the file system. See the
142 * HTTP 1.1
143 * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
144 * for HTTP Etag headers, which are a very similar concept.
145 */
149 GFileQueryInfoFlags flags,
152 GAsyncReadyCallback callback,
153 gpointer user_data);
161 GAsyncReadyCallback callback,
162 gpointer user_data);
168 GFileQueryInfoFlags flags,
171 GAsyncReadyCallback callback,
172 gpointer user_data);
179 GAsyncReadyCallback callback,
180 gpointer user_data);
185 GFileCreateFlags flags,
188 GAsyncReadyCallback callback,
189 gpointer user_data);
194 GFileCreateFlags flags,
197 GAsyncReadyCallback callback,
198 gpointer user_data);
204 gboolean make_backup,
205 GFileCreateFlags flags,
208 GAsyncReadyCallback callback,
209 gpointer user_data);
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);
246 GFileCreateFlags flags,
249 GAsyncReadyCallback callback,
250 gpointer user_data);
256 gboolean make_backup,
257 GFileCreateFlags flags,
260 GAsyncReadyCallback callback,
261 gpointer user_data);
267 GFileQueryInfoFlags flags,
274 GAsyncReadyCallback callback,
275 gpointer user_data);
281 GFileQueryInfoFlags flags,
284 GAsyncReadyCallback callback,
285 gpointer user_data);
293 GAsyncReadyCallback callback,
294 gpointer user_data);
300 GFileCopyFlags flags,
303 GFileProgressCallback progress_callback,
304 gpointer progress_callback_data,
305 GAsyncReadyCallback callback,
306 gpointer user_data);
312 GFileMeasureFlags flags,
314 GFileMeasureProgressCallback progress_callback,
315 gpointer progress_data,
321 GFileMeasureFlags flags,
322 gint io_priority,
324 GFileMeasureProgressCallback progress_callback,
325 gpointer progress_data,
326 GAsyncReadyCallback callback,
327 gpointer user_data);
338 static void
340 {
379 }
382 /**
383 * g_file_is_native:
384 * @file: input #GFile
385 *
386 * Checks to see if a file is native to the platform.
387 *
388 * A native file s one expressed in the platform-native filename format,
389 * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
390 * as it might be on a locally mounted remote filesystem.
391 *
392 * On some systems non-native files may be available using the native
393 * filesystem via a userspace filesystem (FUSE), in these cases this call
394 * will return %FALSE, but g_file_get_path() will still return a native path.
395 *
396 * This call does no blocking I/O.
397 *
398 * Returns: %TRUE if @file is native
399 */
400 gboolean
402 {
410 }
413 /**
414 * g_file_has_uri_scheme:
415 * @file: input #GFile
416 * @uri_scheme: a string containing a URI scheme
417 *
418 * Checks to see if a #GFile has a given URI scheme.
419 *
420 * This call does no blocking I/O.
421 *
422 * Returns: %TRUE if #GFile's backend supports the
423 * given URI scheme, %FALSE if URI scheme is %NULL,
424 * not supported, or #GFile is invalid.
425 */
426 gboolean
429 {
438 }
441 /**
442 * g_file_get_uri_scheme:
443 * @file: input #GFile
444 *
445 * Gets the URI scheme for a #GFile.
446 * RFC 3986 decodes the scheme as:
447 * |[
448 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
449 * ]|
450 * Common schemes include "file", "http", "ftp", etc.
451 *
452 * This call does no blocking I/O.
453 *
454 * Returns: a string containing the URI scheme for the given
455 * #GFile. The returned string should be freed with g_free()
456 * when no longer needed.
457 */
460 {
468 }
471 /**
472 * g_file_get_basename:
473 * @file: input #GFile
474 *
475 * Gets the base name (the last component of the path) for a given #GFile.
476 *
477 * If called for the top level of a system (such as the filesystem root
478 * or a uri like sftp://host/) it will return a single directory separator
479 * (and on Windows, possibly a drive letter).
480 *
481 * The base name is a byte string (not UTF-8). It has no defined encoding
482 * or rules other than it may not contain zero bytes. If you want to use
483 * filenames in a user interface you should use the display name that you
484 * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
485 * attribute with g_file_query_info().
486 *
487 * This call does no blocking I/O.
488 *
489 * Returns: (nullable): string containing the #GFile's base name, or
490 * %NULL if given #GFile is invalid. The returned string should be
491 * freed with g_free() when no longer needed.
492 */
495 {
503 }
505 /**
506 * g_file_get_path:
507 * @file: input #GFile
508 *
509 * Gets the local pathname for #GFile, if one exists.
510 *
511 * This call does no blocking I/O.
512 *
513 * Returns: (nullable): string containing the #GFile's path, or %NULL
514 * if no such path exists. The returned string should be freed
515 * with g_free() when no longer needed.
516 */
519 {
527 }
529 /**
530 * g_file_get_uri:
531 * @file: input #GFile
532 *
533 * Gets the URI for the @file.
534 *
535 * This call does no blocking I/O.
536 *
537 * Returns: a string containing the #GFile's URI.
538 * The returned string should be freed with g_free()
539 * when no longer needed.
540 */
543 {
551 }
553 /**
554 * g_file_get_parse_name:
555 * @file: input #GFile
556 *
557 * Gets the parse name of the @file.
558 * A parse name is a UTF-8 string that describes the
559 * file such that one can get the #GFile back using
560 * g_file_parse_name().
561 *
562 * This is generally used to show the #GFile as a nice
563 * full-pathname kind of string in a user interface,
564 * like in a location entry.
565 *
566 * For local files with names that can safely be converted
567 * to UTF-8 the pathname is used, otherwise the IRI is used
568 * (a form of URI that allows UTF-8 characters unescaped).
569 *
570 * This call does no blocking I/O.
571 *
572 * Returns: a string containing the #GFile's parse name.
573 * The returned string should be freed with g_free()
574 * when no longer needed.
575 */
578 {
586 }
588 /**
589 * g_file_dup:
590 * @file: input #GFile
591 *
592 * Duplicates a #GFile handle. This operation does not duplicate
593 * the actual file or directory represented by the #GFile; see
594 * g_file_copy() if attempting to copy a file.
595 *
596 * This call does no blocking I/O.
597 *
598 * Returns: (transfer full): a new #GFile that is a duplicate
599 * of the given #GFile.
600 */
601 GFile *
603 {
611 }
613 /**
614 * g_file_hash:
615 * @file: (type GFile): #gconstpointer to a #GFile
616 *
617 * Creates a hash value for a #GFile.
618 *
619 * This call does no blocking I/O.
620 *
621 * Virtual: hash
622 * Returns: 0 if @file is not a valid #GFile, otherwise an
623 * integer that can be used as hash value for the #GFile.
624 * This function is intended for easily hashing a #GFile to
625 * add to a #GHashTable or similar data structure.
626 */
627 guint
629 {
637 }
639 /**
640 * g_file_equal:
641 * @file1: the first #GFile
642 * @file2: the second #GFile
643 *
644 * Checks equality of two given #GFiles.
645 *
646 * Note that two #GFiles that differ can still refer to the same
647 * file on the filesystem due to various forms of filename
648 * aliasing.
649 *
650 * This call does no blocking I/O.
651 *
652 * Returns: %TRUE if @file1 and @file2 are equal.
653 * %FALSE if either is not a #GFile.
654 */
655 gboolean
658 {
670 }
673 /**
674 * g_file_get_parent:
675 * @file: input #GFile
676 *
677 * Gets the parent directory for the @file.
678 * If the @file represents the root directory of the
679 * file system, then %NULL will be returned.
680 *
681 * This call does no blocking I/O.
682 *
683 * Returns: (nullable) (transfer full): a #GFile structure to the
684 * parent of the given #GFile or %NULL if there is no parent. Free
685 * the returned object with g_object_unref().
686 */
687 GFile *
689 {
697 }
699 /**
700 * g_file_has_parent:
701 * @file: input #GFile
702 * @parent: (allow-none): the parent to check for, or %NULL
703 *
704 * Checks if @file has a parent, and optionally, if it is @parent.
705 *
706 * If @parent is %NULL then this function returns %TRUE if @file has any
707 * parent at all. If @parent is non-%NULL then %TRUE is only returned
708 * if @file is a child of @parent.
709 *
710 * Returns: %TRUE if @file is a child of @parent (or any parent in the
711 * case that @parent is %NULL).
712 *
713 * Since: 2.24
714 */
715 gboolean
718 {
720 gboolean result;
728 {
731 else
735 }
736 else
740 }
742 /**
743 * g_file_get_child:
744 * @file: input #GFile
745 * @name: string containing the child's basename
746 *
747 * Gets a child of @file with basename equal to @name.
748 *
749 * Note that the file with that specific name might not exist, but
750 * you can still have a #GFile that points to it. You can use this
751 * for instance to create that file.
752 *
753 * This call does no blocking I/O.
754 *
755 * Returns: (transfer full): a #GFile to a child specified by @name.
756 * Free the returned object with g_object_unref().
757 */
758 GFile *
761 {
766 }
768 /**
769 * g_file_get_child_for_display_name:
770 * @file: input #GFile
771 * @display_name: string to a possible child
772 * @error: return location for an error
773 *
774 * Gets the child of @file for a given @display_name (i.e. a UTF-8
775 * version of the name). If this function fails, it returns %NULL
776 * and @error will be set. This is very useful when constructing a
777 * #GFile for a new file and the user entered the filename in the
778 * user interface, for instance when you select a directory and
779 * type a filename in the file selector.
780 *
781 * This call does no blocking I/O.
782 *
783 * Returns: (transfer full): a #GFile to the specified child, or
784 * %NULL if the display name couldn't be converted.
785 * Free the returned object with g_object_unref().
786 */
787 GFile *
791 {
800 }
802 /**
803 * g_file_has_prefix:
804 * @file: input #GFile
805 * @prefix: input #GFile
806 *
807 * Checks whether @file has the prefix specified by @prefix.
808 *
809 * In other words, if the names of initial elements of @file's
810 * pathname match @prefix. Only full pathname elements are matched,
811 * so a path like /foo is not considered a prefix of /foobar, only
812 * of /foo/bar.
813 *
814 * This call does no I/O, as it works purely on names. As such it can
815 * sometimes return %FALSE even if @file is inside a @prefix (from a
816 * filesystem point of view), because the prefix of @file is an alias
817 * of @prefix.
818 *
819 * Virtual: prefix_matches
820 * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix,
821 * %FALSE otherwise.
822 */
823 gboolean
826 {
837 /* The vtable function differs in arg order since
838 * we're using the old contains_file call
839 */
841 }
843 /**
844 * g_file_get_relative_path:
845 * @parent: input #GFile
846 * @descendant: input #GFile
847 *
848 * Gets the path for @descendant relative to @parent.
849 *
850 * This call does no blocking I/O.
851 *
852 * Returns: (nullable): string with the relative path from @descendant
853 * to @parent, or %NULL if @descendant doesn't have @parent as
854 * prefix. The returned string should be freed with g_free() when
855 * no longer needed.
856 */
860 {
872 }
874 /**
875 * g_file_resolve_relative_path:
876 * @file: input #GFile
877 * @relative_path: a given relative path string
878 *
879 * Resolves a relative path for @file to an absolute path.
880 *
881 * This call does no blocking I/O.
882 *
883 * Returns: (transfer full): #GFile to the resolved path.
884 * %NULL if @relative_path is %NULL or if @file is invalid.
885 * Free the returned object with g_object_unref().
886 */
887 GFile *
890 {
899 }
901 /**
902 * g_file_enumerate_children:
903 * @file: input #GFile
904 * @attributes: an attribute query string
905 * @flags: a set of #GFileQueryInfoFlags
906 * @cancellable: (allow-none): optional #GCancellable object,
907 * %NULL to ignore
908 * @error: #GError for error reporting
909 *
910 * Gets the requested information about the files in a directory.
911 * The result is a #GFileEnumerator object that will give out
912 * #GFileInfo objects for all the files in the directory.
913 *
914 * The @attributes value is a string that specifies the file
915 * attributes that should be gathered. It is not an error if
916 * it's not possible to read a particular requested attribute
917 * from a file - it just won't be set. @attributes should
918 * be a comma-separated list of attributes or attribute wildcards.
919 * The wildcard "*" means all attributes, and a wildcard like
920 * "standard::*" means all attributes in the standard namespace.
921 * An example attribute query be "standard::*,owner::user".
922 * The standard attributes are available as defines, like
923 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
924 *
925 * If @cancellable is not %NULL, then the operation can be cancelled
926 * by triggering the cancellable object from another thread. If the
927 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
928 * returned.
929 *
930 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
931 * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
932 * error will be returned. Other errors are possible too.
933 *
934 * Returns: (transfer full): A #GFileEnumerator if successful,
935 * %NULL on error. Free the returned object with g_object_unref().
936 */
937 GFileEnumerator *
940 GFileQueryInfoFlags flags,
943 {
954 {
956 G_IO_ERROR_NOT_SUPPORTED,
959 }
963 }
965 /**
966 * g_file_enumerate_children_async:
967 * @file: input #GFile
968 * @attributes: an attribute query string
969 * @flags: a set of #GFileQueryInfoFlags
970 * @io_priority: the [I/O priority][io-priority] of the request
971 * @cancellable: (allow-none): optional #GCancellable object,
972 * %NULL to ignore
973 * @callback: (scope async): a #GAsyncReadyCallback to call when the
974 * request is satisfied
975 * @user_data: (closure): the data to pass to callback function
976 *
977 * Asynchronously gets the requested information about the files
978 * in a directory. The result is a #GFileEnumerator object that will
979 * give out #GFileInfo objects for all the files in the directory.
980 *
981 * For more details, see g_file_enumerate_children() which is
982 * the synchronous version of this call.
983 *
984 * When the operation is finished, @callback will be called. You can
985 * then call g_file_enumerate_children_finish() to get the result of
986 * the operation.
987 */
988 void
991 GFileQueryInfoFlags flags,
994 GAsyncReadyCallback callback,
995 gpointer user_data)
996 {
1003 attributes,
1004 flags,
1005 io_priority,
1006 cancellable,
1007 callback,
1008 user_data);
1009 }
1011 /**
1012 * g_file_enumerate_children_finish:
1013 * @file: input #GFile
1014 * @res: a #GAsyncResult
1015 * @error: a #GError
1016 *
1017 * Finishes an async enumerate children operation.
1018 * See g_file_enumerate_children_async().
1019 *
1020 * Returns: (transfer full): a #GFileEnumerator or %NULL
1021 * if an error occurred.
1022 * Free the returned object with g_object_unref().
1023 */
1024 GFileEnumerator *
1028 {
1039 }
1041 /**
1042 * g_file_query_exists:
1043 * @file: input #GFile
1044 * @cancellable: (allow-none): optional #GCancellable object,
1045 * %NULL to ignore
1046 *
1047 * Utility function to check if a particular file exists. This is
1048 * implemented using g_file_query_info() and as such does blocking I/O.
1049 *
1050 * Note that in many cases it is racy to first check for file existence
1051 * and then execute something based on the outcome of that, because the
1052 * file might have been created or removed in between the operations. The
1053 * general approach to handling that is to not check, but just do the
1054 * operation and handle the errors as they come.
1055 *
1056 * As an example of race-free checking, take the case of reading a file,
1057 * and if it doesn't exist, creating it. There are two racy versions: read
1058 * it, and on error create it; and: check if it exists, if not create it.
1059 * These can both result in two processes creating the file (with perhaps
1060 * a partially written file as the result). The correct approach is to
1061 * always try to create the file with g_file_create() which will either
1062 * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
1063 *
1064 * However, in many cases an existence check is useful in a user interface,
1065 * for instance to make a menu item sensitive/insensitive, so that you don't
1066 * have to fool users that something is possible and then just show an error
1067 * dialog. If you do this, you should make sure to also handle the errors
1068 * that can happen due to races when you execute the operation.
1069 *
1070 * Returns: %TRUE if the file exists (and can be detected without error),
1071 * %FALSE otherwise (or if cancelled).
1072 */
1073 gboolean
1076 {
1084 {
1087 }
1090 }
1092 /**
1093 * g_file_query_file_type:
1094 * @file: input #GFile
1095 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
1096 * @cancellable: (allow-none): optional #GCancellable object,
1097 * %NULL to ignore
1098 *
1099 * Utility function to inspect the #GFileType of a file. This is
1100 * implemented using g_file_query_info() and as such does blocking I/O.
1101 *
1102 * The primary use case of this method is to check if a file is
1103 * a regular file, directory, or symlink.
1104 *
1105 * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN
1106 * if the file does not exist
1107 *
1108 * Since: 2.18
1109 */
1110 GFileType
1112 GFileQueryInfoFlags flags,
1114 {
1116 GFileType file_type;
1122 {
1125 }
1126 else
1130 }
1132 /**
1133 * g_file_query_info:
1134 * @file: input #GFile
1135 * @attributes: an attribute query string
1136 * @flags: a set of #GFileQueryInfoFlags
1137 * @cancellable: (allow-none): optional #GCancellable object,
1138 * %NULL to ignore
1139 * @error: a #GError
1140 *
1141 * Gets the requested information about specified @file.
1142 * The result is a #GFileInfo object that contains key-value
1143 * attributes (such as the type or size of the file).
1144 *
1145 * The @attributes value is a string that specifies the file
1146 * attributes that should be gathered. It is not an error if
1147 * it's not possible to read a particular requested attribute
1148 * from a file - it just won't be set. @attributes should be a
1149 * comma-separated list of attributes or attribute wildcards.
1150 * The wildcard "*" means all attributes, and a wildcard like
1151 * "standard::*" means all attributes in the standard namespace.
1152 * An example attribute query be "standard::*,owner::user".
1153 * The standard attributes are available as defines, like
1154 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
1155 *
1156 * If @cancellable is not %NULL, then the operation can be cancelled
1157 * by triggering the cancellable object from another thread. If the
1158 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1159 * returned.
1160 *
1161 * For symlinks, normally the information about the target of the
1162 * symlink is returned, rather than information about the symlink
1163 * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
1164 * in @flags the information about the symlink itself will be returned.
1165 * Also, for symlinks that point to non-existing files the information
1166 * about the symlink itself will be returned.
1167 *
1168 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
1169 * returned. Other errors are possible too, and depend on what kind of
1170 * filesystem the file is on.
1171 *
1172 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
1173 * on error. Free the returned object with g_object_unref().
1174 */
1175 GFileInfo *
1178 GFileQueryInfoFlags flags,
1181 {
1192 {
1194 G_IO_ERROR_NOT_SUPPORTED,
1197 }
1200 }
1202 /**
1203 * g_file_query_info_async:
1204 * @file: input #GFile
1205 * @attributes: an attribute query string
1206 * @flags: a set of #GFileQueryInfoFlags
1207 * @io_priority: the [I/O priority][io-priority] of the request
1208 * @cancellable: (allow-none): optional #GCancellable object,
1209 * %NULL to ignore
1210 * @callback: (scope async): a #GAsyncReadyCallback to call when the
1211 * request is satisfied
1212 * @user_data: (closure): the data to pass to callback function
1213 *
1214 * Asynchronously gets the requested information about specified @file.
1215 * The result is a #GFileInfo object that contains key-value attributes
1216 * (such as type or size for the file).
1217 *
1218 * For more details, see g_file_query_info() which is the synchronous
1219 * version of this call.
1220 *
1221 * When the operation is finished, @callback will be called. You can
1222 * then call g_file_query_info_finish() to get the result of the operation.
1223 */
1224 void
1227 GFileQueryInfoFlags flags,
1230 GAsyncReadyCallback callback,
1231 gpointer user_data)
1232 {
1239 attributes,
1240 flags,
1241 io_priority,
1242 cancellable,
1243 callback,
1244 user_data);
1245 }
1247 /**
1248 * g_file_query_info_finish:
1249 * @file: input #GFile
1250 * @res: a #GAsyncResult
1251 * @error: a #GError
1252 *
1253 * Finishes an asynchronous file info query.
1254 * See g_file_query_info_async().
1255 *
1256 * Returns: (transfer full): #GFileInfo for given @file
1257 * or %NULL on error. Free the returned object with
1258 * g_object_unref().
1259 */
1260 GFileInfo *
1264 {
1275 }
1277 /**
1278 * g_file_query_filesystem_info:
1279 * @file: input #GFile
1280 * @attributes: an attribute query string
1281 * @cancellable: (allow-none): optional #GCancellable object,
1282 * %NULL to ignore
1283 * @error: a #GError
1284 *
1285 * Similar to g_file_query_info(), but obtains information
1286 * about the filesystem the @file is on, rather than the file itself.
1287 * For instance the amount of space available and the type of
1288 * the filesystem.
1289 *
1290 * The @attributes value is a string that specifies the attributes
1291 * that should be gathered. It is not an error if it's not possible
1292 * to read a particular requested attribute from a file - it just
1293 * won't be set. @attributes should be a comma-separated list of
1294 * attributes or attribute wildcards. The wildcard "*" means all
1295 * attributes, and a wildcard like "filesystem::*" means all attributes
1296 * in the filesystem namespace. The standard namespace for filesystem
1297 * attributes is "filesystem". Common attributes of interest are
1298 * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
1299 * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
1300 * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
1301 *
1302 * If @cancellable is not %NULL, then the operation can be cancelled
1303 * by triggering the cancellable object from another thread. If the
1304 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1305 * returned.
1306 *
1307 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
1308 * be returned. Other errors are possible too, and depend on what
1309 * kind of filesystem the file is on.
1310 *
1311 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
1312 * Free the returned object with g_object_unref().
1313 */
1314 GFileInfo *
1319 {
1330 {
1332 G_IO_ERROR_NOT_SUPPORTED,
1335 }
1338 }
1340 /**
1341 * g_file_query_filesystem_info_async:
1342 * @file: input #GFile
1343 * @attributes: an attribute query string
1344 * @io_priority: the [I/O priority][io-priority] of the request
1345 * @cancellable: (allow-none): optional #GCancellable object,
1346 * %NULL to ignore
1347 * @callback: (scope async): a #GAsyncReadyCallback to call
1348 * when the request is satisfied
1349 * @user_data: (closure): the data to pass to callback function
1350 *
1351 * Asynchronously gets the requested information about the filesystem
1352 * that the specified @file is on. The result is a #GFileInfo object
1353 * that contains key-value attributes (such as type or size for the
1354 * file).
1355 *
1356 * For more details, see g_file_query_filesystem_info() which is the
1357 * synchronous version of this call.
1358 *
1359 * When the operation is finished, @callback will be called. You can
1360 * then call g_file_query_info_finish() to get the result of the
1361 * operation.
1362 */
1363 void
1368 GAsyncReadyCallback callback,
1369 gpointer user_data)
1370 {
1377 attributes,
1378 io_priority,
1379 cancellable,
1380 callback,
1381 user_data);
1382 }
1384 /**
1385 * g_file_query_filesystem_info_finish:
1386 * @file: input #GFile
1387 * @res: a #GAsyncResult
1388 * @error: a #GError
1389 *
1390 * Finishes an asynchronous filesystem info query.
1391 * See g_file_query_filesystem_info_async().
1392 *
1393 * Returns: (transfer full): #GFileInfo for given @file
1394 * or %NULL on error.
1395 * Free the returned object with g_object_unref().
1396 */
1397 GFileInfo *
1401 {
1412 }
1414 /**
1415 * g_file_find_enclosing_mount:
1416 * @file: input #GFile
1417 * @cancellable: (allow-none): optional #GCancellable object,
1418 * %NULL to ignore
1419 * @error: a #GError
1420 *
1421 * Gets a #GMount for the #GFile.
1422 *
1423 * If the #GFileIface for @file does not have a mount (e.g.
1424 * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
1425 * and %NULL will be returned.
1426 *
1427 * If @cancellable is not %NULL, then the operation can be cancelled by
1428 * triggering the cancellable object from another thread. If the operation
1429 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
1430 *
1431 * Returns: (transfer full): a #GMount where the @file is located
1432 * or %NULL on error.
1433 * Free the returned object with g_object_unref().
1434 */
1435 GMount *
1439 {
1449 {
1452 /* Translators: This is an error message when
1453 * trying to find the enclosing (user visible)
1454 * mount of a file, but none exists.
1455 */
1458 }
1461 }
1463 /**
1464 * g_file_find_enclosing_mount_async:
1465 * @file: a #GFile
1466 * @io_priority: the [I/O priority][io-priority] of the request
1467 * @cancellable: (allow-none): optional #GCancellable object,
1468 * %NULL to ignore
1469 * @callback: (scope async): a #GAsyncReadyCallback to call
1470 * when the request is satisfied
1471 * @user_data: (closure): the data to pass to callback function
1472 *
1473 * Asynchronously gets the mount for the file.
1474 *
1475 * For more details, see g_file_find_enclosing_mount() which is
1476 * the synchronous version of this call.
1477 *
1478 * When the operation is finished, @callback will be called.
1479 * You can then call g_file_find_enclosing_mount_finish() to
1480 * get the result of the operation.
1481 */
1482 void
1486 GAsyncReadyCallback callback,
1487 gpointer user_data)
1488 {
1495 io_priority,
1496 cancellable,
1497 callback,
1498 user_data);
1499 }
1501 /**
1502 * g_file_find_enclosing_mount_finish:
1503 * @file: a #GFile
1504 * @res: a #GAsyncResult
1505 * @error: a #GError
1506 *
1507 * Finishes an asynchronous find mount request.
1508 * See g_file_find_enclosing_mount_async().
1509 *
1510 * Returns: (transfer full): #GMount for given @file or %NULL on error.
1511 * Free the returned object with g_object_unref().
1512 */
1513 GMount *
1517 {
1528 }
1531 /**
1532 * g_file_read:
1533 * @file: #GFile to read
1534 * @cancellable: (allow-none): a #GCancellable
1535 * @error: a #GError, or %NULL
1536 *
1537 * Opens a file for reading. The result is a #GFileInputStream that
1538 * can be used to read the contents of the file.
1539 *
1540 * If @cancellable is not %NULL, then the operation can be cancelled by
1541 * triggering the cancellable object from another thread. If the operation
1542 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
1543 *
1544 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
1545 * returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
1546 * error will be returned. Other errors are possible too, and depend
1547 * on what kind of filesystem the file is on.
1548 *
1549 * Virtual: read_fn
1550 * Returns: (transfer full): #GFileInputStream or %NULL on error.
1551 * Free the returned object with g_object_unref().
1552 */
1553 GFileInputStream *
1557 {
1568 {
1570 G_IO_ERROR_NOT_SUPPORTED,
1573 }
1576 }
1578 /**
1579 * g_file_append_to:
1580 * @file: input #GFile
1581 * @flags: a set of #GFileCreateFlags
1582 * @cancellable: (allow-none): optional #GCancellable object,
1583 * %NULL to ignore
1584 * @error: a #GError, or %NULL
1585 *
1586 * Gets an output stream for appending data to the file.
1587 * If the file doesn't already exist it is created.
1588 *
1589 * By default files created are generally readable by everyone,
1590 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1591 * will be made readable only to the current user, to the level that
1592 * is supported on the target filesystem.
1593 *
1594 * If @cancellable is not %NULL, then the operation can be cancelled
1595 * by triggering the cancellable object from another thread. If the
1596 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1597 * returned.
1598 *
1599 * Some file systems don't allow all file names, and may return an
1600 * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
1601 * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
1602 * possible too, and depend on what kind of filesystem the file is on.
1603 *
1604 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
1605 * Free the returned object with g_object_unref().
1606 */
1607 GFileOutputStream *
1609 GFileCreateFlags flags,
1612 {
1623 {
1625 G_IO_ERROR_NOT_SUPPORTED,
1628 }
1631 }
1633 /**
1634 * g_file_create:
1635 * @file: input #GFile
1636 * @flags: a set of #GFileCreateFlags
1637 * @cancellable: (allow-none): optional #GCancellable object,
1638 * %NULL to ignore
1639 * @error: a #GError, or %NULL
1640 *
1641 * Creates a new file and returns an output stream for writing to it.
1642 * The file must not already exist.
1643 *
1644 * By default files created are generally readable by everyone,
1645 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1646 * will be made readable only to the current user, to the level
1647 * that is supported on the target filesystem.
1648 *
1649 * If @cancellable is not %NULL, then the operation can be cancelled
1650 * by triggering the cancellable object from another thread. If the
1651 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1652 * returned.
1653 *
1654 * If a file or directory with this name already exists the
1655 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
1656 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
1657 * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
1658 * be returned. Other errors are possible too, and depend on what kind
1659 * of filesystem the file is on.
1660 *
1661 * Returns: (transfer full): a #GFileOutputStream for the newly created
1662 * file, or %NULL on error.
1663 * Free the returned object with g_object_unref().
1664 */
1665 GFileOutputStream *
1667 GFileCreateFlags flags,
1670 {
1681 {
1683 G_IO_ERROR_NOT_SUPPORTED,
1686 }
1689 }
1691 /**
1692 * g_file_replace:
1693 * @file: input #GFile
1694 * @etag: (allow-none): an optional [entity tag][gfile-etag]
1695 * for the current #GFile, or #NULL to ignore
1696 * @make_backup: %TRUE if a backup should be created
1697 * @flags: a set of #GFileCreateFlags
1698 * @cancellable: (allow-none): optional #GCancellable object,
1699 * %NULL to ignore
1700 * @error: a #GError, or %NULL
1701 *
1702 * Returns an output stream for overwriting the file, possibly
1703 * creating a backup copy of the file first. If the file doesn't exist,
1704 * it will be created.
1705 *
1706 * This will try to replace the file in the safest way possible so
1707 * that any errors during the writing will not affect an already
1708 * existing copy of the file. For instance, for local files it
1709 * may write to a temporary file and then atomically rename over
1710 * the destination when the stream is closed.
1711 *
1712 * By default files created are generally readable by everyone,
1713 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1714 * will be made readable only to the current user, to the level that
1715 * is supported on the target filesystem.
1716 *
1717 * If @cancellable is not %NULL, then the operation can be cancelled
1718 * by triggering the cancellable object from another thread. If the
1719 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1720 * returned.
1721 *
1722 * If you pass in a non-%NULL @etag value, then this value is
1723 * compared to the current entity tag of the file, and if they differ
1724 * an %G_IO_ERROR_WRONG_ETAG error is returned. This generally means
1725 * that the file has been changed since you last read it. You can get
1726 * the new etag from g_file_output_stream_get_etag() after you've
1727 * finished writing and closed the #GFileOutputStream. When you load
1728 * a new file you can use g_file_input_stream_query_info() to get
1729 * the etag of the file.
1730 *
1731 * If @make_backup is %TRUE, this function will attempt to make a
1732 * backup of the current file before overwriting it. If this fails
1733 * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
1734 * want to replace anyway, try again with @make_backup set to %FALSE.
1735 *
1736 * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
1737 * be returned, and if the file is some other form of non-regular file
1738 * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
1739 * file systems don't allow all file names, and may return an
1740 * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
1741 * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
1742 * possible too, and depend on what kind of filesystem the file is on.
1743 *
1744 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
1745 * Free the returned object with g_object_unref().
1746 */
1747 GFileOutputStream *
1750 gboolean make_backup,
1751 GFileCreateFlags flags,
1754 {
1765 {
1767 G_IO_ERROR_NOT_SUPPORTED,
1770 }
1772 /* Handle empty tag string as NULL in consistent way. */
1777 }
1779 /**
1780 * g_file_open_readwrite:
1781 * @file: #GFile to open
1782 * @cancellable: (allow-none): a #GCancellable
1783 * @error: a #GError, or %NULL
1784 *
1785 * Opens an existing file for reading and writing. The result is
1786 * a #GFileIOStream that can be used to read and write the contents
1787 * of the file.
1788 *
1789 * If @cancellable is not %NULL, then the operation can be cancelled
1790 * by triggering the cancellable object from another thread. If the
1791 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1792 * returned.
1793 *
1794 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
1795 * be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
1796 * error will be returned. Other errors are possible too, and depend on
1797 * what kind of filesystem the file is on. Note that in many non-local
1798 * file cases read and write streams are not supported, so make sure you
1799 * really need to do read and write streaming, rather than just opening
1800 * for reading or writing.
1801 *
1802 * Returns: (transfer full): #GFileIOStream or %NULL on error.
1803 * Free the returned object with g_object_unref().
1804 *
1805 * Since: 2.22
1806 */
1807 GFileIOStream *
1811 {
1822 {
1824 G_IO_ERROR_NOT_SUPPORTED,
1827 }
1830 }
1832 /**
1833 * g_file_create_readwrite:
1834 * @file: a #GFile
1835 * @flags: a set of #GFileCreateFlags
1836 * @cancellable: (allow-none): optional #GCancellable object,
1837 * %NULL to ignore
1838 * @error: return location for a #GError, or %NULL
1839 *
1840 * Creates a new file and returns a stream for reading and
1841 * writing to it. The file must not already exist.
1842 *
1843 * By default files created are generally readable by everyone,
1844 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1845 * will be made readable only to the current user, to the level
1846 * that is supported on the target filesystem.
1847 *
1848 * If @cancellable is not %NULL, then the operation can be cancelled
1849 * by triggering the cancellable object from another thread. If the
1850 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1851 * returned.
1852 *
1853 * If a file or directory with this name already exists, the
1854 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
1855 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
1856 * error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
1857 * will be returned. Other errors are possible too, and depend on what
1858 * kind of filesystem the file is on.
1859 *
1860 * Note that in many non-local file cases read and write streams are
1861 * not supported, so make sure you really need to do read and write
1862 * streaming, rather than just opening for reading or writing.
1863 *
1864 * Returns: (transfer full): a #GFileIOStream for the newly created
1865 * file, or %NULL on error.
1866 * Free the returned object with g_object_unref().
1867 *
1868 * Since: 2.22
1869 */
1870 GFileIOStream *
1872 GFileCreateFlags flags,
1875 {
1886 {
1888 G_IO_ERROR_NOT_SUPPORTED,
1891 }
1894 }
1896 /**
1897 * g_file_replace_readwrite:
1898 * @file: a #GFile
1899 * @etag: (allow-none): an optional [entity tag][gfile-etag]
1900 * for the current #GFile, or #NULL to ignore
1901 * @make_backup: %TRUE if a backup should be created
1902 * @flags: a set of #GFileCreateFlags
1903 * @cancellable: (allow-none): optional #GCancellable object,
1904 * %NULL to ignore
1905 * @error: return location for a #GError, or %NULL
1906 *
1907 * Returns an output stream for overwriting the file in readwrite mode,
1908 * possibly creating a backup copy of the file first. If the file doesn't
1909 * exist, it will be created.
1910 *
1911 * For details about the behaviour, see g_file_replace() which does the
1912 * same thing but returns an output stream only.
1913 *
1914 * Note that in many non-local file cases read and write streams are not
1915 * supported, so make sure you really need to do read and write streaming,
1916 * rather than just opening for reading or writing.
1917 *
1918 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
1919 * Free the returned object with g_object_unref().
1920 *
1921 * Since: 2.22
1922 */
1923 GFileIOStream *
1926 gboolean make_backup,
1927 GFileCreateFlags flags,
1930 {
1941 {
1943 G_IO_ERROR_NOT_SUPPORTED,
1946 }
1949 }
1951 /**
1952 * g_file_read_async:
1953 * @file: input #GFile
1954 * @io_priority: the [I/O priority][io-priority] of the request
1955 * @cancellable: (allow-none): optional #GCancellable object,
1956 * %NULL to ignore
1957 * @callback: (scope async): a #GAsyncReadyCallback to call
1958 * when the request is satisfied
1959 * @user_data: (closure): the data to pass to callback function
1960 *
1961 * Asynchronously opens @file for reading.
1962 *
1963 * For more details, see g_file_read() which is
1964 * the synchronous version of this call.
1965 *
1966 * When the operation is finished, @callback will be called.
1967 * You can then call g_file_read_finish() to get the result
1968 * of the operation.
1969 */
1970 void
1974 GAsyncReadyCallback callback,
1975 gpointer user_data)
1976 {
1983 io_priority,
1984 cancellable,
1985 callback,
1986 user_data);
1987 }
1989 /**
1990 * g_file_read_finish:
1991 * @file: input #GFile
1992 * @res: a #GAsyncResult
1993 * @error: a #GError, or %NULL
1994 *
1995 * Finishes an asynchronous file read operation started with
1996 * g_file_read_async().
1997 *
1998 * Returns: (transfer full): a #GFileInputStream or %NULL on error.
1999 * Free the returned object with g_object_unref().
2000 */
2001 GFileInputStream *
2005 {
2016 }
2018 /**
2019 * g_file_append_to_async:
2020 * @file: input #GFile
2021 * @flags: a set of #GFileCreateFlags
2022 * @io_priority: the [I/O priority][io-priority] of the request
2023 * @cancellable: (allow-none): optional #GCancellable object,
2024 * %NULL to ignore
2025 * @callback: (scope async): a #GAsyncReadyCallback to call
2026 * when the request is satisfied
2027 * @user_data: (closure): the data to pass to callback function
2028 *
2029 * Asynchronously opens @file for appending.
2030 *
2031 * For more details, see g_file_append_to() which is
2032 * the synchronous version of this call.
2033 *
2034 * When the operation is finished, @callback will be called.
2035 * You can then call g_file_append_to_finish() to get the result
2036 * of the operation.
2037 */
2038 void
2040 GFileCreateFlags flags,
2043 GAsyncReadyCallback callback,
2044 gpointer user_data)
2045 {
2052 flags,
2053 io_priority,
2054 cancellable,
2055 callback,
2056 user_data);
2057 }
2059 /**
2060 * g_file_append_to_finish:
2061 * @file: input #GFile
2062 * @res: #GAsyncResult
2063 * @error: a #GError, or %NULL
2064 *
2065 * Finishes an asynchronous file append operation started with
2066 * g_file_append_to_async().
2067 *
2068 * Returns: (transfer full): a valid #GFileOutputStream
2069 * or %NULL on error.
2070 * Free the returned object with g_object_unref().
2071 */
2072 GFileOutputStream *
2076 {
2087 }
2089 /**
2090 * g_file_create_async:
2091 * @file: input #GFile
2092 * @flags: a set of #GFileCreateFlags
2093 * @io_priority: the [I/O priority][io-priority] of the request
2094 * @cancellable: (allow-none): optional #GCancellable object,
2095 * %NULL to ignore
2096 * @callback: (scope async): a #GAsyncReadyCallback to call
2097 * when the request is satisfied
2098 * @user_data: (closure): the data to pass to callback function
2099 *
2100 * Asynchronously creates a new file and returns an output stream
2101 * for writing to it. The file must not already exist.
2102 *
2103 * For more details, see g_file_create() which is
2104 * the synchronous version of this call.
2105 *
2106 * When the operation is finished, @callback will be called.
2107 * You can then call g_file_create_finish() to get the result
2108 * of the operation.
2109 */
2110 void
2112 GFileCreateFlags flags,
2115 GAsyncReadyCallback callback,
2116 gpointer user_data)
2117 {
2124 flags,
2125 io_priority,
2126 cancellable,
2127 callback,
2128 user_data);
2129 }
2131 /**
2132 * g_file_create_finish:
2133 * @file: input #GFile
2134 * @res: a #GAsyncResult
2135 * @error: a #GError, or %NULL
2136 *
2137 * Finishes an asynchronous file create operation started with
2138 * g_file_create_async().
2139 *
2140 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
2141 * Free the returned object with g_object_unref().
2142 */
2143 GFileOutputStream *
2147 {
2158 }
2160 /**
2161 * g_file_replace_async:
2162 * @file: input #GFile
2163 * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
2164 * or %NULL to ignore
2165 * @make_backup: %TRUE if a backup should be created
2166 * @flags: a set of #GFileCreateFlags
2167 * @io_priority: the [I/O priority][io-priority] of the request
2168 * @cancellable: (allow-none): optional #GCancellable object,
2169 * %NULL to ignore
2170 * @callback: (scope async): a #GAsyncReadyCallback to call
2171 * when the request is satisfied
2172 * @user_data: (closure): the data to pass to callback function
2173 *
2174 * Asynchronously overwrites the file, replacing the contents,
2175 * possibly creating a backup copy of the file first.
2176 *
2177 * For more details, see g_file_replace() which is
2178 * the synchronous version of this call.
2179 *
2180 * When the operation is finished, @callback will be called.
2181 * You can then call g_file_replace_finish() to get the result
2182 * of the operation.
2183 */
2184 void
2187 gboolean make_backup,
2188 GFileCreateFlags flags,
2191 GAsyncReadyCallback callback,
2192 gpointer user_data)
2193 {
2200 etag,
2201 make_backup,
2202 flags,
2203 io_priority,
2204 cancellable,
2205 callback,
2206 user_data);
2207 }
2209 /**
2210 * g_file_replace_finish:
2211 * @file: input #GFile
2212 * @res: a #GAsyncResult
2213 * @error: a #GError, or %NULL
2214 *
2215 * Finishes an asynchronous file replace operation started with
2216 * g_file_replace_async().
2217 *
2218 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
2219 * Free the returned object with g_object_unref().
2220 */
2221 GFileOutputStream *
2225 {
2236 }
2238 /**
2239 * g_file_open_readwrite_async
2240 * @file: input #GFile
2241 * @io_priority: the [I/O priority][io-priority] of the request
2242 * @cancellable: (allow-none): optional #GCancellable object,
2243 * %NULL to ignore
2244 * @callback: (scope async): a #GAsyncReadyCallback to call
2245 * when the request is satisfied
2246 * @user_data: (closure): the data to pass to callback function
2247 *
2248 * Asynchronously opens @file for reading and writing.
2249 *
2250 * For more details, see g_file_open_readwrite() which is
2251 * the synchronous version of this call.
2252 *
2253 * When the operation is finished, @callback will be called.
2254 * You can then call g_file_open_readwrite_finish() to get
2255 * the result of the operation.
2256 *
2257 * Since: 2.22
2258 */
2259 void
2263 GAsyncReadyCallback callback,
2264 gpointer user_data)
2265 {
2272 io_priority,
2273 cancellable,
2274 callback,
2275 user_data);
2276 }
2278 /**
2279 * g_file_open_readwrite_finish:
2280 * @file: input #GFile
2281 * @res: a #GAsyncResult
2282 * @error: a #GError, or %NULL
2283 *
2284 * Finishes an asynchronous file read operation started with
2285 * g_file_open_readwrite_async().
2286 *
2287 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
2288 * Free the returned object with g_object_unref().
2289 *
2290 * Since: 2.22
2291 */
2292 GFileIOStream *
2296 {
2307 }
2309 /**
2310 * g_file_create_readwrite_async:
2311 * @file: input #GFile
2312 * @flags: a set of #GFileCreateFlags
2313 * @io_priority: the [I/O priority][io-priority] of the request
2314 * @cancellable: (allow-none): optional #GCancellable object,
2315 * %NULL to ignore
2316 * @callback: (scope async): a #GAsyncReadyCallback to call
2317 * when the request is satisfied
2318 * @user_data: (closure): the data to pass to callback function
2319 *
2320 * Asynchronously creates a new file and returns a stream
2321 * for reading and writing to it. The file must not already exist.
2322 *
2323 * For more details, see g_file_create_readwrite() which is
2324 * the synchronous version of this call.
2325 *
2326 * When the operation is finished, @callback will be called.
2327 * You can then call g_file_create_readwrite_finish() to get
2328 * the result of the operation.
2329 *
2330 * Since: 2.22
2331 */
2332 void
2334 GFileCreateFlags flags,
2337 GAsyncReadyCallback callback,
2338 gpointer user_data)
2339 {
2346 flags,
2347 io_priority,
2348 cancellable,
2349 callback,
2350 user_data);
2351 }
2353 /**
2354 * g_file_create_readwrite_finish:
2355 * @file: input #GFile
2356 * @res: a #GAsyncResult
2357 * @error: a #GError, or %NULL
2358 *
2359 * Finishes an asynchronous file create operation started with
2360 * g_file_create_readwrite_async().
2361 *
2362 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
2363 * Free the returned object with g_object_unref().
2364 *
2365 * Since: 2.22
2366 */
2367 GFileIOStream *
2371 {
2382 }
2384 /**
2385 * g_file_replace_readwrite_async:
2386 * @file: input #GFile
2387 * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
2388 * or %NULL to ignore
2389 * @make_backup: %TRUE if a backup should be created
2390 * @flags: a set of #GFileCreateFlags
2391 * @io_priority: the [I/O priority][io-priority] of the request
2392 * @cancellable: (allow-none): optional #GCancellable object,
2393 * %NULL to ignore
2394 * @callback: (scope async): a #GAsyncReadyCallback to call
2395 * when the request is satisfied
2396 * @user_data: (closure): the data to pass to callback function
2397 *
2398 * Asynchronously overwrites the file in read-write mode,
2399 * replacing the contents, possibly creating a backup copy
2400 * of the file first.
2401 *
2402 * For more details, see g_file_replace_readwrite() which is
2403 * the synchronous version of this call.
2404 *
2405 * When the operation is finished, @callback will be called.
2406 * You can then call g_file_replace_readwrite_finish() to get
2407 * the result of the operation.
2408 *
2409 * Since: 2.22
2410 */
2411 void
2414 gboolean make_backup,
2415 GFileCreateFlags flags,
2418 GAsyncReadyCallback callback,
2419 gpointer user_data)
2420 {
2427 etag,
2428 make_backup,
2429 flags,
2430 io_priority,
2431 cancellable,
2432 callback,
2433 user_data);
2434 }
2436 /**
2437 * g_file_replace_readwrite_finish:
2438 * @file: input #GFile
2439 * @res: a #GAsyncResult
2440 * @error: a #GError, or %NULL
2441 *
2442 * Finishes an asynchronous file replace operation started with
2443 * g_file_replace_readwrite_async().
2444 *
2445 * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
2446 * Free the returned object with g_object_unref().
2447 *
2448 * Since: 2.22
2449 */
2450 GFileIOStream *
2454 {
2465 }
2467 static gboolean
2469 GFileCopyFlags flags,
2473 {
2475 gboolean tried_delete;
2477 GFileType file_type;
2481 retry:
2484 {
2485 /* Maybe it already existed, and we want to overwrite? */
2488 {
2491 /* Don't overwrite if the destination is a directory */
2493 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2496 {
2501 {
2505 }
2506 }
2513 }
2514 /* Nah, fail */
2517 }
2520 }
2525 GFileCopyFlags flags,
2528 {
2532 GFileType file_type;
2539 /* There was an error opening the source, try to set a good error for it: */
2541 {
2542 /* The source is a directory, don't fail with WOULD_RECURSE immediately,
2543 * as that is less useful to the app. Better check for errors on the
2544 * target instead.
2545 */
2550 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2554 {
2559 {
2561 {
2565 }
2566 /* continue to would_recurse error */
2567 }
2568 else
2569 {
2573 }
2574 }
2575 else
2576 {
2577 /* Error getting info from target, return that error
2578 * (except for NOT_FOUND, which is no error here)
2579 */
2582 {
2585 }
2587 }
2592 }
2596 }
2598 static gboolean
2600 gboolean copy_all_attributes,
2601 gboolean skip_perms)
2602 {
2609 }
2611 static gboolean
2613 GFileCopyFlags flags,
2617 {
2621 gboolean first;
2623 gboolean copy_all_attributes;
2624 gboolean skip_perms;
2629 /* Ignore errors here, if the target supports no attributes there is
2630 * nothing to copy. We still honor the cancellable though.
2631 */
2647 {
2649 {
2651 {
2654 else
2658 }
2659 }
2660 }
2663 {
2665 {
2667 {
2670 else
2675 }
2676 }
2677 }
2682 out:
2691 }
2693 /**
2694 * g_file_copy_attributes:
2695 * @source: a #GFile with attributes
2696 * @destination: a #GFile to copy attributes to
2697 * @flags: a set of #GFileCopyFlags
2698 * @cancellable: (allow-none): optional #GCancellable object,
2699 * %NULL to ignore
2700 * @error: a #GError, %NULL to ignore
2701 *
2702 * Copies the file attributes from @source to @destination.
2703 *
2704 * Normally only a subset of the file attributes are copied,
2705 * those that are copies in a normal file copy operation
2706 * (which for instance does not include e.g. owner). However
2707 * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
2708 * all the metadata that is possible to copy is copied. This
2709 * is useful when implementing move by copy + delete source.
2710 *
2711 * Returns: %TRUE if the attributes were copied successfully,
2712 * %FALSE otherwise.
2713 */
2714 gboolean
2717 GFileCopyFlags flags,
2720 {
2722 gboolean res;
2724 gboolean source_nofollow_symlinks;
2732 /* Ignore errors here, if we can't read some info (e.g. if it doesn't exist)
2733 * we just don't copy it.
2734 */
2737 cancellable,
2738 NULL);
2744 {
2746 info,
2747 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2748 cancellable,
2749 error);
2751 }
2754 }
2756 static gboolean
2761 GFileProgressCallback progress_callback,
2762 gpointer progress_callback_data,
2764 {
2766 goffset current_size;
2768 gboolean res;
2769 goffset total_size;
2773 /* avoid performance impact of querying total size when it's not needed */
2775 {
2777 G_FILE_ATTRIBUTE_STANDARD_SIZE,
2780 {
2784 }
2787 {
2789 G_FILE_ATTRIBUTE_STANDARD_SIZE,
2790 G_FILE_QUERY_INFO_NONE,
2793 {
2797 }
2798 }
2799 }
2807 {
2810 {
2813 }
2822 {
2825 {
2828 }
2832 }
2839 }
2841 /* Make sure we send full copied size */
2846 }
2848 #ifdef HAVE_SPLICE
2850 static gboolean
2858 {
2861 retry:
2865 {
2873 else
2880 }
2884 }
2886 static gboolean
2890 GFileProgressCallback progress_callback,
2891 gpointer progress_callback_data,
2893 {
2895 gboolean res;
2896 goffset total_size;
2897 loff_t offset_in;
2898 loff_t offset_out;
2908 /* avoid performance impact of querying total size when it's not needed */
2910 {
2915 }
2923 {
2934 {
2937 }
2940 {
2948 }
2952 }
2954 /* Make sure we send full copied size */
2964 out:
2971 }
2972 #endif
2974 #ifdef __linux__
2975 static gboolean
2980 GFileProgressCallback progress_callback,
2981 gpointer progress_callback_data,
2983 {
2984 goffset source_size;
2994 /* Btrfs clone ioctl properties:
2995 * - Works at the inode level
2996 * - Doesn't work with directories
2997 * - Always follows symlinks (source and destination)
2998 *
2999 * By the time we get here, *in and *out are both regular files */
3003 {
3006 G_IO_ERROR_NOT_SUPPORTED,
3010 G_IO_ERROR_NOT_SUPPORTED,
3012 else
3013 /* Most probably something odd happened; retry with fallback */
3015 G_IO_ERROR_NOT_SUPPORTED,
3017 /* We retry with fallback for all error cases because Btrfs is currently
3018 * unstable, and so we can't trust it to do clone properly.
3019 * In addition, any hard errors here would cause the same failure in the
3020 * fallback manual copy as well. */
3022 }
3024 /* Make sure we send full copied size */
3029 }
3030 #endif
3032 static gboolean
3035 GFileCopyFlags flags,
3037 GFileProgressCallback progress_callback,
3038 gpointer progress_callback_data,
3040 {
3050 /* need to know the file type */
3053 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3054 cancellable,
3055 error);
3059 /* Maybe copy the symlink? */
3062 {
3065 {
3071 }
3072 /* ... else fall back on a regular file copy */
3073 }
3074 /* Handle "special" files (pipes, device nodes, ...)? */
3076 {
3077 /* FIXME: could try to recreate device nodes and others? */
3081 }
3083 /* Everything else should just fall back on a regular copy. */
3095 {
3098 /* Ok, ditch the previous lightweight info (on Unix we just
3099 * called lstat()); at this point we gather all the information
3100 * we need about the source from the opened file descriptor.
3101 */
3107 {
3108 /* Not all gvfs backends implement query_info_on_read(), we
3109 * can just fall back to the pathname again.
3110 * https://bugzilla.gnome.org/706254
3111 */
3113 {
3117 }
3118 else
3119 {
3123 }
3124 }
3130 }
3132 /* In the local file path, we pass down the source info which
3133 * includes things like unix::mode, to ensure that the target file
3134 * is not created with different permissions from the source file.
3135 *
3136 * If a future API like g_file_replace_with_info() is added, switch
3137 * this code to use that.
3138 */
3140 {
3142 out = (GOutputStream*)_g_local_file_output_stream_replace (_g_local_file_get_filename (G_LOCAL_FILE (destination)),
3145 G_FILE_CREATE_REPLACE_DESTINATION,
3146 info,
3148 else
3149 out = (GOutputStream*)_g_local_file_output_stream_create (_g_local_file_get_filename (G_LOCAL_FILE (destination)),
3152 }
3154 {
3156 NULL,
3158 G_FILE_CREATE_REPLACE_DESTINATION,
3160 }
3161 else
3162 {
3164 }
3169 #ifdef __linux__
3171 {
3177 {
3179 {
3181 }
3182 else
3183 {
3186 }
3187 }
3188 else
3189 {
3192 }
3193 }
3194 #endif
3196 #ifdef HAVE_SPLICE
3198 {
3204 {
3206 {
3208 }
3209 else
3210 {
3213 }
3214 }
3215 else
3216 {
3219 }
3220 }
3222 #endif
3224 /* A plain read/write loop */
3227 error))
3231 out:
3233 {
3234 /* Don't care about errors in source here */
3237 }
3240 {
3241 /* But write errors on close are bad! */
3245 }
3247 /* Ignore errors here. Failure to copy metadata is not a hard error */
3248 /* TODO: set these attributes /before/ we do the rename() on Unix */
3250 {
3252 info,
3253 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3254 cancellable,
3255 NULL);
3256 }
3261 }
3263 /**
3264 * g_file_copy:
3265 * @source: input #GFile
3266 * @destination: destination #GFile
3267 * @flags: set of #GFileCopyFlags
3268 * @cancellable: (allow-none): optional #GCancellable object,
3269 * %NULL to ignore
3270 * @progress_callback: (allow-none) (scope call): function to callback with
3271 * progress information, or %NULL if progress information is not needed
3272 * @progress_callback_data: (closure): user data to pass to @progress_callback
3273 * @error: #GError to set on error, or %NULL
3274 *
3275 * Copies the file @source to the location specified by @destination.
3276 * Can not handle recursive copies of directories.
3277 *
3278 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
3279 * existing @destination file is overwritten.
3280 *
3281 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
3282 * will be copied as symlinks, otherwise the target of the
3283 * @source symlink will be copied.
3284 *
3285 * If @cancellable is not %NULL, then the operation can be cancelled by
3286 * triggering the cancellable object from another thread. If the operation
3287 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3288 *
3289 * If @progress_callback is not %NULL, then the operation can be monitored
3290 * by setting this to a #GFileProgressCallback function.
3291 * @progress_callback_data will be passed to this function. It is guaranteed
3292 * that this callback will be called after all data has been transferred with
3293 * the total number of bytes copied during the operation.
3294 *
3295 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
3296 * is returned, independent on the status of the @destination.
3297 *
3298 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
3299 * the error %G_IO_ERROR_EXISTS is returned.
3300 *
3301 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
3302 * error is returned. If trying to overwrite a directory with a directory the
3303 * %G_IO_ERROR_WOULD_MERGE error is returned.
3304 *
3305 * If the source is a directory and the target does not exist, or
3306 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
3307 * %G_IO_ERROR_WOULD_RECURSE error is returned.
3308 *
3309 * If you are interested in copying the #GFile object itself (not the on-disk
3310 * file), see g_file_dup().
3311 *
3312 * Returns: %TRUE on success, %FALSE otherwise.
3313 */
3314 gboolean
3317 GFileCopyFlags flags,
3319 GFileProgressCallback progress_callback,
3320 gpointer progress_callback_data,
3322 {
3325 gboolean res;
3335 {
3346 {
3349 }
3350 else
3352 }
3354 /* If the types are different, and the destination method failed
3355 * also try the source method
3356 */
3358 {
3362 {
3373 {
3376 }
3377 else
3379 }
3380 }
3384 error);
3385 }
3387 /**
3388 * g_file_copy_async: (skip)
3389 * @source: input #GFile
3390 * @destination: destination #GFile
3391 * @flags: set of #GFileCopyFlags
3392 * @io_priority: the [I/O priority][io-priority] of the request
3393 * @cancellable: (allow-none): optional #GCancellable object,
3394 * %NULL to ignore
3395 * @progress_callback: (allow-none): function to callback with progress
3396 * information, or %NULL if progress information is not needed
3397 * @progress_callback_data: (closure): user data to pass to @progress_callback
3398 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
3399 * @user_data: the data to pass to callback function
3400 *
3401 * Copies the file @source to the location specified by @destination
3402 * asynchronously. For details of the behaviour, see g_file_copy().
3403 *
3404 * If @progress_callback is not %NULL, then that function that will be called
3405 * just like in g_file_copy(). The callback will run in the default main context
3406 * of the thread calling g_file_copy_async() — the same context as @callback is
3407 * run in.
3408 *
3409 * When the operation is finished, @callback will be called. You can then call
3410 * g_file_copy_finish() to get the result of the operation.
3411 */
3412 void
3415 GFileCopyFlags flags,
3418 GFileProgressCallback progress_callback,
3419 gpointer progress_callback_data,
3420 GAsyncReadyCallback callback,
3421 gpointer user_data)
3422 {
3430 destination,
3431 flags,
3432 io_priority,
3433 cancellable,
3434 progress_callback,
3435 progress_callback_data,
3436 callback,
3437 user_data);
3438 }
3440 /**
3441 * g_file_copy_finish:
3442 * @file: input #GFile
3443 * @res: a #GAsyncResult
3444 * @error: a #GError, or %NULL
3445 *
3446 * Finishes copying the file started with g_file_copy_async().
3447 *
3448 * Returns: a %TRUE on success, %FALSE on error.
3449 */
3450 gboolean
3454 {
3465 }
3467 /**
3468 * g_file_move:
3469 * @source: #GFile pointing to the source location
3470 * @destination: #GFile pointing to the destination location
3471 * @flags: set of #GFileCopyFlags
3472 * @cancellable: (allow-none): optional #GCancellable object,
3473 * %NULL to ignore
3474 * @progress_callback: (allow-none) (scope call): #GFileProgressCallback
3475 * function for updates
3476 * @progress_callback_data: (closure): gpointer to user data for
3477 * the callback function
3478 * @error: #GError for returning error conditions, or %NULL
3479 *
3480 * Tries to move the file or directory @source to the location specified
3481 * by @destination. If native move operations are supported then this is
3482 * used, otherwise a copy + delete fallback is used. The native
3483 * implementation may support moving directories (for instance on moves
3484 * inside the same filesystem), but the fallback code does not.
3485 *
3486 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
3487 * existing @destination file is overwritten.
3488 *
3489 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
3490 * will be copied as symlinks, otherwise the target of the
3491 * @source symlink will be copied.
3492 *
3493 * If @cancellable is not %NULL, then the operation can be cancelled by
3494 * triggering the cancellable object from another thread. If the operation
3495 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3496 *
3497 * If @progress_callback is not %NULL, then the operation can be monitored
3498 * by setting this to a #GFileProgressCallback function.
3499 * @progress_callback_data will be passed to this function. It is
3500 * guaranteed that this callback will be called after all data has been
3501 * transferred with the total number of bytes copied during the operation.
3502 *
3503 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
3504 * error is returned, independent on the status of the @destination.
3505 *
3506 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
3507 * then the error %G_IO_ERROR_EXISTS is returned.
3508 *
3509 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
3510 * error is returned. If trying to overwrite a directory with a directory the
3511 * %G_IO_ERROR_WOULD_MERGE error is returned.
3512 *
3513 * If the source is a directory and the target does not exist, or
3514 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then
3515 * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
3516 * move operation isn't available).
3517 *
3518 * Returns: %TRUE on successful move, %FALSE otherwise.
3519 */
3520 gboolean
3523 GFileCopyFlags flags,
3525 GFileProgressCallback progress_callback,
3526 gpointer progress_callback_data,
3528 {
3531 gboolean res;
3541 {
3552 {
3555 }
3556 }
3558 /* If the types are different, and the destination method failed
3559 * also try the source method
3560 */
3562 {
3566 {
3577 {
3580 }
3581 }
3582 }
3585 {
3587 G_IO_ERROR_NOT_SUPPORTED,
3590 }
3595 error))
3599 }
3601 /**
3602 * g_file_make_directory:
3603 * @file: input #GFile
3604 * @cancellable: (allow-none): optional #GCancellable object,
3605 * %NULL to ignore
3606 * @error: a #GError, or %NULL
3607 *
3608 * Creates a directory. Note that this will only create a child directory
3609 * of the immediate parent directory of the path or URI given by the #GFile.
3610 * To recursively create directories, see g_file_make_directory_with_parents().
3611 * This function will fail if the parent directory does not exist, setting
3612 * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
3613 * creating directories, this function will fail, setting @error to
3614 * %G_IO_ERROR_NOT_SUPPORTED.
3615 *
3616 * For a local #GFile the newly created directory will have the default
3617 * (current) ownership and permissions of the current process.
3618 *
3619 * If @cancellable is not %NULL, then the operation can be cancelled by
3620 * triggering the cancellable object from another thread. If the operation
3621 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3622 *
3623 * Returns: %TRUE on successful creation, %FALSE otherwise.
3624 */
3625 gboolean
3629 {
3640 {
3642 G_IO_ERROR_NOT_SUPPORTED,
3645 }
3648 }
3650 /**
3651 * g_file_make_directory_async:
3652 * @file: input #GFile
3653 * @io_priority: the [I/O priority][io-priority] of the request
3654 * @cancellable: (allow-none): optional #GCancellable object,
3655 * %NULL to ignore
3656 * @callback: a #GAsyncReadyCallback to call
3657 * when the request is satisfied
3658 * @user_data: the data to pass to callback function
3659 *
3660 * Asynchronously creates a directory.
3661 *
3662 * Virtual: make_directory_async
3663 * Since: 2.38
3664 */
3665 void
3669 GAsyncReadyCallback callback,
3670 gpointer user_data)
3671 {
3678 io_priority,
3679 cancellable,
3680 callback,
3681 user_data);
3682 }
3684 /**
3685 * g_file_make_directory_finish:
3686 * @file: input #GFile
3687 * @result: a #GAsyncResult
3688 * @error: a #GError, or %NULL
3689 *
3690 * Finishes an asynchronous directory creation, started with
3691 * g_file_make_directory_async().
3692 *
3693 * Virtual: make_directory_finish
3694 * Returns: %TRUE on successful directory creation, %FALSE otherwise.
3695 * Since: 2.38
3696 */
3697 gboolean
3701 {
3709 }
3711 /**
3712 * g_file_make_directory_with_parents:
3713 * @file: input #GFile
3714 * @cancellable: (allow-none): optional #GCancellable object,
3715 * %NULL to ignore
3716 * @error: a #GError, or %NULL
3717 *
3718 * Creates a directory and any parent directories that may not
3719 * exist similar to 'mkdir -p'. If the file system does not support
3720 * creating directories, this function will fail, setting @error to
3721 * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
3722 * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
3723 * the similar g_mkdir_with_parents().
3724 *
3725 * For a local #GFile the newly created directories will have the default
3726 * (current) ownership and permissions of the current process.
3727 *
3728 * If @cancellable is not %NULL, then the operation can be cancelled by
3729 * triggering the cancellable object from another thread. If the operation
3730 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3731 *
3732 * Returns: %TRUE if all directories have been successfully created, %FALSE
3733 * otherwise.
3734 *
3735 * Since: 2.18
3736 */
3737 gboolean
3741 {
3753 {
3757 }
3762 {
3777 else
3779 }
3782 {
3784 }
3789 /* Clean up */
3791 {
3794 }
3797 {
3800 }
3803 }
3805 /**
3806 * g_file_make_symbolic_link:
3807 * @file: a #GFile with the name of the symlink to create
3808 * @symlink_value: a string with the path for the target of the new symlink
3809 * @cancellable: (allow-none): optional #GCancellable object,
3810 * %NULL to ignore
3811 * @error: a #GError
3812 *
3813 * Creates a symbolic link named @file which contains the string
3814 * @symlink_value.
3815 *
3816 * If @cancellable is not %NULL, then the operation can be cancelled by
3817 * triggering the cancellable object from another thread. If the operation
3818 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3819 *
3820 * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
3821 */
3822 gboolean
3827 {
3837 {
3839 G_IO_ERROR_INVALID_ARGUMENT,
3842 }
3847 {
3849 G_IO_ERROR_NOT_SUPPORTED,
3852 }
3855 }
3857 /**
3858 * g_file_delete:
3859 * @file: input #GFile
3860 * @cancellable: (allow-none): optional #GCancellable object,
3861 * %NULL to ignore
3862 * @error: a #GError, or %NULL
3863 *
3864 * Deletes a file. If the @file is a directory, it will only be
3865 * deleted if it is empty. This has the same semantics as g_unlink().
3866 *
3867 * If @cancellable is not %NULL, then the operation can be cancelled by
3868 * triggering the cancellable object from another thread. If the operation
3869 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3870 *
3871 * Virtual: delete_file
3872 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
3873 */
3874 gboolean
3878 {
3889 {
3891 G_IO_ERROR_NOT_SUPPORTED,
3894 }
3897 }
3899 /**
3900 * g_file_delete_async:
3901 * @file: input #GFile
3902 * @io_priority: the [I/O priority][io-priority] of the request
3903 * @cancellable: (allow-none): optional #GCancellable object,
3904 * %NULL to ignore
3905 * @callback: a #GAsyncReadyCallback to call
3906 * when the request is satisfied
3907 * @user_data: the data to pass to callback function
3908 *
3909 * Asynchronously delete a file. If the @file is a directory, it will
3910 * only be deleted if it is empty. This has the same semantics as
3911 * g_unlink().
3912 *
3913 * Virtual: delete_file_async
3914 * Since: 2.34
3915 */
3916 void
3920 GAsyncReadyCallback callback,
3921 gpointer user_data)
3922 {
3929 io_priority,
3930 cancellable,
3931 callback,
3932 user_data);
3933 }
3935 /**
3936 * g_file_delete_finish:
3937 * @file: input #GFile
3938 * @result: a #GAsyncResult
3939 * @error: a #GError, or %NULL
3940 *
3941 * Finishes deleting a file started with g_file_delete_async().
3942 *
3943 * Virtual: delete_file_finish
3944 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
3945 * Since: 2.34
3946 **/
3947 gboolean
3951 {
3962 }
3964 /**
3965 * g_file_trash:
3966 * @file: #GFile to send to trash
3967 * @cancellable: (allow-none): optional #GCancellable object,
3968 * %NULL to ignore
3969 * @error: a #GError, or %NULL
3970 *
3971 * Sends @file to the "Trashcan", if possible. This is similar to
3972 * deleting it, but the user can recover it before emptying the trashcan.
3973 * Not all file systems support trashing, so this call can return the
3974 * %G_IO_ERROR_NOT_SUPPORTED error.
3975 *
3976 * If @cancellable is not %NULL, then the operation can be cancelled by
3977 * triggering the cancellable object from another thread. If the operation
3978 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3979 *
3980 * Virtual: trash
3981 * Returns: %TRUE on successful trash, %FALSE otherwise.
3982 */
3983 gboolean
3987 {
3998 {
4003 }
4006 }
4008 /**
4009 * g_file_trash_async:
4010 * @file: input #GFile
4011 * @io_priority: the [I/O priority][io-priority] of the request
4012 * @cancellable: (allow-none): optional #GCancellable object,
4013 * %NULL to ignore
4014 * @callback: a #GAsyncReadyCallback to call
4015 * when the request is satisfied
4016 * @user_data: the data to pass to callback function
4017 *
4018 * Asynchronously sends @file to the Trash location, if possible.
4019 *
4020 * Virtual: trash_async
4021 * Since: 2.38
4022 */
4023 void
4027 GAsyncReadyCallback callback,
4028 gpointer user_data)
4029 {
4036 io_priority,
4037 cancellable,
4038 callback,
4039 user_data);
4040 }
4042 /**
4043 * g_file_trash_finish:
4044 * @file: input #GFile
4045 * @result: a #GAsyncResult
4046 * @error: a #GError, or %NULL
4047 *
4048 * Finishes an asynchronous file trashing operation, started with
4049 * g_file_trash_async().
4050 *
4051 * Virtual: trash_finish
4052 * Returns: %TRUE on successful trash, %FALSE otherwise.
4053 * Since: 2.38
4054 */
4055 gboolean
4059 {
4067 }
4069 /**
4070 * g_file_set_display_name:
4071 * @file: input #GFile
4072 * @display_name: a string
4073 * @cancellable: (allow-none): optional #GCancellable object,
4074 * %NULL to ignore
4075 * @error: a #GError, or %NULL
4076 *
4077 * Renames @file to the specified display name.
4078 *
4079 * The display name is converted from UTF-8 to the correct encoding
4080 * for the target filesystem if possible and the @file is renamed to this.
4081 *
4082 * If you want to implement a rename operation in the user interface the
4083 * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
4084 * initial value in the rename widget, and then the result after editing
4085 * should be passed to g_file_set_display_name().
4086 *
4087 * On success the resulting converted filename is returned.
4088 *
4089 * If @cancellable is not %NULL, then the operation can be cancelled by
4090 * triggering the cancellable object from another thread. If the operation
4091 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4092 *
4093 * Returns: (transfer full): a #GFile specifying what @file was renamed to,
4094 * or %NULL if there was an error.
4095 * Free the returned object with g_object_unref().
4096 */
4097 GFile *
4102 {
4109 {
4111 G_IO_ERROR,
4112 G_IO_ERROR_INVALID_ARGUMENT,
4115 }
4123 }
4125 /**
4126 * g_file_set_display_name_async:
4127 * @file: input #GFile
4128 * @display_name: a string
4129 * @io_priority: the [I/O priority][io-priority] of the request
4130 * @cancellable: (allow-none): optional #GCancellable object,
4131 * %NULL to ignore
4132 * @callback: (scope async): a #GAsyncReadyCallback to call
4133 * when the request is satisfied
4134 * @user_data: (closure): the data to pass to callback function
4135 *
4136 * Asynchronously sets the display name for a given #GFile.
4137 *
4138 * For more details, see g_file_set_display_name() which is
4139 * the synchronous version of this call.
4140 *
4141 * When the operation is finished, @callback will be called.
4142 * You can then call g_file_set_display_name_finish() to get
4143 * the result of the operation.
4144 */
4145 void
4148 gint io_priority,
4150 GAsyncReadyCallback callback,
4151 gpointer user_data)
4152 {
4160 display_name,
4161 io_priority,
4162 cancellable,
4163 callback,
4164 user_data);
4165 }
4167 /**
4168 * g_file_set_display_name_finish:
4169 * @file: input #GFile
4170 * @res: a #GAsyncResult
4171 * @error: a #GError, or %NULL
4172 *
4173 * Finishes setting a display name started with
4174 * g_file_set_display_name_async().
4175 *
4176 * Returns: (transfer full): a #GFile or %NULL on error.
4177 * Free the returned object with g_object_unref().
4178 */
4179 GFile *
4183 {
4194 }
4196 /**
4197 * g_file_query_settable_attributes:
4198 * @file: input #GFile
4199 * @cancellable: (allow-none): optional #GCancellable object,
4200 * %NULL to ignore
4201 * @error: a #GError, or %NULL
4202 *
4203 * Obtain the list of settable attributes for the file.
4204 *
4205 * Returns the type and full attribute name of all the attributes
4206 * that can be set on this file. This doesn't mean setting it will
4207 * always succeed though, you might get an access failure, or some
4208 * specific file may not support a specific attribute.
4209 *
4210 * If @cancellable is not %NULL, then the operation can be cancelled by
4211 * triggering the cancellable object from another thread. If the operation
4212 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4213 *
4214 * Returns: a #GFileAttributeInfoList describing the settable attributes.
4215 * When you are done with it, release it with
4216 * g_file_attribute_info_list_unref()
4217 */
4218 GFileAttributeInfoList *
4222 {
4241 {
4243 {
4246 }
4247 else
4249 }
4252 }
4254 /**
4255 * g_file_query_writable_namespaces:
4256 * @file: input #GFile
4257 * @cancellable: (allow-none): optional #GCancellable object,
4258 * %NULL to ignore
4259 * @error: a #GError, or %NULL
4260 *
4261 * Obtain the list of attribute namespaces where new attributes
4262 * can be created by a user. An example of this is extended
4263 * attributes (in the "xattr" namespace).
4264 *
4265 * If @cancellable is not %NULL, then the operation can be cancelled by
4266 * triggering the cancellable object from another thread. If the operation
4267 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4268 *
4269 * Returns: a #GFileAttributeInfoList describing the writable namespaces.
4270 * When you are done with it, release it with
4271 * g_file_attribute_info_list_unref()
4272 */
4273 GFileAttributeInfoList *
4277 {
4296 {
4298 {
4301 }
4302 else
4304 }
4307 }
4309 /**
4310 * g_file_set_attribute:
4311 * @file: input #GFile
4312 * @attribute: a string containing the attribute's name
4313 * @type: The type of the attribute
4314 * @value_p: (allow-none): a pointer to the value (or the pointer
4315 * itself if the type is a pointer type)
4316 * @flags: a set of #GFileQueryInfoFlags
4317 * @cancellable: (allow-none): optional #GCancellable object,
4318 * %NULL to ignore
4319 * @error: a #GError, or %NULL
4320 *
4321 * Sets an attribute in the file with attribute name @attribute to @value.
4322 *
4323 * Some attributes can be unset by setting @attribute to
4324 * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
4325 *
4326 * If @cancellable is not %NULL, then the operation can be cancelled by
4327 * triggering the cancellable object from another thread. If the operation
4328 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4329 *
4330 * Returns: %TRUE if the attribute was set, %FALSE otherwise.
4331 */
4332 gboolean
4335 GFileAttributeType type,
4336 gpointer value_p,
4337 GFileQueryInfoFlags flags,
4340 {
4352 {
4354 G_IO_ERROR_NOT_SUPPORTED,
4357 }
4360 }
4362 /**
4363 * g_file_set_attributes_from_info:
4364 * @file: input #GFile
4365 * @info: a #GFileInfo
4366 * @flags: #GFileQueryInfoFlags
4367 * @cancellable: (allow-none): optional #GCancellable object,
4368 * %NULL to ignore
4369 * @error: a #GError, or %NULL
4370 *
4371 * Tries to set all attributes in the #GFileInfo on the target
4372 * values, not stopping on the first error.
4373 *
4374 * If there is any error during this operation then @error will
4375 * be set to the first error. Error on particular fields are flagged
4376 * by setting the "status" field in the attribute value to
4377 * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
4378 * also detect further errors.
4379 *
4380 * If @cancellable is not %NULL, then the operation can be cancelled by
4381 * triggering the cancellable object from another thread. If the operation
4382 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4383 *
4384 * Returns: %FALSE if there was any error, %TRUE otherwise.
4385 */
4386 gboolean
4389 GFileQueryInfoFlags flags,
4392 {
4406 info,
4407 flags,
4408 cancellable,
4409 error);
4410 }
4412 static gboolean
4415 GFileQueryInfoFlags flags,
4418 {
4421 gboolean res;
4429 {
4438 {
4441 /* Don't set error multiple times */
4443 }
4444 else
4446 }
4451 }
4453 /**
4454 * g_file_set_attributes_async:
4455 * @file: input #GFile
4456 * @info: a #GFileInfo
4457 * @flags: a #GFileQueryInfoFlags
4458 * @io_priority: the [I/O priority][io-priority] of the request
4459 * @cancellable: (allow-none): optional #GCancellable object,
4460 * %NULL to ignore
4461 * @callback: (scope async): a #GAsyncReadyCallback
4462 * @user_data: (closure): a #gpointer
4463 *
4464 * Asynchronously sets the attributes of @file with @info.
4465 *
4466 * For more details, see g_file_set_attributes_from_info(),
4467 * which is the synchronous version of this call.
4468 *
4469 * When the operation is finished, @callback will be called.
4470 * You can then call g_file_set_attributes_finish() to get
4471 * the result of the operation.
4472 */
4473 void
4476 GFileQueryInfoFlags flags,
4479 GAsyncReadyCallback callback,
4480 gpointer user_data)
4481 {
4489 info,
4490 flags,
4491 io_priority,
4492 cancellable,
4493 callback,
4494 user_data);
4495 }
4497 /**
4498 * g_file_set_attributes_finish:
4499 * @file: input #GFile
4500 * @result: a #GAsyncResult
4501 * @info: (out) (transfer full): a #GFileInfo
4502 * @error: a #GError, or %NULL
4503 *
4504 * Finishes setting an attribute started in g_file_set_attributes_async().
4505 *
4506 * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
4507 */
4508 gboolean
4513 {
4519 /* No standard handling of errors here, as we must set info even
4520 * on errors
4521 */
4524 }
4526 /**
4527 * g_file_set_attribute_string:
4528 * @file: input #GFile
4529 * @attribute: a string containing the attribute's name
4530 * @value: a string containing the attribute's value
4531 * @flags: #GFileQueryInfoFlags
4532 * @cancellable: (allow-none): optional #GCancellable object,
4533 * %NULL to ignore
4534 * @error: a #GError, or %NULL
4535 *
4536 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
4537 * If @attribute is of a different type, this operation will fail.
4538 *
4539 * If @cancellable is not %NULL, then the operation can be cancelled by
4540 * triggering the cancellable object from another thread. If the operation
4541 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4542 *
4543 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
4544 */
4545 gboolean
4549 GFileQueryInfoFlags flags,
4552 {
4556 }
4558 /**
4559 * g_file_set_attribute_byte_string:
4560 * @file: input #GFile
4561 * @attribute: a string containing the attribute's name
4562 * @value: a string containing the attribute's new value
4563 * @flags: a #GFileQueryInfoFlags
4564 * @cancellable: (allow-none): optional #GCancellable object,
4565 * %NULL to ignore
4566 * @error: a #GError, or %NULL
4567 *
4568 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
4569 * If @attribute is of a different type, this operation will fail,
4570 * returning %FALSE.
4571 *
4572 * If @cancellable is not %NULL, then the operation can be cancelled by
4573 * triggering the cancellable object from another thread. If the operation
4574 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4575 *
4576 * Returns: %TRUE if the @attribute was successfully set to @value
4577 * in the @file, %FALSE otherwise.
4578 */
4579 gboolean
4583 GFileQueryInfoFlags flags,
4586 {
4590 }
4592 /**
4593 * g_file_set_attribute_uint32:
4594 * @file: input #GFile
4595 * @attribute: a string containing the attribute's name
4596 * @value: a #guint32 containing the attribute's new value
4597 * @flags: a #GFileQueryInfoFlags
4598 * @cancellable: (allow-none): optional #GCancellable object,
4599 * %NULL to ignore
4600 * @error: a #GError, or %NULL
4601 *
4602 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
4603 * If @attribute is of a different type, this operation will fail.
4604 *
4605 * If @cancellable is not %NULL, then the operation can be cancelled by
4606 * triggering the cancellable object from another thread. If the operation
4607 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4608 *
4609 * Returns: %TRUE if the @attribute was successfully set to @value
4610 * in the @file, %FALSE otherwise.
4611 */
4612 gboolean
4615 guint32 value,
4616 GFileQueryInfoFlags flags,
4619 {
4623 }
4625 /**
4626 * g_file_set_attribute_int32:
4627 * @file: input #GFile
4628 * @attribute: a string containing the attribute's name
4629 * @value: a #gint32 containing the attribute's new value
4630 * @flags: a #GFileQueryInfoFlags
4631 * @cancellable: (allow-none): optional #GCancellable object,
4632 * %NULL to ignore
4633 * @error: a #GError, or %NULL
4634 *
4635 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
4636 * If @attribute is of a different type, this operation will fail.
4637 *
4638 * If @cancellable is not %NULL, then the operation can be cancelled by
4639 * triggering the cancellable object from another thread. If the operation
4640 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4641 *
4642 * Returns: %TRUE if the @attribute was successfully set to @value
4643 * in the @file, %FALSE otherwise.
4644 */
4645 gboolean
4648 gint32 value,
4649 GFileQueryInfoFlags flags,
4652 {
4656 }
4658 /**
4659 * g_file_set_attribute_uint64:
4660 * @file: input #GFile
4661 * @attribute: a string containing the attribute's name
4662 * @value: a #guint64 containing the attribute's new value
4663 * @flags: a #GFileQueryInfoFlags
4664 * @cancellable: (allow-none): optional #GCancellable object,
4665 * %NULL to ignore
4666 * @error: a #GError, or %NULL
4667 *
4668 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
4669 * If @attribute is of a different type, this operation will fail.
4670 *
4671 * If @cancellable is not %NULL, then the operation can be cancelled by
4672 * triggering the cancellable object from another thread. If the operation
4673 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4674 *
4675 * Returns: %TRUE if the @attribute was successfully set to @value
4676 * in the @file, %FALSE otherwise.
4677 */
4678 gboolean
4681 guint64 value,
4682 GFileQueryInfoFlags flags,
4685 {
4689 }
4691 /**
4692 * g_file_set_attribute_int64:
4693 * @file: input #GFile
4694 * @attribute: a string containing the attribute's name
4695 * @value: a #guint64 containing the attribute's new value
4696 * @flags: a #GFileQueryInfoFlags
4697 * @cancellable: (allow-none): optional #GCancellable object,
4698 * %NULL to ignore
4699 * @error: a #GError, or %NULL
4700 *
4701 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
4702 * If @attribute is of a different type, this operation will fail.
4703 *
4704 * If @cancellable is not %NULL, then the operation can be cancelled by
4705 * triggering the cancellable object from another thread. If the operation
4706 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4707 *
4708 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
4709 */
4710 gboolean
4713 gint64 value,
4714 GFileQueryInfoFlags flags,
4717 {
4721 }
4723 /**
4724 * g_file_mount_mountable:
4725 * @file: input #GFile
4726 * @flags: flags affecting the operation
4727 * @mount_operation: (allow-none): a #GMountOperation,
4728 * or %NULL to avoid user interaction
4729 * @cancellable: (allow-none): optional #GCancellable object,
4730 * %NULL to ignore
4731 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4732 * when the request is satisfied, or %NULL
4733 * @user_data: (closure): the data to pass to callback function
4734 *
4735 * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
4736 * Using @mount_operation, you can request callbacks when, for instance,
4737 * passwords are needed during authentication.
4738 *
4739 * If @cancellable is not %NULL, then the operation can be cancelled by
4740 * triggering the cancellable object from another thread. If the operation
4741 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4742 *
4743 * When the operation is finished, @callback will be called.
4744 * You can then call g_file_mount_mountable_finish() to get
4745 * the result of the operation.
4746 */
4747 void
4749 GMountMountFlags flags,
4752 GAsyncReadyCallback callback,
4753 gpointer user_data)
4754 {
4762 {
4764 g_file_mount_mountable,
4768 }
4771 flags,
4772 mount_operation,
4773 cancellable,
4774 callback,
4775 user_data);
4776 }
4778 /**
4779 * g_file_mount_mountable_finish:
4780 * @file: input #GFile
4781 * @result: a #GAsyncResult
4782 * @error: a #GError, or %NULL
4783 *
4784 * Finishes a mount operation. See g_file_mount_mountable() for details.
4785 *
4786 * Finish an asynchronous mount operation that was started
4787 * with g_file_mount_mountable().
4788 *
4789 * Returns: (transfer full): a #GFile or %NULL on error.
4790 * Free the returned object with g_object_unref().
4791 */
4792 GFile *
4796 {
4809 }
4811 /**
4812 * g_file_unmount_mountable:
4813 * @file: input #GFile
4814 * @flags: flags affecting the operation
4815 * @cancellable: (allow-none): optional #GCancellable object,
4816 * %NULL to ignore
4817 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4818 * when the request is satisfied, or %NULL
4819 * @user_data: (closure): the data to pass to callback function
4820 *
4821 * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
4822 *
4823 * If @cancellable is not %NULL, then the operation can be cancelled by
4824 * triggering the cancellable object from another thread. If the operation
4825 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4826 *
4827 * When the operation is finished, @callback will be called.
4828 * You can then call g_file_unmount_mountable_finish() to get
4829 * the result of the operation.
4830 *
4831 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
4832 */
4833 void
4835 GMountUnmountFlags flags,
4837 GAsyncReadyCallback callback,
4838 gpointer user_data)
4839 {
4847 {
4849 g_file_unmount_mountable_with_operation,
4853 }
4856 flags,
4857 cancellable,
4858 callback,
4859 user_data);
4860 }
4862 /**
4863 * g_file_unmount_mountable_finish:
4864 * @file: input #GFile
4865 * @result: a #GAsyncResult
4866 * @error: a #GError, or %NULL
4867 *
4868 * Finishes an unmount operation, see g_file_unmount_mountable() for details.
4869 *
4870 * Finish an asynchronous unmount operation that was started
4871 * with g_file_unmount_mountable().
4872 *
4873 * Returns: %TRUE if the operation finished successfully.
4874 * %FALSE otherwise.
4875 *
4876 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish()
4877 * instead.
4878 */
4879 gboolean
4883 {
4896 }
4898 /**
4899 * g_file_unmount_mountable_with_operation:
4900 * @file: input #GFile
4901 * @flags: flags affecting the operation
4902 * @mount_operation: (allow-none): a #GMountOperation,
4903 * or %NULL to avoid user interaction
4904 * @cancellable: (allow-none): optional #GCancellable object,
4905 * %NULL to ignore
4906 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4907 * when the request is satisfied, or %NULL
4908 * @user_data: (closure): the data to pass to callback function
4909 *
4910 * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
4911 *
4912 * If @cancellable is not %NULL, then the operation can be cancelled by
4913 * triggering the cancellable object from another thread. If the operation
4914 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4915 *
4916 * When the operation is finished, @callback will be called.
4917 * You can then call g_file_unmount_mountable_finish() to get
4918 * the result of the operation.
4919 *
4920 * Since: 2.22
4921 */
4922 void
4924 GMountUnmountFlags flags,
4927 GAsyncReadyCallback callback,
4928 gpointer user_data)
4929 {
4937 {
4939 g_file_unmount_mountable_with_operation,
4943 }
4947 flags,
4948 mount_operation,
4949 cancellable,
4950 callback,
4951 user_data);
4952 else
4954 flags,
4955 cancellable,
4956 callback,
4957 user_data);
4958 }
4960 /**
4961 * g_file_unmount_mountable_with_operation_finish:
4962 * @file: input #GFile
4963 * @result: a #GAsyncResult
4964 * @error: a #GError, or %NULL
4965 *
4966 * Finishes an unmount operation,
4967 * see g_file_unmount_mountable_with_operation() for details.
4968 *
4969 * Finish an asynchronous unmount operation that was started
4970 * with g_file_unmount_mountable_with_operation().
4971 *
4972 * Returns: %TRUE if the operation finished successfully.
4973 * %FALSE otherwise.
4974 *
4975 * Since: 2.22
4976 */
4977 gboolean
4981 {
4995 else
4997 }
4999 /**
5000 * g_file_eject_mountable:
5001 * @file: input #GFile
5002 * @flags: flags affecting the operation
5003 * @cancellable: (allow-none): optional #GCancellable object,
5004 * %NULL to ignore
5005 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
5006 * when the request is satisfied, or %NULL
5007 * @user_data: (closure): the data to pass to callback function
5008 *
5009 * Starts an asynchronous eject on a mountable.
5010 * When this operation has completed, @callback will be called with
5011 * @user_user data, and the operation can be finalized with
5012 * g_file_eject_mountable_finish().
5013 *
5014 * If @cancellable is not %NULL, then the operation can be cancelled by
5015 * triggering the cancellable object from another thread. If the operation
5016 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5017 *
5018 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
5019 */
5020 void
5022 GMountUnmountFlags flags,
5024 GAsyncReadyCallback callback,
5025 gpointer user_data)
5026 {
5034 {
5036 g_file_eject_mountable_with_operation,
5040 }
5043 flags,
5044 cancellable,
5045 callback,
5046 user_data);
5047 }
5049 /**
5050 * g_file_eject_mountable_finish:
5051 * @file: input #GFile
5052 * @result: a #GAsyncResult
5053 * @error: a #GError, or %NULL
5054 *
5055 * Finishes an asynchronous eject operation started by
5056 * g_file_eject_mountable().
5057 *
5058 * Returns: %TRUE if the @file was ejected successfully.
5059 * %FALSE otherwise.
5060 *
5061 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
5062 * instead.
5063 */
5064 gboolean
5068 {
5081 }
5083 /**
5084 * g_file_eject_mountable_with_operation:
5085 * @file: input #GFile
5086 * @flags: flags affecting the operation
5087 * @mount_operation: (allow-none): a #GMountOperation,
5088 * or %NULL to avoid user interaction
5089 * @cancellable: (allow-none): optional #GCancellable object,
5090 * %NULL to ignore
5091 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
5092 * when the request is satisfied, or %NULL
5093 * @user_data: (closure): the data to pass to callback function
5094 *
5095 * Starts an asynchronous eject on a mountable.
5096 * When this operation has completed, @callback will be called with
5097 * @user_user data, and the operation can be finalized with
5098 * g_file_eject_mountable_with_operation_finish().
5099 *
5100 * If @cancellable is not %NULL, then the operation can be cancelled by
5101 * triggering the cancellable object from another thread. If the operation
5102 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5103 *
5104 * Since: 2.22
5105 */
5106 void
5108 GMountUnmountFlags flags,
5111 GAsyncReadyCallback callback,
5112 gpointer user_data)
5113 {
5121 {
5123 g_file_eject_mountable_with_operation,
5127 }
5131 flags,
5132 mount_operation,
5133 cancellable,
5134 callback,
5135 user_data);
5136 else
5138 flags,
5139 cancellable,
5140 callback,
5141 user_data);
5142 }
5144 /**
5145 * g_file_eject_mountable_with_operation_finish:
5146 * @file: input #GFile
5147 * @result: a #GAsyncResult
5148 * @error: a #GError, or %NULL
5149 *
5150 * Finishes an asynchronous eject operation started by
5151 * g_file_eject_mountable_with_operation().
5152 *
5153 * Returns: %TRUE if the @file was ejected successfully.
5154 * %FALSE otherwise.
5155 *
5156 * Since: 2.22
5157 */
5158 gboolean
5162 {
5176 else
5178 }
5180 /**
5181 * g_file_monitor_directory:
5182 * @file: input #GFile
5183 * @flags: a set of #GFileMonitorFlags
5184 * @cancellable: (allow-none): optional #GCancellable object,
5185 * %NULL to ignore
5186 * @error: a #GError, or %NULL
5187 *
5188 * Obtains a directory monitor for the given file.
5189 * This may fail if directory monitoring is not supported.
5190 *
5191 * If @cancellable is not %NULL, then the operation can be cancelled by
5192 * triggering the cancellable object from another thread. If the operation
5193 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5194 *
5195 * It does not make sense for @flags to contain
5196 * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
5197 * directories. It is not possible to monitor all the files in a
5198 * directory for changes made via hard links; if you want to do this then
5199 * you must register individual watches with g_file_monitor().
5200 *
5201 * Virtual: monitor_dir
5202 * Returns: (transfer full): a #GFileMonitor for the given @file,
5203 * or %NULL on error.
5204 * Free the returned object with g_object_unref().
5205 */
5206 GFileMonitor *
5208 GFileMonitorFlags flags,
5211 {
5223 {
5225 G_IO_ERROR_NOT_SUPPORTED,
5228 }
5231 }
5233 /**
5234 * g_file_monitor_file:
5235 * @file: input #GFile
5236 * @flags: a set of #GFileMonitorFlags
5237 * @cancellable: (allow-none): optional #GCancellable object,
5238 * %NULL to ignore
5239 * @error: a #GError, or %NULL
5240 *
5241 * Obtains a file monitor for the given file. If no file notification
5242 * mechanism exists, then regular polling of the file is used.
5243 *
5244 * If @cancellable is not %NULL, then the operation can be cancelled by
5245 * triggering the cancellable object from another thread. If the operation
5246 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5247 *
5248 * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
5249 * will also attempt to report changes made to the file via another
5250 * filename (ie, a hard link). Without this flag, you can only rely on
5251 * changes made through the filename contained in @file to be
5252 * reported. Using this flag may result in an increase in resource
5253 * usage, and may not have any effect depending on the #GFileMonitor
5254 * backend and/or filesystem type.
5255 *
5256 * Returns: (transfer full): a #GFileMonitor for the given @file,
5257 * or %NULL on error.
5258 * Free the returned object with g_object_unref().
5259 */
5260 GFileMonitor *
5262 GFileMonitorFlags flags,
5265 {
5281 /* Fallback to polling */
5286 }
5288 /**
5289 * g_file_monitor:
5290 * @file: input #GFile
5291 * @flags: a set of #GFileMonitorFlags
5292 * @cancellable: (allow-none): optional #GCancellable object,
5293 * %NULL to ignore
5294 * @error: a #GError, or %NULL
5295 *
5296 * Obtains a file or directory monitor for the given file,
5297 * depending on the type of the file.
5298 *
5299 * If @cancellable is not %NULL, then the operation can be cancelled by
5300 * triggering the cancellable object from another thread. If the operation
5301 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5302 *
5303 * Returns: (transfer full): a #GFileMonitor for the given @file,
5304 * or %NULL on error.
5305 * Free the returned object with g_object_unref().
5306 *
5307 * Since: 2.18
5308 */
5309 GFileMonitor *
5311 GFileMonitorFlags flags,
5314 {
5319 else
5321 }
5323 /********************************************
5324 * Default implementation of async ops *
5325 ********************************************/
5329 GFileQueryInfoFlags flags;
5332 static void
5334 {
5337 }
5339 static void
5341 gpointer object,
5342 gpointer task_data,
5344 {
5349 info = g_file_query_info (G_FILE (object), data->attributes, data->flags, cancellable, &error);
5352 else
5354 }
5356 static void
5359 GFileQueryInfoFlags flags,
5362 GAsyncReadyCallback callback,
5363 gpointer user_data)
5364 {
5377 }
5383 {
5387 }
5389 static void
5391 gpointer object,
5392 gpointer task_data,
5394 {
5402 else
5404 }
5406 static void
5411 GAsyncReadyCallback callback,
5412 gpointer user_data)
5413 {
5421 }
5427 {
5431 }
5433 static void
5435 gpointer object,
5436 gpointer task_data,
5438 {
5443 enumerator = g_file_enumerate_children (G_FILE (object), data->attributes, data->flags, cancellable, &error);
5446 else
5448 }
5450 static void
5453 GFileQueryInfoFlags flags,
5456 GAsyncReadyCallback callback,
5457 gpointer user_data)
5458 {
5471 }
5477 {
5481 }
5483 static void
5485 gpointer object,
5486 gpointer task_data,
5488 {
5495 else
5497 }
5499 static void
5503 GAsyncReadyCallback callback,
5504 gpointer user_data)
5505 {
5512 }
5518 {
5522 }
5524 static void
5526 gpointer source_object,
5527 gpointer task_data,
5529 {
5537 else
5539 }
5541 static void
5543 GFileCreateFlags flags,
5546 GAsyncReadyCallback callback,
5547 gpointer user_data)
5548 {
5561 }
5567 {
5571 }
5573 static void
5575 gpointer source_object,
5576 gpointer task_data,
5578 {
5586 else
5588 }
5590 static void
5592 GFileCreateFlags flags,
5595 GAsyncReadyCallback callback,
5596 gpointer user_data)
5597 {
5610 }
5616 {
5620 }
5625 gboolean make_backup;
5626 GFileCreateFlags flags;
5629 static void
5631 {
5636 }
5638 static void
5640 gpointer source_object,
5641 gpointer task_data,
5643 {
5652 cancellable,
5657 else
5659 }
5661 static void
5664 gboolean make_backup,
5665 GFileCreateFlags flags,
5668 GAsyncReadyCallback callback,
5669 gpointer user_data)
5670 {
5685 }
5691 {
5695 }
5697 static void
5699 gpointer object,
5700 gpointer task_data,
5702 {
5707 else
5709 }
5711 static void
5715 GAsyncReadyCallback callback,
5716 gpointer user_data)
5717 {
5724 }
5726 static gboolean
5730 {
5734 }
5736 static void
5738 gpointer object,
5739 gpointer task_data,
5741 {
5746 else
5748 }
5750 static void
5754 GAsyncReadyCallback callback,
5755 gpointer user_data)
5756 {
5763 }
5765 static gboolean
5769 {
5773 }
5775 static void
5777 gpointer object,
5778 gpointer task_data,
5780 {
5785 else
5787 }
5789 static void
5793 GAsyncReadyCallback callback,
5794 gpointer user_data)
5795 {
5802 }
5804 static gboolean
5808 {
5812 }
5814 static void
5816 gpointer object,
5817 gpointer task_data,
5819 {
5827 else
5829 }
5831 static void
5835 GAsyncReadyCallback callback,
5836 gpointer user_data)
5837 {
5845 }
5851 {
5855 }
5857 static void
5859 gpointer object,
5860 gpointer task_data,
5862 {
5871 else
5873 }
5875 static void
5877 GFileCreateFlags flags,
5880 GAsyncReadyCallback callback,
5881 gpointer user_data)
5882 {
5895 }
5901 {
5905 }
5909 gboolean make_backup;
5910 GFileCreateFlags flags;
5913 static void
5915 {
5918 }
5920 static void
5922 gpointer object,
5923 gpointer task_data,
5925 {
5934 cancellable,
5939 else
5941 }
5943 static void
5946 gboolean make_backup,
5947 GFileCreateFlags flags,
5950 GAsyncReadyCallback callback,
5951 gpointer user_data)
5952 {
5967 }
5973 {
5977 }
5979 static void
5981 gpointer object,
5982 gpointer task_data,
5984 {
5993 else
5995 }
5997 static void
6002 GAsyncReadyCallback callback,
6003 gpointer user_data)
6004 {
6013 }
6019 {
6023 }
6026 GFileQueryInfoFlags flags;
6028 gboolean res;
6032 static void
6034 {
6040 }
6042 static void
6044 gpointer object,
6045 gpointer task_data,
6047 {
6054 cancellable,
6056 }
6058 static void
6061 GFileQueryInfoFlags flags,
6064 GAsyncReadyCallback callback,
6065 gpointer user_data)
6066 {
6080 }
6082 static gboolean
6087 {
6101 }
6103 static void
6105 gpointer object,
6106 gpointer task_data,
6108 {
6116 else
6118 }
6120 static void
6124 GAsyncReadyCallback callback,
6125 gpointer user_data)
6126 {
6134 }
6140 {
6144 }
6150 GFileCopyFlags flags;
6151 GFileProgressCallback progress_cb;
6152 gpointer progress_cb_data;
6155 static void
6157 {
6161 }
6165 goffset current_num_bytes;
6166 goffset total_num_bytes;
6169 static gboolean
6171 {
6180 }
6182 static void
6184 goffset total_num_bytes,
6185 gpointer user_data)
6186 {
6198 copy_async_progress_in_main,
6199 progress,
6200 g_free);
6201 }
6203 static void
6205 gpointer source,
6206 gpointer task_data,
6208 {
6210 gboolean result;
6216 cancellable,
6218 task,
6222 else
6224 }
6226 static void
6229 GFileCopyFlags flags,
6232 GFileProgressCallback progress_callback,
6233 gpointer progress_callback_data,
6234 GAsyncReadyCallback callback,
6235 gpointer user_data)
6236 {
6252 }
6254 static gboolean
6258 {
6262 }
6265 /********************************************
6266 * Default VFS operations *
6267 ********************************************/
6269 /**
6270 * g_file_new_for_path:
6271 * @path: a string containing a relative or absolute path.
6272 * The string must be encoded in the glib filename encoding.
6273 *
6274 * Constructs a #GFile for a given path. This operation never
6275 * fails, but the returned object might not support any I/O
6276 * operation if @path is malformed.
6277 *
6278 * Returns: (transfer full): a new #GFile for the given @path.
6279 * Free the returned object with g_object_unref().
6280 */
6281 GFile *
6283 {
6287 }
6289 /**
6290 * g_file_new_for_uri:
6291 * @uri: a UTF-8 string containing a URI
6292 *
6293 * Constructs a #GFile for a given URI. This operation never
6294 * fails, but the returned object might not support any I/O
6295 * operation if @uri is malformed or if the uri type is
6296 * not supported.
6297 *
6298 * Returns: (transfer full): a new #GFile for the given @uri.
6299 * Free the returned object with g_object_unref().
6300 */
6301 GFile *
6303 {
6307 }
6309 /**
6310 * g_file_new_tmp:
6311 * @tmpl: (type filename) (allow-none): Template for the file
6312 * name, as in g_file_open_tmp(), or %NULL for a default template
6313 * @iostream: (out): on return, a #GFileIOStream for the created file
6314 * @error: a #GError, or %NULL
6315 *
6316 * Opens a file in the preferred directory for temporary files (as
6317 * returned by g_get_tmp_dir()) and returns a #GFile and
6318 * #GFileIOStream pointing to it.
6319 *
6320 * @tmpl should be a string in the GLib file name encoding
6321 * containing a sequence of six 'X' characters, and containing no
6322 * directory components. If it is %NULL, a default template is used.
6323 *
6324 * Unlike the other #GFile constructors, this will return %NULL if
6325 * a temporary file could not be created.
6326 *
6327 * Returns: (transfer full): a new #GFile.
6328 * Free the returned object with g_object_unref().
6329 *
6330 * Since: 2.32
6331 */
6332 GFile *
6336 {
6337 gint fd;
6357 }
6359 /**
6360 * g_file_parse_name:
6361 * @parse_name: a file name or path to be parsed
6362 *
6363 * Constructs a #GFile with the given @parse_name (i.e. something
6364 * given by g_file_get_parse_name()). This operation never fails,
6365 * but the returned object might not support any I/O operation if
6366 * the @parse_name cannot be parsed.
6367 *
6368 * Returns: (transfer full): a new #GFile.
6369 */
6370 GFile *
6372 {
6376 }
6378 static gboolean
6380 {
6382 }
6384 /* Following RFC 2396, valid schemes are built like:
6385 * scheme = alpha *( alpha | digit | "+" | "-" | "." )
6386 */
6387 static gboolean
6389 {
6398 p++;
6402 }
6407 {
6418 {
6424 }
6425 else
6432 }
6434 /**
6435 * g_file_new_for_commandline_arg:
6436 * @arg: a command line string
6437 *
6438 * Creates a #GFile with the given argument from the command line.
6439 * The value of @arg can be either a URI, an absolute path or a
6440 * relative path resolved relative to the current working directory.
6441 * This operation never fails, but the returned object might not
6442 * support any I/O operation if @arg points to a malformed path.
6443 *
6444 * Note that on Windows, this function expects its argument to be in
6445 * UTF-8 -- not the system code page. This means that you
6446 * should not use this function with string from argv as it is passed
6447 * to main(). g_win32_get_command_line() will return a UTF-8 version of
6448 * the commandline. #GApplication also uses UTF-8 but
6449 * g_application_command_line_create_file_for_arg() may be more useful
6450 * for you there. It is also always possible to use this function with
6451 * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
6452 *
6453 * Returns: (transfer full): a new #GFile.
6454 * Free the returned object with g_object_unref().
6455 */
6456 GFile *
6458 {
6462 }
6464 /**
6465 * g_file_new_for_commandline_arg_and_cwd:
6466 * @arg: a command line string
6467 * @cwd: the current working directory of the commandline
6468 *
6469 * Creates a #GFile with the given argument from the command line.
6470 *
6471 * This function is similar to g_file_new_for_commandline_arg() except
6472 * that it allows for passing the current working directory as an
6473 * argument instead of using the current working directory of the
6474 * process.
6475 *
6476 * This is useful if the commandline argument was given in a context
6477 * other than the invocation of the current process.
6478 *
6479 * See also g_application_command_line_create_file_for_arg().
6480 *
6481 * Returns: (transfer full): a new #GFile
6482 *
6483 * Since: 2.36
6484 **/
6485 GFile *
6488 {
6493 }
6495 /**
6496 * g_file_mount_enclosing_volume:
6497 * @location: input #GFile
6498 * @flags: flags affecting the operation
6499 * @mount_operation: (allow-none): a #GMountOperation
6500 * or %NULL to avoid user interaction
6501 * @cancellable: (allow-none): optional #GCancellable object,
6502 * %NULL to ignore
6503 * @callback: (allow-none): a #GAsyncReadyCallback to call
6504 * when the request is satisfied, or %NULL
6505 * @user_data: the data to pass to callback function
6506 *
6507 * Starts a @mount_operation, mounting the volume that contains
6508 * the file @location.
6509 *
6510 * When this operation has completed, @callback will be called with
6511 * @user_user data, and the operation can be finalized with
6512 * g_file_mount_enclosing_volume_finish().
6513 *
6514 * If @cancellable is not %NULL, then the operation can be cancelled by
6515 * triggering the cancellable object from another thread. If the operation
6516 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6517 */
6518 void
6520 GMountMountFlags flags,
6523 GAsyncReadyCallback callback,
6524 gpointer user_data)
6525 {
6533 {
6535 g_file_mount_enclosing_volume,
6539 }
6541 (* iface->mount_enclosing_volume) (location, flags, mount_operation, cancellable, callback, user_data);
6543 }
6545 /**
6546 * g_file_mount_enclosing_volume_finish:
6547 * @location: input #GFile
6548 * @result: a #GAsyncResult
6549 * @error: a #GError, or %NULL
6550 *
6551 * Finishes a mount operation started by g_file_mount_enclosing_volume().
6552 *
6553 * Returns: %TRUE if successful. If an error has occurred,
6554 * this function will return %FALSE and set @error
6555 * appropriately if present.
6556 */
6557 gboolean
6561 {
6575 }
6577 /********************************************
6578 * Utility functions *
6579 ********************************************/
6581 /**
6582 * g_file_query_default_handler:
6583 * @file: a #GFile to open
6584 * @cancellable: optional #GCancellable object, %NULL to ignore
6585 * @error: a #GError, or %NULL
6586 *
6587 * Returns the #GAppInfo that is registered as the default
6588 * application to handle the file specified by @file.
6589 *
6590 * If @cancellable is not %NULL, then the operation can be cancelled by
6591 * triggering the cancellable object from another thread. If the operation
6592 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6593 *
6594 * Returns: (transfer full): a #GAppInfo if the handle was found,
6595 * %NULL if there were errors.
6596 * When you are done with it, release it with g_object_unref()
6597 */
6598 GAppInfo *
6602 {
6611 {
6617 }
6620 G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE,
6622 cancellable,
6623 error);
6631 {
6632 /* Don't use is_native(), as we want to support fuse paths if available */
6637 }
6645 G_IO_ERROR_NOT_SUPPORTED,
6648 }
6650 #define GET_CONTENT_BLOCK_SIZE 8192
6652 /**
6653 * g_file_load_contents:
6654 * @file: input #GFile
6655 * @cancellable: optional #GCancellable object, %NULL to ignore
6656 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
6657 * @length: (out) (allow-none): a location to place the length of the contents of the file,
6658 * or %NULL if the length is not needed
6659 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
6660 * or %NULL if the entity tag is not needed
6661 * @error: a #GError, or %NULL
6662 *
6663 * Loads the content of the file into memory. The data is always
6664 * zero-terminated, but this is not included in the resultant @length.
6665 * The returned @content should be freed with g_free() when no longer
6666 * needed.
6667 *
6668 * If @cancellable is not %NULL, then the operation can be cancelled by
6669 * triggering the cancellable object from another thread. If the operation
6670 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6671 *
6672 * Returns: %TRUE if the @file's contents were successfully loaded.
6673 * %FALSE if there were errors.
6674 */
6675 gboolean
6682 {
6685 gsize pos;
6686 gssize res;
6702 GET_CONTENT_BLOCK_SIZE,
6704 {
6707 }
6710 {
6714 G_FILE_ATTRIBUTE_ETAG_VALUE,
6715 cancellable,
6716 NULL);
6718 {
6721 }
6722 }
6724 /* Ignore errors on close */
6729 {
6730 /* error is set already */
6733 }
6738 /* Zero terminate (we got an extra byte allocated for this */
6744 }
6748 GFileReadMoreCallback read_more_callback;
6750 gsize pos;
6755 static void
6757 {
6762 }
6764 static void
6767 gpointer user_data)
6768 {
6772 /* Ignore errors here, we're only reading anyway */
6778 }
6780 static void
6783 gpointer user_data)
6784 {
6792 {
6795 }
6800 }
6802 static void
6805 gpointer user_data)
6806 {
6810 gssize read_size;
6815 {
6819 /* Close the file ignoring any error */
6822 }
6824 {
6826 G_FILE_ATTRIBUTE_ETAG_VALUE,
6829 load_contents_fstat_callback,
6830 data);
6831 }
6833 {
6844 G_FILE_ATTRIBUTE_ETAG_VALUE,
6847 load_contents_fstat_callback,
6848 data);
6849 else
6852 GET_CONTENT_BLOCK_SIZE,
6855 load_contents_read_callback,
6856 data);
6857 }
6858 }
6860 static void
6863 gpointer user_data)
6864 {
6873 {
6878 GET_CONTENT_BLOCK_SIZE,
6881 load_contents_read_callback,
6882 data);
6883 }
6884 else
6885 {
6888 }
6889 }
6891 /**
6892 * g_file_load_partial_contents_async: (skip)
6893 * @file: input #GFile
6894 * @cancellable: optional #GCancellable object, %NULL to ignore
6895 * @read_more_callback: a #GFileReadMoreCallback to receive partial data
6896 * and to specify whether further data should be read
6897 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
6898 * @user_data: the data to pass to the callback functions
6899 *
6900 * Reads the partial contents of a file. A #GFileReadMoreCallback should
6901 * be used to stop reading from the file when appropriate, else this
6902 * function will behave exactly as g_file_load_contents_async(). This
6903 * operation can be finished by g_file_load_partial_contents_finish().
6904 *
6905 * Users of this function should be aware that @user_data is passed to
6906 * both the @read_more_callback and the @callback.
6907 *
6908 * If @cancellable is not %NULL, then the operation can be cancelled by
6909 * triggering the cancellable object from another thread. If the operation
6910 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6911 */
6912 void
6915 GFileReadMoreCallback read_more_callback,
6916 GAsyncReadyCallback callback,
6917 gpointer user_data)
6918 {
6933 load_contents_open_callback,
6934 data);
6935 }
6937 /**
6938 * g_file_load_partial_contents_finish:
6939 * @file: input #GFile
6940 * @res: a #GAsyncResult
6941 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
6942 * @length: (out) (allow-none): a location to place the length of the contents of the file,
6943 * or %NULL if the length is not needed
6944 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
6945 * or %NULL if the entity tag is not needed
6946 * @error: a #GError, or %NULL
6947 *
6948 * Finishes an asynchronous partial load operation that was started
6949 * with g_file_load_partial_contents_async(). The data is always
6950 * zero-terminated, but this is not included in the resultant @length.
6951 * The returned @content should be freed with g_free() when no longer
6952 * needed.
6953 *
6954 * Returns: %TRUE if the load was successful. If %FALSE and @error is
6955 * present, it will be set appropriately.
6956 */
6957 gboolean
6964 {
6975 {
6979 }
6987 {
6990 }
6992 /* Zero terminate */
7000 }
7002 /**
7003 * g_file_load_contents_async:
7004 * @file: input #GFile
7005 * @cancellable: optional #GCancellable object, %NULL to ignore
7006 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7007 * @user_data: the data to pass to callback function
7008 *
7009 * Starts an asynchronous load of the @file's contents.
7010 *
7011 * For more details, see g_file_load_contents() which is
7012 * the synchronous version of this call.
7013 *
7014 * When the load operation has completed, @callback will be called
7015 * with @user data. To finish the operation, call
7016 * g_file_load_contents_finish() with the #GAsyncResult returned by
7017 * the @callback.
7018 *
7019 * If @cancellable is not %NULL, then the operation can be cancelled by
7020 * triggering the cancellable object from another thread. If the operation
7021 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7022 */
7023 void
7026 GAsyncReadyCallback callback,
7027 gpointer user_data)
7028 {
7030 cancellable,
7031 NULL,
7033 }
7035 /**
7036 * g_file_load_contents_finish:
7037 * @file: input #GFile
7038 * @res: a #GAsyncResult
7039 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
7040 * @length: (out) (allow-none): a location to place the length of the contents of the file,
7041 * or %NULL if the length is not needed
7042 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
7043 * or %NULL if the entity tag is not needed
7044 * @error: a #GError, or %NULL
7045 *
7046 * Finishes an asynchronous load of the @file's contents.
7047 * The contents are placed in @contents, and @length is set to the
7048 * size of the @contents string. The @content should be freed with
7049 * g_free() when no longer needed. If @etag_out is present, it will be
7050 * set to the new entity tag for the @file.
7051 *
7052 * Returns: %TRUE if the load was successful. If %FALSE and @error is
7053 * present, it will be set appropriately.
7054 */
7055 gboolean
7062 {
7064 res,
7065 contents,
7066 length,
7067 etag_out,
7068 error);
7069 }
7071 /**
7072 * g_file_replace_contents:
7073 * @file: input #GFile
7074 * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
7075 * @length: the length of @contents in bytes
7076 * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document,
7077 * or %NULL
7078 * @make_backup: %TRUE if a backup should be created
7079 * @flags: a set of #GFileCreateFlags
7080 * @new_etag: (allow-none) (out): a location to a new [entity tag][gfile-etag]
7081 * for the document. This should be freed with g_free() when no longer
7082 * needed, or %NULL
7083 * @cancellable: optional #GCancellable object, %NULL to ignore
7084 * @error: a #GError, or %NULL
7085 *
7086 * Replaces the contents of @file with @contents of @length bytes.
7087 *
7088 * If @etag is specified (not %NULL), any existing file must have that etag,
7089 * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
7090 *
7091 * If @make_backup is %TRUE, this function will attempt to make a backup
7092 * of @file.
7093 *
7094 * If @cancellable is not %NULL, then the operation can be cancelled by
7095 * triggering the cancellable object from another thread. If the operation
7096 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7097 *
7098 * The returned @new_etag can be used to verify that the file hasn't
7099 * changed the next time it is saved over.
7100 *
7101 * Returns: %TRUE if successful. If an error has occurred, this function
7102 * will return %FALSE and set @error appropriately if present.
7103 */
7104 gboolean
7107 gsize length,
7109 gboolean make_backup,
7110 GFileCreateFlags flags,
7114 {
7117 gssize res;
7118 gboolean ret;
7133 cancellable,
7135 {
7138 }
7141 {
7142 /* Ignore errors on close */
7146 /* error is set already */
7148 }
7158 }
7163 gsize pos;
7165 gboolean failed;
7168 static void
7170 {
7174 }
7176 static void
7179 gpointer user_data)
7180 {
7184 /* Ignore errors here, we're only reading anyway */
7189 {
7192 }
7194 }
7196 static void
7199 gpointer user_data)
7200 {
7204 gssize write_size;
7209 {
7210 /* Error or EOF, close the file */
7212 {
7215 }
7219 }
7221 {
7223 gsize length;
7232 else
7238 replace_contents_write_callback,
7239 data);
7240 }
7241 }
7243 static void
7246 gpointer user_data)
7247 {
7256 {
7258 gsize length;
7266 replace_contents_write_callback,
7267 data);
7268 }
7269 else
7270 {
7273 }
7274 }
7276 /**
7277 * g_file_replace_contents_async:
7278 * @file: input #GFile
7279 * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
7280 * @length: the length of @contents in bytes
7281 * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
7282 * @make_backup: %TRUE if a backup should be created
7283 * @flags: a set of #GFileCreateFlags
7284 * @cancellable: optional #GCancellable object, %NULL to ignore
7285 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7286 * @user_data: the data to pass to callback function
7287 *
7288 * Starts an asynchronous replacement of @file with the given
7289 * @contents of @length bytes. @etag will replace the document's
7290 * current entity tag.
7291 *
7292 * When this operation has completed, @callback will be called with
7293 * @user_user data, and the operation can be finalized with
7294 * g_file_replace_contents_finish().
7295 *
7296 * If @cancellable is not %NULL, then the operation can be cancelled by
7297 * triggering the cancellable object from another thread. If the operation
7298 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7299 *
7300 * If @make_backup is %TRUE, this function will attempt to
7301 * make a backup of @file.
7302 *
7303 * Note that no copy of @content will be made, so it must stay valid
7304 * until @callback is called. See g_file_replace_contents_bytes_async()
7305 * for a #GBytes version that will automatically hold a reference to the
7306 * contents (without copying) for the duration of the call.
7307 */
7308 void
7311 gsize length,
7313 gboolean make_backup,
7314 GFileCreateFlags flags,
7316 GAsyncReadyCallback callback,
7317 gpointer user_data)
7318 {
7325 }
7327 /**
7328 * g_file_replace_contents_bytes_async:
7329 * @file: input #GFile
7330 * @contents: a #GBytes
7331 * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
7332 * @make_backup: %TRUE if a backup should be created
7333 * @flags: a set of #GFileCreateFlags
7334 * @cancellable: optional #GCancellable object, %NULL to ignore
7335 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7336 * @user_data: the data to pass to callback function
7337 *
7338 * Same as g_file_replace_contents_async() but takes a #GBytes input instead.
7339 * This function will keep a ref on @contents until the operation is done.
7340 * Unlike g_file_replace_contents_async() this allows forgetting about the
7341 * content without waiting for the callback.
7342 *
7343 * When this operation has completed, @callback will be called with
7344 * @user_user data, and the operation can be finalized with
7345 * g_file_replace_contents_finish().
7346 *
7347 * Since: 2.40
7348 */
7349 void
7353 gboolean make_backup,
7354 GFileCreateFlags flags,
7356 GAsyncReadyCallback callback,
7357 gpointer user_data)
7358 {
7372 etag,
7373 make_backup,
7374 flags,
7377 replace_contents_open_callback,
7378 data);
7379 }
7381 /**
7382 * g_file_replace_contents_finish:
7383 * @file: input #GFile
7384 * @res: a #GAsyncResult
7385 * @new_etag: (out) (allow-none): a location of a new [entity tag][gfile-etag]
7386 * for the document. This should be freed with g_free() when it is no
7387 * longer needed, or %NULL
7388 * @error: a #GError, or %NULL
7389 *
7390 * Finishes an asynchronous replace of the given @file. See
7391 * g_file_replace_contents_async(). Sets @new_etag to the new entity
7392 * tag for the document, if present.
7393 *
7394 * Returns: %TRUE on success, %FALSE on failure.
7395 */
7396 gboolean
7401 {
7416 {
7419 }
7422 }
7424 gboolean
7426 GFileMeasureFlags flags,
7428 GFileMeasureProgressCallback progress_callback,
7429 gpointer progress_data,
7434 {
7438 }
7441 {
7442 GFileMeasureFlags flags;
7443 GFileMeasureProgressCallback progress_callback;
7444 gpointer progress_data;
7448 {
7449 guint64 disk_usage;
7450 guint64 num_dirs;
7451 guint64 num_files;
7455 {
7456 GFileMeasureProgressCallback callback;
7457 gpointer user_data;
7458 gboolean reporting;
7459 guint64 current_size;
7460 guint64 num_dirs;
7461 guint64 num_files;
7464 static gboolean
7466 {
7474 }
7476 static void
7478 guint64 current_size,
7479 guint64 num_dirs,
7480 guint64 num_files,
7481 gpointer user_data)
7482 {
7483 MeasureProgress progress;
7498 measure_disk_usage_invoke_progress,
7500 g_free);
7501 }
7503 static void
7505 gpointer source_object,
7506 gpointer task_data,
7508 {
7511 MeasureResult result;
7518 else
7520 }
7522 static void
7524 GFileMeasureFlags flags,
7525 gint io_priority,
7527 GFileMeasureProgressCallback progress_callback,
7528 gpointer progress_data,
7529 GAsyncReadyCallback callback,
7530 gpointer user_data)
7531 {
7532 MeasureTaskData data;
7545 }
7547 static gboolean
7554 {
7576 }
7578 /**
7579 * g_file_measure_disk_usage:
7580 * @file: a #GFile
7581 * @flags: #GFileMeasureFlags
7582 * @cancellable: (allow-none): optional #GCancellable
7583 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
7584 * @progress_data: user_data for @progress_callback
7585 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
7586 * @num_dirs: (allow-none) (out): the number of directories encountered
7587 * @num_files: (allow-none) (out): the number of non-directories encountered
7588 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
7589 *
7590 * Recursively measures the disk usage of @file.
7591 *
7592 * This is essentially an analog of the 'du' command, but it also
7593 * reports the number of directories and non-directory files encountered
7594 * (including things like symbolic links).
7595 *
7596 * By default, errors are only reported against the toplevel file
7597 * itself. Errors found while recursing are silently ignored, unless
7598 * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
7599 *
7600 * The returned size, @disk_usage, is in bytes and should be formatted
7601 * with g_format_size() in order to get something reasonable for showing
7602 * in a user interface.
7603 *
7604 * @progress_callback and @progress_data can be given to request
7605 * periodic progress updates while scanning. See the documentation for
7606 * #GFileMeasureProgressCallback for information about when and how the
7607 * callback will be invoked.
7608 *
7609 * Returns: %TRUE if successful, with the out parameters set.
7610 * %FALSE otherwise, with @error set.
7611 *
7612 * Since: 2.38
7613 **/
7614 gboolean
7616 GFileMeasureFlags flags,
7618 GFileMeasureProgressCallback progress_callback,
7619 gpointer progress_data,
7624 {
7632 error);
7633 }
7635 /**
7636 * g_file_measure_disk_usage_async:
7637 * @file: a #GFile
7638 * @flags: #GFileMeasureFlags
7639 * @io_priority: the [I/O priority][io-priority] of the request
7640 * @cancellable: (allow-none): optional #GCancellable
7641 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
7642 * @progress_data: user_data for @progress_callback
7643 * @callback: (allow-none): a #GAsyncReadyCallback to call when complete
7644 * @user_data: the data to pass to callback function
7645 *
7646 * Recursively measures the disk usage of @file.
7647 *
7648 * This is the asynchronous version of g_file_measure_disk_usage(). See
7649 * there for more information.
7650 *
7651 * Since: 2.38
7652 **/
7653 void
7655 GFileMeasureFlags flags,
7656 gint io_priority,
7658 GFileMeasureProgressCallback progress_callback,
7659 gpointer progress_data,
7660 GAsyncReadyCallback callback,
7661 gpointer user_data)
7662 {
7669 }
7671 /**
7672 * g_file_measure_disk_usage_finish:
7673 * @file: a #GFile
7674 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
7675 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
7676 * @num_dirs: (allow-none) (out): the number of directories encountered
7677 * @num_files: (allow-none) (out): the number of non-directories encountered
7678 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
7679 *
7680 * Collects the results from an earlier call to
7681 * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for
7682 * more information.
7683 *
7684 * Returns: %TRUE if successful, with the out parameters set.
7685 * %FALSE otherwise, with @error set.
7686 *
7687 * Since: 2.38
7688 **/
7689 gboolean
7696 {
7700 return G_FILE_GET_IFACE (file)->measure_disk_usage_finish (file, result, disk_usage, num_dirs, num_files, error);
7701 }
7703 /**
7704 * g_file_start_mountable:
7705 * @file: input #GFile
7706 * @flags: flags affecting the operation
7707 * @start_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
7708 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
7709 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
7710 * @user_data: the data to pass to callback function
7711 *
7712 * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
7713 * Using @start_operation, you can request callbacks when, for instance,
7714 * passwords are needed during authentication.
7715 *
7716 * If @cancellable is not %NULL, then the operation can be cancelled by
7717 * triggering the cancellable object from another thread. If the operation
7718 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7719 *
7720 * When the operation is finished, @callback will be called.
7721 * You can then call g_file_mount_mountable_finish() to get
7722 * the result of the operation.
7723 *
7724 * Since: 2.22
7725 */
7726 void
7728 GDriveStartFlags flags,
7731 GAsyncReadyCallback callback,
7732 gpointer user_data)
7733 {
7741 {
7743 g_file_start_mountable,
7747 }
7750 flags,
7751 start_operation,
7752 cancellable,
7753 callback,
7754 user_data);
7755 }
7757 /**
7758 * g_file_start_mountable_finish:
7759 * @file: input #GFile
7760 * @result: a #GAsyncResult
7761 * @error: a #GError, or %NULL
7762 *
7763 * Finishes a start operation. See g_file_start_mountable() for details.
7764 *
7765 * Finish an asynchronous start operation that was started
7766 * with g_file_start_mountable().
7767 *
7768 * Returns: %TRUE if the operation finished successfully. %FALSE
7769 * otherwise.
7770 *
7771 * Since: 2.22
7772 */
7773 gboolean
7777 {
7790 }
7792 /**
7793 * g_file_stop_mountable:
7794 * @file: input #GFile
7795 * @flags: flags affecting the operation
7796 * @mount_operation: (allow-none): a #GMountOperation,
7797 * or %NULL to avoid user interaction.
7798 * @cancellable: (allow-none): optional #GCancellable object,
7799 * %NULL to ignore
7800 * @callback: (allow-none): a #GAsyncReadyCallback to call
7801 * when the request is satisfied, or %NULL
7802 * @user_data: the data to pass to callback function
7803 *
7804 * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
7805 *
7806 * If @cancellable is not %NULL, then the operation can be cancelled by
7807 * triggering the cancellable object from another thread. If the operation
7808 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7809 *
7810 * When the operation is finished, @callback will be called.
7811 * You can then call g_file_stop_mountable_finish() to get
7812 * the result of the operation.
7813 *
7814 * Since: 2.22
7815 */
7816 void
7818 GMountUnmountFlags flags,
7821 GAsyncReadyCallback callback,
7822 gpointer user_data)
7823 {
7831 {
7833 g_file_stop_mountable,
7837 }
7840 flags,
7841 mount_operation,
7842 cancellable,
7843 callback,
7844 user_data);
7845 }
7847 /**
7848 * g_file_stop_mountable_finish:
7849 * @file: input #GFile
7850 * @result: a #GAsyncResult
7851 * @error: a #GError, or %NULL
7852 *
7853 * Finishes an stop operation, see g_file_stop_mountable() for details.
7854 *
7855 * Finish an asynchronous stop operation that was started
7856 * with g_file_stop_mountable().
7857 *
7858 * Returns: %TRUE if the operation finished successfully.
7859 * %FALSE otherwise.
7860 *
7861 * Since: 2.22
7862 */
7863 gboolean
7867 {
7880 }
7882 /**
7883 * g_file_poll_mountable:
7884 * @file: input #GFile
7885 * @cancellable: optional #GCancellable object, %NULL to ignore
7886 * @callback: (allow-none): a #GAsyncReadyCallback to call
7887 * when the request is satisfied, or %NULL
7888 * @user_data: the data to pass to callback function
7889 *
7890 * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
7891 *
7892 * If @cancellable is not %NULL, then the operation can be cancelled by
7893 * triggering the cancellable object from another thread. If the operation
7894 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7895 *
7896 * When the operation is finished, @callback will be called.
7897 * You can then call g_file_mount_mountable_finish() to get
7898 * the result of the operation.
7899 *
7900 * Since: 2.22
7901 */
7902 void
7905 GAsyncReadyCallback callback,
7906 gpointer user_data)
7907 {
7915 {
7917 g_file_poll_mountable,
7921 }
7924 cancellable,
7925 callback,
7926 user_data);
7927 }
7929 /**
7930 * g_file_poll_mountable_finish:
7931 * @file: input #GFile
7932 * @result: a #GAsyncResult
7933 * @error: a #GError, or %NULL
7934 *
7935 * Finishes a poll operation. See g_file_poll_mountable() for details.
7936 *
7937 * Finish an asynchronous poll operation that was polled
7938 * with g_file_poll_mountable().
7939 *
7940 * Returns: %TRUE if the operation finished successfully. %FALSE
7941 * otherwise.
7942 *
7943 * Since: 2.22
7944 */
7945 gboolean
7949 {
7962 }
7964 /**
7965 * g_file_supports_thread_contexts:
7966 * @file: a #GFile
7967 *
7968 * Checks if @file supports
7969 * [thread-default contexts][g-main-context-push-thread-default-context].
7970 * If this returns %FALSE, you cannot perform asynchronous operations on
7971 * @file in a thread that has a thread-default context.
7972 *
7973 * Returns: Whether or not @file supports thread-default contexts.
7974 *
7975 * Since: 2.22
7976 */
7977 gboolean
7979 {
7986 }