gio/gfile.c

   1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
   2
   3 /* GIO - GLib Input, Output and Streaming Library
   4  *
   5  * Copyright (C) 2006-2007 Red Hat, Inc.
   6  *
   7  * SPDX-License-Identifier: LGPL-2.1-or-later
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2.1 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General
  20  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  21  *
  22  * Author: Alexander Larsson <alexl@redhat.com>
  23  */
  24
  25 #include "config.h"
  26
  27 #ifdef __linux__
  28 #include <sys/ioctl.h>
  29 #include <errno.h>
  30 /* See linux.git/fs/btrfs/ioctl.h */
  31 #define BTRFS_IOCTL_MAGIC 0x94
  32 #define BTRFS_IOC_CLONE _IOW(BTRFS_IOCTL_MAGIC, 9, int)
  33 #endif
  34
  35 #ifdef HAVE_SPLICE
  36 #include <sys/stat.h>
  37 #include <unistd.h>
  38 #include <fcntl.h>
  39 #include <errno.h>
  40
  41 /*
  42  * We duplicate the following Linux kernel header defines here so we can still
  43  * run at full speed on modern kernels in cases where an old toolchain was used
  44  * to build GLib. This is often done deliberately to allow shipping binaries
  45  * that need to run on a wide range of systems.
  46  */
  47 #ifndef F_SETPIPE_SZ
  48 #define F_SETPIPE_SZ 1031
  49 #endif
  50 #ifndef F_GETPIPE_SZ
  51 #define F_GETPIPE_SZ 1032
  52 #endif
  53
  54 #endif
  55
  56 #include <string.h>
  57 #include <sys/types.h>
  58
  59 #include "gfile.h"
  60 #include "glib/gstdio.h"
  61 #ifdef G_OS_UNIX
  62 #include "glib-unix.h"
  63 #endif
  64 #include "gvfs.h"
  65 #include "gtask.h"
  66 #include "gfileattribute-priv.h"
  67 #include "gfiledescriptorbased.h"
  68 #include "gpollfilemonitor.h"
  69 #include "gappinfo.h"
  70 #include "gfileinputstream.h"
  71 #include "gfileoutputstream.h"
  72 #include "glocalfileoutputstream.h"
  73 #include "glocalfileiostream.h"
  74 #include "glocalfile.h"
  75 #include "gcancellable.h"
  76 #include "gasyncresult.h"
  77 #include "gioerror.h"
  78 #include "glibintl.h"
  79
  80 /* Linux defines loff_t as a way to simplify the offset types for calls like
  81  * splice() and copy_file_range(). BSD has copy_file_range() but doesn’t define
  82  * loff_t. Abstract that. */
  83 #ifndef HAVE_LOFF_T
  84 typedef off_t loff_t;
  85 #endif
  86
  87
  88 /**
  89  * SECTION:gfile
  90  * @short_description: File and Directory Handling
  91  * @include: gio/gio.h
  92  * @see_also: #GFileInfo, #GFileEnumerator
  93  *
  94  * #GFile is a high level abstraction for manipulating files on a
  95  * virtual file system. #GFiles are lightweight, immutable objects
  96  * that do no I/O upon creation. It is necessary to understand that
  97  * #GFile objects do not represent files, merely an identifier for a
  98  * file. All file content I/O is implemented as streaming operations
  99  * (see #GInputStream and #GOutputStream).
 100  *
 101  * To construct a #GFile, you can use:
 102  * - g_file_new_for_path() if you have a path.
 103  * - g_file_new_for_uri() if you have a URI.
 104  * - g_file_new_for_commandline_arg() for a command line argument.
 105  * - g_file_new_tmp() to create a temporary file from a template.
 106  * - g_file_new_tmp_async() to asynchronously create a temporary file.
 107  * - g_file_new_tmp_dir_async() to asynchronously create a temporary directory.
 108  * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
 109  * - g_file_new_build_filename() or g_file_new_build_filenamev() to create a file from path elements.
 110  *
 111  * One way to think of a #GFile is as an abstraction of a pathname. For
 112  * normal files the system pathname is what is stored internally, but as
 113  * #GFiles are extensible it could also be something else that corresponds
 114  * to a pathname in a userspace implementation of a filesystem.
 115  *
 116  * #GFiles make up hierarchies of directories and files that correspond to
 117  * the files on a filesystem. You can move through the file system with
 118  * #GFile using g_file_get_parent() to get an identifier for the parent
 119  * directory, g_file_get_child() to get a child within a directory,
 120  * g_file_resolve_relative_path() to resolve a relative path between two
 121  * #GFiles. There can be multiple hierarchies, so you may not end up at
 122  * the same root if you repeatedly call g_file_get_parent() on two different
 123  * files.
 124  *
 125  * All #GFiles have a basename (get with g_file_get_basename()). These names
 126  * are byte strings that are used to identify the file on the filesystem
 127  * (relative to its parent directory) and there is no guarantees that they
 128  * have any particular charset encoding or even make any sense at all. If
 129  * you want to use filenames in a user interface you should use the display
 130  * name that you can get by requesting the
 131  * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
 132  * This is guaranteed to be in UTF-8 and can be used in a user interface.
 133  * But always store the real basename or the #GFile to use to actually
 134  * access the file, because there is no way to go from a display name to
 135  * the actual name.
 136  *
 137  * Using #GFile as an identifier has the same weaknesses as using a path
 138  * in that there may be multiple aliases for the same file. For instance,
 139  * hard or soft links may cause two different #GFiles to refer to the same
 140  * file. Other possible causes for aliases are: case insensitive filesystems,
 141  * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
 142  * check if two #GFiles point to the same file you can query for the
 143  * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
 144  * canonicalization of pathnames passed in, so that trivial differences in
 145  * the path string used at creation (duplicated slashes, slash at end of
 146  * path, "." or ".." path segments, etc) does not create different #GFiles.
 147  *
 148  * Many #GFile operations have both synchronous and asynchronous versions
 149  * to suit your application. Asynchronous versions of synchronous functions
 150  * simply have _async() appended to their function names. The asynchronous
 151  * I/O functions call a #GAsyncReadyCallback which is then used to finalize
 152  * the operation, producing a GAsyncResult which is then passed to the
 153  * function's matching _finish() operation.
 154  *
 155  * It is highly recommended to use asynchronous calls when running within a
 156  * shared main loop, such as in the main thread of an application. This avoids
 157  * I/O operations blocking other sources on the main loop from being dispatched.
 158  * Synchronous I/O operations should be performed from worker threads. See the
 159  * [introduction to asynchronous programming section][async-programming] for
 160  * more.
 161  *
 162  * Some #GFile operations almost always take a noticeable amount of time, and
 163  * so do not have synchronous analogs. Notable cases include:
 164  * - g_file_mount_mountable() to mount a mountable file.
 165  * - g_file_unmount_mountable_with_operation() to unmount a mountable file.
 166  * - g_file_eject_mountable_with_operation() to eject a mountable file.
 167  *
 168  * ## Entity Tags # {#gfile-etag}
 169  *
 170  * One notable feature of #GFiles are entity tags, or "etags" for
 171  * short. Entity tags are somewhat like a more abstract version of the
 172  * traditional mtime, and can be used to quickly determine if the file
 173  * has been modified from the version on the file system. See the
 174  * HTTP 1.1
 175  * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
 176  * for HTTP Etag headers, which are a very similar concept.
 177  */
 178
 179 static void               g_file_real_query_info_async            (GFile                  *file,
 180                                                                    const char             *attributes,
 181                                                                    GFileQueryInfoFlags     flags,
 182                                                                    int                     io_priority,
 183                                                                    GCancellable           *cancellable,
 184                                                                    GAsyncReadyCallback     callback,
 185                                                                    gpointer                user_data);
 186 static GFileInfo *        g_file_real_query_info_finish           (GFile                  *file,
 187                                                                    GAsyncResult           *res,
 188                                                                    GError                **error);
 189 static void               g_file_real_query_filesystem_info_async (GFile                  *file,
 190                                                                    const char             *attributes,
 191                                                                    int                     io_priority,
 192                                                                    GCancellable           *cancellable,
 193                                                                    GAsyncReadyCallback     callback,
 194                                                                    gpointer                user_data);
 195 static GFileInfo *        g_file_real_query_filesystem_info_finish (GFile                  *file,
 196                                                                    GAsyncResult           *res,
 197                                                                    GError                **error);
 198 static void               g_file_real_enumerate_children_async    (GFile                  *file,
 199                                                                    const char             *attributes,
 200                                                                    GFileQueryInfoFlags     flags,
 201                                                                    int                     io_priority,
 202                                                                    GCancellable           *cancellable,
 203                                                                    GAsyncReadyCallback     callback,
 204                                                                    gpointer                user_data);
 205 static GFileEnumerator *  g_file_real_enumerate_children_finish   (GFile                  *file,
 206                                                                    GAsyncResult           *res,
 207                                                                    GError                **error);
 208 static void               g_file_real_read_async                  (GFile                  *file,
 209                                                                    int                     io_priority,
 210                                                                    GCancellable           *cancellable,
 211                                                                    GAsyncReadyCallback     callback,
 212                                                                    gpointer                user_data);
 213 static GFileInputStream * g_file_real_read_finish                 (GFile                  *file,
 214                                                                    GAsyncResult           *res,
 215                                                                    GError                **error);
 216 static void               g_file_real_append_to_async             (GFile                  *file,
 217                                                                    GFileCreateFlags        flags,
 218                                                                    int                     io_priority,
 219                                                                    GCancellable           *cancellable,
 220                                                                    GAsyncReadyCallback     callback,
 221                                                                    gpointer                user_data);
 222 static GFileOutputStream *g_file_real_append_to_finish            (GFile                  *file,
 223                                                                    GAsyncResult           *res,
 224                                                                    GError                **error);
 225 static void               g_file_real_create_async                (GFile                  *file,
 226                                                                    GFileCreateFlags        flags,
 227                                                                    int                     io_priority,
 228                                                                    GCancellable           *cancellable,
 229                                                                    GAsyncReadyCallback     callback,
 230                                                                    gpointer                user_data);
 231 static GFileOutputStream *g_file_real_create_finish               (GFile                  *file,
 232                                                                    GAsyncResult           *res,
 233                                                                    GError                **error);
 234 static void               g_file_real_replace_async               (GFile                  *file,
 235                                                                    const char             *etag,
 236                                                                    gboolean                make_backup,
 237                                                                    GFileCreateFlags        flags,
 238                                                                    int                     io_priority,
 239                                                                    GCancellable           *cancellable,
 240                                                                    GAsyncReadyCallback     callback,
 241                                                                    gpointer                user_data);
 242 static GFileOutputStream *g_file_real_replace_finish              (GFile                  *file,
 243                                                                    GAsyncResult           *res,
 244                                                                    GError                **error);
 245 static void               g_file_real_delete_async                (GFile                  *file,
 246                                                                    int                     io_priority,
 247                                                                    GCancellable           *cancellable,
 248                                                                    GAsyncReadyCallback     callback,
 249                                                                    gpointer                user_data);
 250 static gboolean           g_file_real_delete_finish               (GFile                  *file,
 251                                                                    GAsyncResult           *res,
 252                                                                    GError                **error);
 253 static void               g_file_real_trash_async                 (GFile                  *file,
 254                                                                    int                     io_priority,
 255                                                                    GCancellable           *cancellable,
 256                                                                    GAsyncReadyCallback     callback,
 257                                                                    gpointer                user_data);
 258 static gboolean           g_file_real_trash_finish                (GFile                  *file,
 259                                                                    GAsyncResult           *res,
 260                                                                    GError                **error);
 261 static void               g_file_real_move_async                  (GFile                  *source,
 262                                                                    GFile                  *destination,
 263                                                                    GFileCopyFlags          flags,
 264                                                                    int                     io_priority,
 265                                                                    GCancellable           *cancellable,
 266                                                                    GFileProgressCallback   progress_callback,
 267                                                                    gpointer                progress_callback_data,
 268                                                                    GAsyncReadyCallback     callback,
 269                                                                    gpointer                user_data);
 270 static gboolean           g_file_real_move_finish                 (GFile                  *file,
 271                                                                    GAsyncResult           *result,
 272                                                                    GError                **error);
 273 static void               g_file_real_make_directory_async        (GFile                  *file,
 274                                                                    int                     io_priority,
 275                                                                    GCancellable           *cancellable,
 276                                                                    GAsyncReadyCallback     callback,
 277                                                                    gpointer                user_data);
 278 static gboolean           g_file_real_make_directory_finish       (GFile                  *file,
 279                                                                    GAsyncResult           *res,
 280                                                                    GError                **error);
 281 static void               g_file_real_make_symbolic_link_async    (GFile                  *file,
 282                                                                    const char             *symlink_value,
 283                                                                    int                     io_priority,
 284                                                                    GCancellable           *cancellable,
 285                                                                    GAsyncReadyCallback     callback,
 286                                                                    gpointer                user_data);
 287 static gboolean           g_file_real_make_symbolic_link_finish   (GFile                  *file,
 288                                                                    GAsyncResult           *result,
 289                                                                    GError                **error);
 290 static void               g_file_real_open_readwrite_async        (GFile                  *file,
 291                                                                    int                  io_priority,
 292                                                                    GCancellable           *cancellable,
 293                                                                    GAsyncReadyCallback     callback,
 294                                                                    gpointer                user_data);
 295 static GFileIOStream *    g_file_real_open_readwrite_finish       (GFile                  *file,
 296                                                                    GAsyncResult           *res,
 297                                                                    GError                **error);
 298 static void               g_file_real_create_readwrite_async      (GFile                  *file,
 299                                                                    GFileCreateFlags        flags,
 300                                                                    int                     io_priority,
 301                                                                    GCancellable           *cancellable,
 302                                                                    GAsyncReadyCallback     callback,
 303                                                                    gpointer                user_data);
 304 static GFileIOStream *    g_file_real_create_readwrite_finish     (GFile                  *file,
 305                                                                    GAsyncResult           *res,
 306                                                                    GError                **error);
 307 static void               g_file_real_replace_readwrite_async     (GFile                  *file,
 308                                                                    const char             *etag,
 309                                                                    gboolean                make_backup,
 310                                                                    GFileCreateFlags        flags,
 311                                                                    int                     io_priority,
 312                                                                    GCancellable           *cancellable,
 313                                                                    GAsyncReadyCallback     callback,
 314                                                                    gpointer                user_data);
 315 static GFileIOStream *    g_file_real_replace_readwrite_finish    (GFile                  *file,
 316                                                                   GAsyncResult            *res,
 317                                                                   GError                 **error);
 318 static gboolean           g_file_real_set_attributes_from_info    (GFile                  *file,
 319                                                                    GFileInfo              *info,
 320                                                                    GFileQueryInfoFlags     flags,
 321                                                                    GCancellable           *cancellable,
 322                                                                    GError                **error);
 323 static void               g_file_real_set_display_name_async      (GFile                  *file,
 324                                                                    const char             *display_name,
 325                                                                    int                     io_priority,
 326                                                                    GCancellable           *cancellable,
 327                                                                    GAsyncReadyCallback     callback,
 328                                                                    gpointer                user_data);
 329 static GFile *            g_file_real_set_display_name_finish     (GFile                  *file,
 330                                                                    GAsyncResult           *res,
 331                                                                    GError                **error);
 332 static void               g_file_real_set_attributes_async        (GFile                  *file,
 333                                                                    GFileInfo              *info,
 334                                                                    GFileQueryInfoFlags     flags,
 335                                                                    int                     io_priority,
 336                                                                    GCancellable           *cancellable,
 337                                                                    GAsyncReadyCallback     callback,
 338                                                                    gpointer                user_data);
 339 static gboolean           g_file_real_set_attributes_finish       (GFile                  *file,
 340                                                                    GAsyncResult           *res,
 341                                                                    GFileInfo             **info,
 342                                                                    GError                **error);
 343 static void               g_file_real_find_enclosing_mount_async  (GFile                  *file,
 344                                                                    int                     io_priority,
 345                                                                    GCancellable           *cancellable,
 346                                                                    GAsyncReadyCallback     callback,
 347                                                                    gpointer                user_data);
 348 static GMount *           g_file_real_find_enclosing_mount_finish (GFile                  *file,
 349                                                                    GAsyncResult           *res,
 350                                                                    GError                **error);
 351 static void               g_file_real_copy_async                  (GFile                  *source,
 352                                                                    GFile                  *destination,
 353                                                                    GFileCopyFlags          flags,
 354                                                                    int                     io_priority,
 355                                                                    GCancellable           *cancellable,
 356                                                                    GFileProgressCallback   progress_callback,
 357                                                                    gpointer                progress_callback_data,
 358                                                                    GAsyncReadyCallback     callback,
 359                                                                    gpointer                user_data);
 360 static gboolean           g_file_real_copy_finish                 (GFile                  *file,
 361                                                                    GAsyncResult           *res,
 362                                                                    GError                **error);
 363
 364 static gboolean           g_file_real_measure_disk_usage          (GFile                         *file,
 365                                                                    GFileMeasureFlags              flags,
 366                                                                    GCancellable                  *cancellable,
 367                                                                    GFileMeasureProgressCallback   progress_callback,
 368                                                                    gpointer                       progress_data,
 369                                                                    guint64                       *disk_usage,
 370                                                                    guint64                       *num_dirs,
 371                                                                    guint64                       *num_files,
 372                                                                    GError                       **error);
 373 static void               g_file_real_measure_disk_usage_async    (GFile                         *file,
 374                                                                    GFileMeasureFlags              flags,
 375                                                                    gint                           io_priority,
 376                                                                    GCancellable                  *cancellable,
 377                                                                    GFileMeasureProgressCallback   progress_callback,
 378                                                                    gpointer                       progress_data,
 379                                                                    GAsyncReadyCallback            callback,
 380                                                                    gpointer                       user_data);
 381 static gboolean           g_file_real_measure_disk_usage_finish   (GFile                         *file,
 382                                                                    GAsyncResult                  *result,
 383                                                                    guint64                       *disk_usage,
 384                                                                    guint64                       *num_dirs,
 385                                                                    guint64                       *num_files,
 386                                                                    GError                       **error);
 387
 388 typedef GFileIface GFileInterface;
 389 G_DEFINE_INTERFACE (GFile, g_file, G_TYPE_OBJECT)
 390
 391 static void
 392 g_file_default_init (GFileIface *iface)
 393 {
 394   iface->enumerate_children_async = g_file_real_enumerate_children_async;
 395   iface->enumerate_children_finish = g_file_real_enumerate_children_finish;
 396   iface->set_display_name_async = g_file_real_set_display_name_async;
 397   iface->set_display_name_finish = g_file_real_set_display_name_finish;
 398   iface->query_info_async = g_file_real_query_info_async;
 399   iface->query_info_finish = g_file_real_query_info_finish;
 400   iface->query_filesystem_info_async = g_file_real_query_filesystem_info_async;
 401   iface->query_filesystem_info_finish = g_file_real_query_filesystem_info_finish;
 402   iface->set_attributes_async = g_file_real_set_attributes_async;
 403   iface->set_attributes_finish = g_file_real_set_attributes_finish;
 404   iface->read_async = g_file_real_read_async;
 405   iface->read_finish = g_file_real_read_finish;
 406   iface->append_to_async = g_file_real_append_to_async;
 407   iface->append_to_finish = g_file_real_append_to_finish;
 408   iface->create_async = g_file_real_create_async;
 409   iface->create_finish = g_file_real_create_finish;
 410   iface->replace_async = g_file_real_replace_async;
 411   iface->replace_finish = g_file_real_replace_finish;
 412   iface->delete_file_async = g_file_real_delete_async;
 413   iface->delete_file_finish = g_file_real_delete_finish;
 414   iface->trash_async = g_file_real_trash_async;
 415   iface->trash_finish = g_file_real_trash_finish;
 416   iface->move_async = g_file_real_move_async;
 417   iface->move_finish = g_file_real_move_finish;
 418   iface->make_directory_async = g_file_real_make_directory_async;
 419   iface->make_directory_finish = g_file_real_make_directory_finish;
 420   iface->make_symbolic_link_async = g_file_real_make_symbolic_link_async;
 421   iface->make_symbolic_link_finish = g_file_real_make_symbolic_link_finish;
 422   iface->open_readwrite_async = g_file_real_open_readwrite_async;
 423   iface->open_readwrite_finish = g_file_real_open_readwrite_finish;
 424   iface->create_readwrite_async = g_file_real_create_readwrite_async;
 425   iface->create_readwrite_finish = g_file_real_create_readwrite_finish;
 426   iface->replace_readwrite_async = g_file_real_replace_readwrite_async;
 427   iface->replace_readwrite_finish = g_file_real_replace_readwrite_finish;
 428   iface->find_enclosing_mount_async = g_file_real_find_enclosing_mount_async;
 429   iface->find_enclosing_mount_finish = g_file_real_find_enclosing_mount_finish;
 430   iface->set_attributes_from_info = g_file_real_set_attributes_from_info;
 431   iface->copy_async = g_file_real_copy_async;
 432   iface->copy_finish = g_file_real_copy_finish;
 433   iface->measure_disk_usage = g_file_real_measure_disk_usage;
 434   iface->measure_disk_usage_async = g_file_real_measure_disk_usage_async;
 435   iface->measure_disk_usage_finish = g_file_real_measure_disk_usage_finish;
 436 }
 437
 438
 439 /**
 440  * g_file_is_native:
 441  * @file: input #GFile
 442  *
 443  * Checks to see if a file is native to the platform.
 444  *
 445  * A native file is one expressed in the platform-native filename format,
 446  * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
 447  * as it might be on a locally mounted remote filesystem.
 448  *
 449  * On some systems non-native files may be available using the native
 450  * filesystem via a userspace filesystem (FUSE), in these cases this call
 451  * will return %FALSE, but g_file_get_path() will still return a native path.
 452  *
 453  * This call does no blocking I/O.
 454  *
 455  * Returns: %TRUE if @file is native
 456  */
 457 gboolean
 458 g_file_is_native (GFile *file)
 459 {
 460   GFileIface *iface;
 461
 462   g_return_val_if_fail (G_IS_FILE (file), FALSE);
 463
 464   iface = G_FILE_GET_IFACE (file);
 465
 466   return (* iface->is_native) (file);
 467 }
 468
 469
 470 /**
 471  * g_file_has_uri_scheme:
 472  * @file: input #GFile
 473  * @uri_scheme: a string containing a URI scheme
 474  *
 475  * Checks to see if a #GFile has a given URI scheme.
 476  *
 477  * This call does no blocking I/O.
 478  *
 479  * Returns: %TRUE if #GFile's backend supports the
 480  *   given URI scheme, %FALSE if URI scheme is %NULL,
 481  *   not supported, or #GFile is invalid.
 482  */
 483 gboolean
 484 g_file_has_uri_scheme (GFile      *file,
 485                        const char *uri_scheme)
 486 {
 487   GFileIface *iface;
 488
 489   g_return_val_if_fail (G_IS_FILE (file), FALSE);
 490   g_return_val_if_fail (uri_scheme != NULL, FALSE);
 491
 492   iface = G_FILE_GET_IFACE (file);
 493
 494   return (* iface->has_uri_scheme) (file, uri_scheme);
 495 }
 496
 497
 498 /**
 499  * g_file_get_uri_scheme:
 500  * @file: input #GFile
 501  *
 502  * Gets the URI scheme for a #GFile.
 503  * RFC 3986 decodes the scheme as:
 504  * |[
 505  * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
 506  * ]|
 507  * Common schemes include "file", "http", "ftp", etc.
 508  *
 509  * The scheme can be different from the one used to construct the #GFile,
 510  * in that it might be replaced with one that is logically equivalent to the #GFile.
 511  *
 512  * This call does no blocking I/O.
 513  *
 514  * Returns: (nullable): a string containing the URI scheme for the given
 515  *   #GFile or %NULL if the #GFile was constructed with an invalid URI. The
 516  *   returned string should be freed with g_free() when no longer needed.
 517  */
 518 char *
 519 g_file_get_uri_scheme (GFile *file)
 520 {
 521   GFileIface *iface;
 522
 523   g_return_val_if_fail (G_IS_FILE (file), NULL);
 524
 525   iface = G_FILE_GET_IFACE (file);
 526
 527   return (* iface->get_uri_scheme) (file);
 528 }
 529
 530
 531 /**
 532  * g_file_get_basename: (virtual get_basename)
 533  * @file: input #GFile
 534  *
 535  * Gets the base name (the last component of the path) for a given #GFile.
 536  *
 537  * If called for the top level of a system (such as the filesystem root
 538  * or a uri like sftp://host/) it will return a single directory separator
 539  * (and on Windows, possibly a drive letter).
 540  *
 541  * The base name is a byte string (not UTF-8). It has no defined encoding
 542  * or rules other than it may not contain zero bytes.  If you want to use
 543  * filenames in a user interface you should use the display name that you
 544  * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
 545  * attribute with g_file_query_info().
 546  *
 547  * This call does no blocking I/O.
 548  *
 549  * Returns: (type filename) (nullable): string containing the #GFile's
 550  *   base name, or %NULL if given #GFile is invalid. The returned string
 551  *   should be freed with g_free() when no longer needed.
 552  */
 553 char *
 554 g_file_get_basename (GFile *file)
 555 {
 556   GFileIface *iface;
 557
 558   g_return_val_if_fail (G_IS_FILE (file), NULL);
 559
 560   iface = G_FILE_GET_IFACE (file);
 561
 562   return (* iface->get_basename) (file);
 563 }
 564
 565 /**
 566  * g_file_get_path: (virtual get_path)
 567  * @file: input #GFile
 568  *
 569  * Gets the local pathname for #GFile, if one exists. If non-%NULL, this is
 570  * guaranteed to be an absolute, canonical path. It might contain symlinks.
 571  *
 572  * This call does no blocking I/O.
 573  *
 574  * Returns: (type filename) (nullable): string containing the #GFile's path,
 575  *   or %NULL if no such path exists. The returned string should be freed
 576  *   with g_free() when no longer needed.
 577  */
 578 char *
 579 g_file_get_path (GFile *file)
 580 {
 581   GFileIface *iface;
 582
 583   g_return_val_if_fail (G_IS_FILE (file), NULL);
 584
 585   iface = G_FILE_GET_IFACE (file);
 586
 587   return (* iface->get_path) (file);
 588 }
 589
 590 static const char *
 591 file_peek_path_generic (GFile *file)
 592 {
 593   const char *path;
 594   static GQuark _file_path_quark = 0;
 595
 596   if (G_UNLIKELY (_file_path_quark) == 0)
 597     _file_path_quark = g_quark_from_static_string ("gio-file-path");
 598
 599   /* We need to be careful about threading, as two threads calling
 600    * g_file_peek_path() on the same file could race: both would see
 601    * (g_object_get_qdata(…) == NULL) to begin with, both would generate and add
 602    * the path, but the second thread to add it would end up freeing the path
 603    * set by the first thread. The first thread would still return the pointer
 604    * to that freed path, though, resulting an a read-after-free. Handle that
 605    * with a compare-and-swap loop. The g_object_*_qdata() functions are atomic. */
 606
 607   while (TRUE)
 608     {
 609       gchar *new_path = NULL;
 610
 611       path = g_object_get_qdata ((GObject*)file, _file_path_quark);
 612
 613       if (path != NULL)
 614         break;
 615
 616       new_path = g_file_get_path (file);
 617       if (new_path == NULL)
 618         return NULL;
 619
 620       /* By passing NULL here, we ensure we never replace existing data: */
 621       if (g_object_replace_qdata ((GObject *) file, _file_path_quark,
 622                                   NULL, (gpointer) new_path,
 623                                   (GDestroyNotify) g_free, NULL))
 624         {
 625           path = new_path;
 626           break;
 627         }
 628       else
 629         g_free (new_path);
 630     }
 631
 632   return path;
 633 }
 634
 635 /**
 636  * g_file_peek_path:
 637  * @file: input #GFile
 638  *
 639  * Exactly like g_file_get_path(), but caches the result via
 640  * g_object_set_qdata_full().  This is useful for example in C
 641  * applications which mix `g_file_*` APIs with native ones.  It
 642  * also avoids an extra duplicated string when possible, so will be
 643  * generally more efficient.
 644  *
 645  * This call does no blocking I/O.
 646  *
 647  * Returns: (type filename) (nullable): string containing the #GFile's path,
 648  *   or %NULL if no such path exists. The returned string is owned by @file.
 649  * Since: 2.56
 650  */
 651 const char *
 652 g_file_peek_path (GFile *file)
 653 {
 654   if (G_IS_LOCAL_FILE (file))
 655     return _g_local_file_get_filename ((GLocalFile *) file);
 656   return file_peek_path_generic (file);
 657 }
 658
 659 /**
 660  * g_file_get_uri:
 661  * @file: input #GFile
 662  *
 663  * Gets the URI for the @file.
 664  *
 665  * This call does no blocking I/O.
 666  *
 667  * Returns: a string containing the #GFile's URI. If the #GFile was constructed
 668  *   with an invalid URI, an invalid URI is returned.
 669  *   The returned string should be freed with g_free()
 670  *   when no longer needed.
 671  */
 672 char *
 673 g_file_get_uri (GFile *file)
 674 {
 675   GFileIface *iface;
 676
 677   g_return_val_if_fail (G_IS_FILE (file), NULL);
 678
 679   iface = G_FILE_GET_IFACE (file);
 680
 681   return (* iface->get_uri) (file);
 682 }
 683
 684 /**
 685  * g_file_get_parse_name:
 686  * @file: input #GFile
 687  *
 688  * Gets the parse name of the @file.
 689  * A parse name is a UTF-8 string that describes the
 690  * file such that one can get the #GFile back using
 691  * g_file_parse_name().
 692  *
 693  * This is generally used to show the #GFile as a nice
 694  * full-pathname kind of string in a user interface,
 695  * like in a location entry.
 696  *
 697  * For local files with names that can safely be converted
 698  * to UTF-8 the pathname is used, otherwise the IRI is used
 699  * (a form of URI that allows UTF-8 characters unescaped).
 700  *
 701  * This call does no blocking I/O.
 702  *
 703  * Returns: a string containing the #GFile's parse name.
 704  *   The returned string should be freed with g_free()
 705  *   when no longer needed.
 706  */
 707 char *
 708 g_file_get_parse_name (GFile *file)
 709 {
 710   GFileIface *iface;
 711
 712   g_return_val_if_fail (G_IS_FILE (file), NULL);
 713
 714   iface = G_FILE_GET_IFACE (file);
 715
 716   return (* iface->get_parse_name) (file);
 717 }
 718
 719 /**
 720  * g_file_dup:
 721  * @file: input #GFile
 722  *
 723  * Duplicates a #GFile handle. This operation does not duplicate
 724  * the actual file or directory represented by the #GFile; see
 725  * g_file_copy() if attempting to copy a file.
 726  *
 727  * g_file_dup() is useful when a second handle is needed to the same underlying
 728  * file, for use in a separate thread (#GFile is not thread-safe). For use
 729  * within the same thread, use g_object_ref() to increment the existing object’s
 730  * reference count.
 731  *
 732  * This call does no blocking I/O.
 733  *
 734  * Returns: (transfer full): a new #GFile that is a duplicate
 735  *   of the given #GFile.
 736  */
 737 GFile *
 738 g_file_dup (GFile *file)
 739 {
 740   GFileIface *iface;
 741
 742   g_return_val_if_fail (G_IS_FILE (file), NULL);
 743
 744   iface = G_FILE_GET_IFACE (file);
 745
 746   return (* iface->dup) (file);
 747 }
 748
 749 /**
 750  * g_file_hash:
 751  * @file: (type GFile): #gconstpointer to a #GFile
 752  *
 753  * Creates a hash value for a #GFile.
 754  *
 755  * This call does no blocking I/O.
 756  *
 757  * Virtual: hash
 758  * Returns: 0 if @file is not a valid #GFile, otherwise an
 759  *   integer that can be used as hash value for the #GFile.
 760  *   This function is intended for easily hashing a #GFile to
 761  *   add to a #GHashTable or similar data structure.
 762  */
 763 guint
 764 g_file_hash (gconstpointer file)
 765 {
 766   GFileIface *iface;
 767
 768   g_return_val_if_fail (G_IS_FILE (file), 0);
 769
 770   iface = G_FILE_GET_IFACE (file);
 771
 772   return (* iface->hash) ((GFile *)file);
 773 }
 774
 775 /**
 776  * g_file_equal:
 777  * @file1: the first #GFile
 778  * @file2: the second #GFile
 779  *
 780  * Checks if the two given #GFiles refer to the same file.
 781  *
 782  * Note that two #GFiles that differ can still refer to the same
 783  * file on the filesystem due to various forms of filename
 784  * aliasing.
 785  *
 786  * This call does no blocking I/O.
 787  *
 788  * Returns: %TRUE if @file1 and @file2 are equal.
 789  */
 790 gboolean
 791 g_file_equal (GFile *file1,
 792               GFile *file2)
 793 {
 794   GFileIface *iface;
 795
 796   g_return_val_if_fail (G_IS_FILE (file1), FALSE);
 797   g_return_val_if_fail (G_IS_FILE (file2), FALSE);
 798
 799   if (file1 == file2)
 800     return TRUE;
 801
 802   if (G_TYPE_FROM_INSTANCE (file1) != G_TYPE_FROM_INSTANCE (file2))
 803     return FALSE;
 804
 805   iface = G_FILE_GET_IFACE (file1);
 806
 807   return (* iface->equal) (file1, file2);
 808 }
 809
 810
 811 /**
 812  * g_file_get_parent:
 813  * @file: input #GFile
 814  *
 815  * Gets the parent directory for the @file.
 816  * If the @file represents the root directory of the
 817  * file system, then %NULL will be returned.
 818  *
 819  * This call does no blocking I/O.
 820  *
 821  * Returns: (nullable) (transfer full): a #GFile structure to the
 822  *   parent of the given #GFile or %NULL if there is no parent. Free
 823  *   the returned object with g_object_unref().
 824  */
 825 GFile *
 826 g_file_get_parent (GFile *file)
 827 {
 828   GFileIface *iface;
 829
 830   g_return_val_if_fail (G_IS_FILE (file), NULL);
 831
 832   iface = G_FILE_GET_IFACE (file);
 833
 834   return (* iface->get_parent) (file);
 835 }
 836
 837 /**
 838  * g_file_has_parent:
 839  * @file: input #GFile
 840  * @parent: (nullable): the parent to check for, or %NULL
 841  *
 842  * Checks if @file has a parent, and optionally, if it is @parent.
 843  *
 844  * If @parent is %NULL then this function returns %TRUE if @file has any
 845  * parent at all.  If @parent is non-%NULL then %TRUE is only returned
 846  * if @file is an immediate child of @parent.
 847  *
 848  * Returns: %TRUE if @file is an immediate child of @parent (or any parent in
 849  *   the case that @parent is %NULL).
 850  *
 851  * Since: 2.24
 852  */
 853 gboolean
 854 g_file_has_parent (GFile *file,
 855                    GFile *parent)
 856 {
 857   GFile *actual_parent;
 858   gboolean result;
 859
 860   g_return_val_if_fail (G_IS_FILE (file), FALSE);
 861   g_return_val_if_fail (parent == NULL || G_IS_FILE (parent), FALSE);
 862
 863   actual_parent = g_file_get_parent (file);
 864
 865   if (actual_parent != NULL)
 866     {
 867       if (parent != NULL)
 868         result = g_file_equal (parent, actual_parent);
 869       else
 870         result = TRUE;
 871
 872       g_object_unref (actual_parent);
 873     }
 874   else
 875     result = FALSE;
 876
 877   return result;
 878 }
 879
 880 /**
 881  * g_file_get_child:
 882  * @file: input #GFile
 883  * @name: (type filename): string containing the child's basename
 884  *
 885  * Gets a child of @file with basename equal to @name.
 886  *
 887  * Note that the file with that specific name might not exist, but
 888  * you can still have a #GFile that points to it. You can use this
 889  * for instance to create that file.
 890  *
 891  * This call does no blocking I/O.
 892  *
 893  * Returns: (transfer full): a #GFile to a child specified by @name.
 894  *   Free the returned object with g_object_unref().
 895  */
 896 GFile *
 897 g_file_get_child (GFile      *file,
 898                   const char *name)
 899 {
 900   g_return_val_if_fail (G_IS_FILE (file), NULL);
 901   g_return_val_if_fail (name != NULL, NULL);
 902   g_return_val_if_fail (!g_path_is_absolute (name), NULL);
 903
 904   return g_file_resolve_relative_path (file, name);
 905 }
 906
 907 /**
 908  * g_file_get_child_for_display_name:
 909  * @file: input #GFile
 910  * @display_name: string to a possible child
 911  * @error: return location for an error
 912  *
 913  * Gets the child of @file for a given @display_name (i.e. a UTF-8
 914  * version of the name). If this function fails, it returns %NULL
 915  * and @error will be set. This is very useful when constructing a
 916  * #GFile for a new file and the user entered the filename in the
 917  * user interface, for instance when you select a directory and
 918  * type a filename in the file selector.
 919  *
 920  * This call does no blocking I/O.
 921  *
 922  * Returns: (transfer full): a #GFile to the specified child, or
 923  *   %NULL if the display name couldn't be converted.
 924  *   Free the returned object with g_object_unref().
 925  */
 926 GFile *
 927 g_file_get_child_for_display_name (GFile      *file,
 928                                    const char *display_name,
 929                                    GError **error)
 930 {
 931   GFileIface *iface;
 932
 933   g_return_val_if_fail (G_IS_FILE (file), NULL);
 934   g_return_val_if_fail (display_name != NULL, NULL);
 935
 936   iface = G_FILE_GET_IFACE (file);
 937
 938   return (* iface->get_child_for_display_name) (file, display_name, error);
 939 }
 940
 941 /**
 942  * g_file_has_prefix:
 943  * @file: input #GFile
 944  * @prefix: input #GFile
 945  *
 946  * Checks whether @file has the prefix specified by @prefix.
 947  *
 948  * In other words, if the names of initial elements of @file's
 949  * pathname match @prefix. Only full pathname elements are matched,
 950  * so a path like /foo is not considered a prefix of /foobar, only
 951  * of /foo/bar.
 952  *
 953  * A #GFile is not a prefix of itself. If you want to check for
 954  * equality, use g_file_equal().
 955  *
 956  * This call does no I/O, as it works purely on names. As such it can
 957  * sometimes return %FALSE even if @file is inside a @prefix (from a
 958  * filesystem point of view), because the prefix of @file is an alias
 959  * of @prefix.
 960  *
 961  * Virtual: prefix_matches
 962  * Returns:  %TRUE if the @file's parent, grandparent, etc is @prefix,
 963  *   %FALSE otherwise.
 964  */
 965 gboolean
 966 g_file_has_prefix (GFile *file,
 967                    GFile *prefix)
 968 {
 969   GFileIface *iface;
 970
 971   g_return_val_if_fail (G_IS_FILE (file), FALSE);
 972   g_return_val_if_fail (G_IS_FILE (prefix), FALSE);
 973
 974   if (G_TYPE_FROM_INSTANCE (file) != G_TYPE_FROM_INSTANCE (prefix))
 975     return FALSE;
 976
 977   iface = G_FILE_GET_IFACE (file);
 978
 979   /* The vtable function differs in arg order since
 980    * we're using the old contains_file call
 981    */
 982   return (* iface->prefix_matches) (prefix, file);
 983 }
 984
 985 /**
 986  * g_file_get_relative_path: (virtual get_relative_path)
 987  * @parent: input #GFile
 988  * @descendant: input #GFile
 989  *
 990  * Gets the path for @descendant relative to @parent.
 991  *
 992  * This call does no blocking I/O.
 993  *
 994  * Returns: (type filename) (nullable): string with the relative path from
 995  *   @descendant to @parent, or %NULL if @descendant doesn't have @parent as
 996  *   prefix. The returned string should be freed with g_free() when
 997  *   no longer needed.
 998  */
 999 char *
1000 g_file_get_relative_path (GFile *parent,
1001                           GFile *descendant)
1002 {
1003   GFileIface *iface;
1004
1005   g_return_val_if_fail (G_IS_FILE (parent), NULL);
1006   g_return_val_if_fail (G_IS_FILE (descendant), NULL);
1007
1008   if (G_TYPE_FROM_INSTANCE (parent) != G_TYPE_FROM_INSTANCE (descendant))
1009     return NULL;
1010
1011   iface = G_FILE_GET_IFACE (parent);
1012
1013   return (* iface->get_relative_path) (parent, descendant);
1014 }
1015
1016 /**
1017  * g_file_resolve_relative_path:
1018  * @file: input #GFile
1019  * @relative_path: (type filename): a given relative path string
1020  *
1021  * Resolves a relative path for @file to an absolute path.
1022  *
1023  * This call does no blocking I/O.
1024  *
1025  * If the @relative_path is an absolute path name, the resolution
1026  * is done absolutely (without taking @file path as base).
1027  *
1028  * Returns: (transfer full): a #GFile for the resolved path.
1029  */
1030 GFile *
1031 g_file_resolve_relative_path (GFile      *file,
1032                               const char *relative_path)
1033 {
1034   GFileIface *iface;
1035
1036   g_return_val_if_fail (G_IS_FILE (file), NULL);
1037   g_return_val_if_fail (relative_path != NULL, NULL);
1038
1039   iface = G_FILE_GET_IFACE (file);
1040
1041   return (* iface->resolve_relative_path) (file, relative_path);
1042 }
1043
1044 /**
1045  * g_file_enumerate_children:
1046  * @file: input #GFile
1047  * @attributes: an attribute query string
1048  * @flags: a set of #GFileQueryInfoFlags
1049  * @cancellable: (nullable): optional #GCancellable object,
1050  *   %NULL to ignore
1051  * @error: #GError for error reporting
1052  *
1053  * Gets the requested information about the files in a directory.
1054  * The result is a #GFileEnumerator object that will give out
1055  * #GFileInfo objects for all the files in the directory.
1056  *
1057  * The @attributes value is a string that specifies the file
1058  * attributes that should be gathered. It is not an error if
1059  * it's not possible to read a particular requested attribute
1060  * from a file - it just won't be set. @attributes should
1061  * be a comma-separated list of attributes or attribute wildcards.
1062  * The wildcard "*" means all attributes, and a wildcard like
1063  * "standard::*" means all attributes in the standard namespace.
1064  * An example attribute query be "standard::*,owner::user".
1065  * The standard attributes are available as defines, like
1066  * %G_FILE_ATTRIBUTE_STANDARD_NAME. %G_FILE_ATTRIBUTE_STANDARD_NAME should
1067  * always be specified if you plan to call g_file_enumerator_get_child() or
1068  * g_file_enumerator_iterate() on the returned enumerator.
1069  *
1070  * If @cancellable is not %NULL, then the operation can be cancelled
1071  * by triggering the cancellable object from another thread. If the
1072  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1073  * returned.
1074  *
1075  * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
1076  * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
1077  * error will be returned. Other errors are possible too.
1078  *
1079  * Returns: (transfer full): A #GFileEnumerator if successful,
1080  *   %NULL on error. Free the returned object with g_object_unref().
1081  */
1082 GFileEnumerator *
1083 g_file_enumerate_children (GFile                *file,
1084                            const char           *attributes,
1085                            GFileQueryInfoFlags   flags,
1086                            GCancellable         *cancellable,
1087                            GError              **error)
1088 {
1089   GFileIface *iface;
1090
1091   g_return_val_if_fail (G_IS_FILE (file), NULL);
1092
1093   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1094     return NULL;
1095
1096   iface = G_FILE_GET_IFACE (file);
1097
1098   if (iface->enumerate_children == NULL)
1099     {
1100       g_set_error_literal (error, G_IO_ERROR,
1101                            G_IO_ERROR_NOT_SUPPORTED,
1102                            _("Operation not supported"));
1103       return NULL;
1104     }
1105
1106   return (* iface->enumerate_children) (file, attributes, flags,
1107                                         cancellable, error);
1108 }
1109
1110 /**
1111  * g_file_enumerate_children_async:
1112  * @file: input #GFile
1113  * @attributes: an attribute query string
1114  * @flags: a set of #GFileQueryInfoFlags
1115  * @io_priority: the [I/O priority][io-priority] of the request
1116  * @cancellable: (nullable): optional #GCancellable object,
1117  *   %NULL to ignore
1118  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
1119  *   to call when the request is satisfied
1120  * @user_data: the data to pass to callback function
1121  *
1122  * Asynchronously gets the requested information about the files
1123  * in a directory. The result is a #GFileEnumerator object that will
1124  * give out #GFileInfo objects for all the files in the directory.
1125  *
1126  * For more details, see g_file_enumerate_children() which is
1127  * the synchronous version of this call.
1128  *
1129  * When the operation is finished, @callback will be called. You can
1130  * then call g_file_enumerate_children_finish() to get the result of
1131  * the operation.
1132  */
1133 void
1134 g_file_enumerate_children_async (GFile               *file,
1135                                  const char          *attributes,
1136                                  GFileQueryInfoFlags  flags,
1137                                  int                  io_priority,
1138                                  GCancellable        *cancellable,
1139                                  GAsyncReadyCallback  callback,
1140                                  gpointer             user_data)
1141 {
1142   GFileIface *iface;
1143
1144   g_return_if_fail (G_IS_FILE (file));
1145
1146   iface = G_FILE_GET_IFACE (file);
1147   (* iface->enumerate_children_async) (file,
1148                                        attributes,
1149                                        flags,
1150                                        io_priority,
1151                                        cancellable,
1152                                        callback,
1153                                        user_data);
1154 }
1155
1156 /**
1157  * g_file_enumerate_children_finish:
1158  * @file: input #GFile
1159  * @res: a #GAsyncResult
1160  * @error: a #GError
1161  *
1162  * Finishes an async enumerate children operation.
1163  * See g_file_enumerate_children_async().
1164  *
1165  * Returns: (transfer full): a #GFileEnumerator or %NULL
1166  *   if an error occurred.
1167  *   Free the returned object with g_object_unref().
1168  */
1169 GFileEnumerator *
1170 g_file_enumerate_children_finish (GFile         *file,
1171                                   GAsyncResult  *res,
1172                                   GError       **error)
1173 {
1174   GFileIface *iface;
1175
1176   g_return_val_if_fail (G_IS_FILE (file), NULL);
1177   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
1178
1179   if (g_async_result_legacy_propagate_error (res, error))
1180     return NULL;
1181
1182   iface = G_FILE_GET_IFACE (file);
1183   return (* iface->enumerate_children_finish) (file, res, error);
1184 }
1185
1186 /**
1187  * g_file_query_exists:
1188  * @file: input #GFile
1189  * @cancellable: (nullable): optional #GCancellable object,
1190  *   %NULL to ignore
1191  *
1192  * Utility function to check if a particular file exists. This is
1193  * implemented using g_file_query_info() and as such does blocking I/O.
1194  *
1195  * Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use)
1196  * and then execute something based on the outcome of that, because the
1197  * file might have been created or removed in between the operations. The
1198  * general approach to handling that is to not check, but just do the
1199  * operation and handle the errors as they come.
1200  *
1201  * As an example of race-free checking, take the case of reading a file,
1202  * and if it doesn't exist, creating it. There are two racy versions: read
1203  * it, and on error create it; and: check if it exists, if not create it.
1204  * These can both result in two processes creating the file (with perhaps
1205  * a partially written file as the result). The correct approach is to
1206  * always try to create the file with g_file_create() which will either
1207  * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
1208  *
1209  * However, in many cases an existence check is useful in a user interface,
1210  * for instance to make a menu item sensitive/insensitive, so that you don't
1211  * have to fool users that something is possible and then just show an error
1212  * dialog. If you do this, you should make sure to also handle the errors
1213  * that can happen due to races when you execute the operation.
1214  *
1215  * Returns: %TRUE if the file exists (and can be detected without error),
1216  *   %FALSE otherwise (or if cancelled).
1217  */
1218 gboolean
1219 g_file_query_exists (GFile        *file,
1220                      GCancellable *cancellable)
1221 {
1222   GFileInfo *info;
1223
1224   g_return_val_if_fail (G_IS_FILE(file), FALSE);
1225
1226   info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_TYPE,
1227                             G_FILE_QUERY_INFO_NONE, cancellable, NULL);
1228   if (info != NULL)
1229     {
1230       g_object_unref (info);
1231       return TRUE;
1232     }
1233
1234   return FALSE;
1235 }
1236
1237 /**
1238  * g_file_query_file_type:
1239  * @file: input #GFile
1240  * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
1241  * @cancellable: (nullable): optional #GCancellable object,
1242  *   %NULL to ignore
1243  *
1244  * Utility function to inspect the #GFileType of a file. This is
1245  * implemented using g_file_query_info() and as such does blocking I/O.
1246  *
1247  * The primary use case of this method is to check if a file is
1248  * a regular file, directory, or symlink.
1249  *
1250  * Returns: The #GFileType of the file and %G_FILE_TYPE_UNKNOWN
1251  *   if the file does not exist
1252  *
1253  * Since: 2.18
1254  */
1255 GFileType
1256 g_file_query_file_type (GFile               *file,
1257                         GFileQueryInfoFlags  flags,
1258                         GCancellable        *cancellable)
1259 {
1260   GFileInfo *info;
1261   GFileType file_type;
1262
1263   g_return_val_if_fail (G_IS_FILE(file), G_FILE_TYPE_UNKNOWN);
1264   info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_TYPE, flags,
1265                             cancellable, NULL);
1266   if (info != NULL)
1267     {
1268       file_type = g_file_info_get_file_type (info);
1269       g_object_unref (info);
1270     }
1271   else
1272     file_type = G_FILE_TYPE_UNKNOWN;
1273
1274   return file_type;
1275 }
1276
1277 /**
1278  * g_file_query_info:
1279  * @file: input #GFile
1280  * @attributes: an attribute query string
1281  * @flags: a set of #GFileQueryInfoFlags
1282  * @cancellable: (nullable): optional #GCancellable object,
1283  *   %NULL to ignore
1284  * @error: a #GError
1285  *
1286  * Gets the requested information about specified @file.
1287  * The result is a #GFileInfo object that contains key-value
1288  * attributes (such as the type or size of the file).
1289  *
1290  * The @attributes value is a string that specifies the file
1291  * attributes that should be gathered. It is not an error if
1292  * it's not possible to read a particular requested attribute
1293  * from a file - it just won't be set. @attributes should be a
1294  * comma-separated list of attributes or attribute wildcards.
1295  * The wildcard "*" means all attributes, and a wildcard like
1296  * "standard::*" means all attributes in the standard namespace.
1297  * An example attribute query be "standard::*,owner::user".
1298  * The standard attributes are available as defines, like
1299  * %G_FILE_ATTRIBUTE_STANDARD_NAME.
1300  *
1301  * If @cancellable is not %NULL, then the operation can be cancelled
1302  * by triggering the cancellable object from another thread. If the
1303  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1304  * returned.
1305  *
1306  * For symlinks, normally the information about the target of the
1307  * symlink is returned, rather than information about the symlink
1308  * itself. However if you pass %G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
1309  * in @flags the information about the symlink itself will be returned.
1310  * Also, for symlinks that point to non-existing files the information
1311  * about the symlink itself will be returned.
1312  *
1313  * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
1314  * returned. Other errors are possible too, and depend on what kind of
1315  * filesystem the file is on.
1316  *
1317  * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
1318  *   on error. Free the returned object with g_object_unref().
1319  */
1320 GFileInfo *
1321 g_file_query_info (GFile                *file,
1322                    const char           *attributes,
1323                    GFileQueryInfoFlags   flags,
1324                    GCancellable         *cancellable,
1325                    GError              **error)
1326 {
1327   GFileIface *iface;
1328
1329   g_return_val_if_fail (G_IS_FILE (file), NULL);
1330
1331   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1332     return NULL;
1333
1334   iface = G_FILE_GET_IFACE (file);
1335
1336   if (iface->query_info == NULL)
1337     {
1338       g_set_error_literal (error, G_IO_ERROR,
1339                            G_IO_ERROR_NOT_SUPPORTED,
1340                            _("Operation not supported"));
1341       return NULL;
1342     }
1343
1344   return (* iface->query_info) (file, attributes, flags, cancellable, error);
1345 }
1346
1347 /**
1348  * g_file_query_info_async:
1349  * @file: input #GFile
1350  * @attributes: an attribute query string
1351  * @flags: a set of #GFileQueryInfoFlags
1352  * @io_priority: the [I/O priority][io-priority] of the request
1353  * @cancellable: (nullable): optional #GCancellable object,
1354  *   %NULL to ignore
1355  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
1356  *   to call when the request is satisfied
1357  * @user_data: the data to pass to callback function
1358  *
1359  * Asynchronously gets the requested information about specified @file.
1360  * The result is a #GFileInfo object that contains key-value attributes
1361  * (such as type or size for the file).
1362  *
1363  * For more details, see g_file_query_info() which is the synchronous
1364  * version of this call.
1365  *
1366  * When the operation is finished, @callback will be called. You can
1367  * then call g_file_query_info_finish() to get the result of the operation.
1368  */
1369 void
1370 g_file_query_info_async (GFile               *file,
1371                          const char          *attributes,
1372                          GFileQueryInfoFlags  flags,
1373                          int                  io_priority,
1374                          GCancellable        *cancellable,
1375                          GAsyncReadyCallback  callback,
1376                          gpointer             user_data)
1377 {
1378   GFileIface *iface;
1379
1380   g_return_if_fail (G_IS_FILE (file));
1381
1382   iface = G_FILE_GET_IFACE (file);
1383   (* iface->query_info_async) (file,
1384                                attributes,
1385                                flags,
1386                                io_priority,
1387                                cancellable,
1388                                callback,
1389                                user_data);
1390 }
1391
1392 /**
1393  * g_file_query_info_finish:
1394  * @file: input #GFile
1395  * @res: a #GAsyncResult
1396  * @error: a #GError
1397  *
1398  * Finishes an asynchronous file info query.
1399  * See g_file_query_info_async().
1400  *
1401  * Returns: (transfer full): #GFileInfo for given @file
1402  *   or %NULL on error. Free the returned object with
1403  *   g_object_unref().
1404  */
1405 GFileInfo *
1406 g_file_query_info_finish (GFile         *file,
1407                           GAsyncResult  *res,
1408                           GError       **error)
1409 {
1410   GFileIface *iface;
1411
1412   g_return_val_if_fail (G_IS_FILE (file), NULL);
1413   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
1414
1415   if (g_async_result_legacy_propagate_error (res, error))
1416     return NULL;
1417
1418   iface = G_FILE_GET_IFACE (file);
1419   return (* iface->query_info_finish) (file, res, error);
1420 }
1421
1422 /**
1423  * g_file_query_filesystem_info:
1424  * @file: input #GFile
1425  * @attributes:  an attribute query string
1426  * @cancellable: (nullable): optional #GCancellable object,
1427  *   %NULL to ignore
1428  * @error: a #GError
1429  *
1430  * Similar to g_file_query_info(), but obtains information
1431  * about the filesystem the @file is on, rather than the file itself.
1432  * For instance the amount of space available and the type of
1433  * the filesystem.
1434  *
1435  * The @attributes value is a string that specifies the attributes
1436  * that should be gathered. It is not an error if it's not possible
1437  * to read a particular requested attribute from a file - it just
1438  * won't be set. @attributes should be a comma-separated list of
1439  * attributes or attribute wildcards. The wildcard "*" means all
1440  * attributes, and a wildcard like "filesystem::*" means all attributes
1441  * in the filesystem namespace. The standard namespace for filesystem
1442  * attributes is "filesystem". Common attributes of interest are
1443  * %G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
1444  * in bytes), %G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
1445  * and %G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
1446  *
1447  * If @cancellable is not %NULL, then the operation can be cancelled
1448  * by triggering the cancellable object from another thread. If the
1449  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1450  * returned.
1451  *
1452  * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
1453  * be returned. Other errors are possible too, and depend on what
1454  * kind of filesystem the file is on.
1455  *
1456  * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
1457  *   Free the returned object with g_object_unref().
1458  */
1459 GFileInfo *
1460 g_file_query_filesystem_info (GFile         *file,
1461                               const char    *attributes,
1462                               GCancellable  *cancellable,
1463                               GError       **error)
1464 {
1465   GFileIface *iface;
1466
1467   g_return_val_if_fail (G_IS_FILE (file), NULL);
1468
1469   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1470     return NULL;
1471
1472   iface = G_FILE_GET_IFACE (file);
1473
1474   if (iface->query_filesystem_info == NULL)
1475     {
1476       g_set_error_literal (error, G_IO_ERROR,
1477                            G_IO_ERROR_NOT_SUPPORTED,
1478                            _("Operation not supported"));
1479       return NULL;
1480     }
1481
1482   return (* iface->query_filesystem_info) (file, attributes, cancellable, error);
1483 }
1484
1485 /**
1486  * g_file_query_filesystem_info_async:
1487  * @file: input #GFile
1488  * @attributes: an attribute query string
1489  * @io_priority: the [I/O priority][io-priority] of the request
1490  * @cancellable: (nullable): optional #GCancellable object,
1491  *   %NULL to ignore
1492  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
1493  *   to call when the request is satisfied
1494  * @user_data: the data to pass to callback function
1495  *
1496  * Asynchronously gets the requested information about the filesystem
1497  * that the specified @file is on. The result is a #GFileInfo object
1498  * that contains key-value attributes (such as type or size for the
1499  * file).
1500  *
1501  * For more details, see g_file_query_filesystem_info() which is the
1502  * synchronous version of this call.
1503  *
1504  * When the operation is finished, @callback will be called. You can
1505  * then call g_file_query_info_finish() to get the result of the
1506  * operation.
1507  */
1508 void
1509 g_file_query_filesystem_info_async (GFile               *file,
1510                                     const char          *attributes,
1511                                     int                  io_priority,
1512                                     GCancellable        *cancellable,
1513                                     GAsyncReadyCallback  callback,
1514                                     gpointer             user_data)
1515 {
1516   GFileIface *iface;
1517
1518   g_return_if_fail (G_IS_FILE (file));
1519
1520   iface = G_FILE_GET_IFACE (file);
1521   (* iface->query_filesystem_info_async) (file,
1522                                           attributes,
1523                                           io_priority,
1524                                           cancellable,
1525                                           callback,
1526                                           user_data);
1527 }
1528
1529 /**
1530  * g_file_query_filesystem_info_finish:
1531  * @file: input #GFile
1532  * @res: a #GAsyncResult
1533  * @error: a #GError
1534  *
1535  * Finishes an asynchronous filesystem info query.
1536  * See g_file_query_filesystem_info_async().
1537  *
1538  * Returns: (transfer full): #GFileInfo for given @file
1539  *   or %NULL on error.
1540  *   Free the returned object with g_object_unref().
1541  */
1542 GFileInfo *
1543 g_file_query_filesystem_info_finish (GFile         *file,
1544                                      GAsyncResult  *res,
1545                                      GError       **error)
1546 {
1547   GFileIface *iface;
1548
1549   g_return_val_if_fail (G_IS_FILE (file), NULL);
1550   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
1551
1552   if (g_async_result_legacy_propagate_error (res, error))
1553     return NULL;
1554
1555   iface = G_FILE_GET_IFACE (file);
1556   return (* iface->query_filesystem_info_finish) (file, res, error);
1557 }
1558
1559 /**
1560  * g_file_find_enclosing_mount:
1561  * @file: input #GFile
1562  * @cancellable: (nullable): optional #GCancellable object,
1563  *   %NULL to ignore
1564  * @error: a #GError
1565  *
1566  * Gets a #GMount for the #GFile.
1567  *
1568  * #GMount is returned only for user interesting locations, see
1569  * #GVolumeMonitor. If the #GFileIface for @file does not have a #mount,
1570  * @error will be set to %G_IO_ERROR_NOT_FOUND and %NULL #will be returned.
1571  *
1572  * If @cancellable is not %NULL, then the operation can be cancelled by
1573  * triggering the cancellable object from another thread. If the operation
1574  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
1575  *
1576  * Returns: (transfer full): a #GMount where the @file is located
1577  *   or %NULL on error.
1578  *   Free the returned object with g_object_unref().
1579  */
1580 GMount *
1581 g_file_find_enclosing_mount (GFile         *file,
1582                              GCancellable  *cancellable,
1583                              GError       **error)
1584 {
1585   GFileIface *iface;
1586
1587   g_return_val_if_fail (G_IS_FILE (file), NULL);
1588
1589   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1590     return NULL;
1591
1592   iface = G_FILE_GET_IFACE (file);
1593   if (iface->find_enclosing_mount == NULL)
1594     {
1595
1596       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND,
1597                            /* Translators: This is an error message when
1598                             * trying to find the enclosing (user visible)
1599                             * mount of a file, but none exists.
1600                             */
1601                            _("Containing mount does not exist"));
1602       return NULL;
1603     }
1604
1605   return (* iface->find_enclosing_mount) (file, cancellable, error);
1606 }
1607
1608 /**
1609  * g_file_find_enclosing_mount_async:
1610  * @file: a #GFile
1611  * @io_priority: the [I/O priority][io-priority] of the request
1612  * @cancellable: (nullable): optional #GCancellable object,
1613  *   %NULL to ignore
1614  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
1615  *   to call when the request is satisfied
1616  * @user_data: the data to pass to callback function
1617  *
1618  * Asynchronously gets the mount for the file.
1619  *
1620  * For more details, see g_file_find_enclosing_mount() which is
1621  * the synchronous version of this call.
1622  *
1623  * When the operation is finished, @callback will be called.
1624  * You can then call g_file_find_enclosing_mount_finish() to
1625  * get the result of the operation.
1626  */
1627 void
1628 g_file_find_enclosing_mount_async (GFile              *file,
1629                                    int                   io_priority,
1630                                    GCancellable         *cancellable,
1631                                    GAsyncReadyCallback   callback,
1632                                    gpointer              user_data)
1633 {
1634   GFileIface *iface;
1635
1636   g_return_if_fail (G_IS_FILE (file));
1637
1638   iface = G_FILE_GET_IFACE (file);
1639   (* iface->find_enclosing_mount_async) (file,
1640                                          io_priority,
1641                                          cancellable,
1642                                          callback,
1643                                          user_data);
1644 }
1645
1646 /**
1647  * g_file_find_enclosing_mount_finish:
1648  * @file: a #GFile
1649  * @res: a #GAsyncResult
1650  * @error: a #GError
1651  *
1652  * Finishes an asynchronous find mount request.
1653  * See g_file_find_enclosing_mount_async().
1654  *
1655  * Returns: (transfer full): #GMount for given @file or %NULL on error.
1656  *   Free the returned object with g_object_unref().
1657  */
1658 GMount *
1659 g_file_find_enclosing_mount_finish (GFile         *file,
1660                                     GAsyncResult  *res,
1661                                     GError       **error)
1662 {
1663   GFileIface *iface;
1664
1665   g_return_val_if_fail (G_IS_FILE (file), NULL);
1666   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
1667
1668   if (g_async_result_legacy_propagate_error (res, error))
1669     return NULL;
1670
1671   iface = G_FILE_GET_IFACE (file);
1672   return (* iface->find_enclosing_mount_finish) (file, res, error);
1673 }
1674
1675
1676 /**
1677  * g_file_read:
1678  * @file: #GFile to read
1679  * @cancellable: (nullable): a #GCancellable
1680  * @error: a #GError, or %NULL
1681  *
1682  * Opens a file for reading. The result is a #GFileInputStream that
1683  * can be used to read the contents of the file.
1684  *
1685  * If @cancellable is not %NULL, then the operation can be cancelled by
1686  * triggering the cancellable object from another thread. If the operation
1687  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
1688  *
1689  * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
1690  * returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
1691  * error will be returned. Other errors are possible too, and depend
1692  * on what kind of filesystem the file is on.
1693  *
1694  * Virtual: read_fn
1695  * Returns: (transfer full): #GFileInputStream or %NULL on error.
1696  *   Free the returned object with g_object_unref().
1697  */
1698 GFileInputStream *
1699 g_file_read (GFile         *file,
1700              GCancellable  *cancellable,
1701              GError       **error)
1702 {
1703   GFileIface *iface;
1704
1705   g_return_val_if_fail (G_IS_FILE (file), NULL);
1706
1707   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1708     return NULL;
1709
1710   iface = G_FILE_GET_IFACE (file);
1711
1712   if (iface->read_fn == NULL)
1713     {
1714       g_set_error_literal (error, G_IO_ERROR,
1715                            G_IO_ERROR_NOT_SUPPORTED,
1716                            _("Operation not supported"));
1717       return NULL;
1718     }
1719
1720   return (* iface->read_fn) (file, cancellable, error);
1721 }
1722
1723 /**
1724  * g_file_append_to:
1725  * @file: input #GFile
1726  * @flags: a set of #GFileCreateFlags
1727  * @cancellable: (nullable): optional #GCancellable object,
1728  *   %NULL to ignore
1729  * @error: a #GError, or %NULL
1730  *
1731  * Gets an output stream for appending data to the file.
1732  * If the file doesn't already exist it is created.
1733  *
1734  * By default files created are generally readable by everyone,
1735  * but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
1736  * will be made readable only to the current user, to the level that
1737  * is supported on the target filesystem.
1738  *
1739  * If @cancellable is not %NULL, then the operation can be cancelled
1740  * by triggering the cancellable object from another thread. If the
1741  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1742  * returned.
1743  *
1744  * Some file systems don't allow all file names, and may return an
1745  * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
1746  * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
1747  * possible too, and depend on what kind of filesystem the file is on.
1748  *
1749  * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
1750  *   Free the returned object with g_object_unref().
1751  */
1752 GFileOutputStream *
1753 g_file_append_to (GFile             *file,
1754                   GFileCreateFlags   flags,
1755                   GCancellable      *cancellable,
1756                   GError           **error)
1757 {
1758   GFileIface *iface;
1759
1760   g_return_val_if_fail (G_IS_FILE (file), NULL);
1761
1762   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1763     return NULL;
1764
1765   iface = G_FILE_GET_IFACE (file);
1766
1767   if (iface->append_to == NULL)
1768     {
1769       g_set_error_literal (error, G_IO_ERROR,
1770                            G_IO_ERROR_NOT_SUPPORTED,
1771                            _("Operation not supported"));
1772       return NULL;
1773     }
1774
1775   return (* iface->append_to) (file, flags, cancellable, error);
1776 }
1777
1778 /**
1779  * g_file_create:
1780  * @file: input #GFile
1781  * @flags: a set of #GFileCreateFlags
1782  * @cancellable: (nullable): optional #GCancellable object,
1783  *   %NULL to ignore
1784  * @error: a #GError, or %NULL
1785  *
1786  * Creates a new file and returns an output stream for writing to it.
1787  * The file must not already exist.
1788  *
1789  * By default files created are generally readable by everyone,
1790  * but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
1791  * will be made readable only to the current user, to the level
1792  * that is supported on the target filesystem.
1793  *
1794  * If @cancellable is not %NULL, then the operation can be cancelled
1795  * by triggering the cancellable object from another thread. If the
1796  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1797  * returned.
1798  *
1799  * If a file or directory with this name already exists the
1800  * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
1801  * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
1802  * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
1803  * be returned. Other errors are possible too, and depend on what kind
1804  * of filesystem the file is on.
1805  *
1806  * Returns: (transfer full): a #GFileOutputStream for the newly created
1807  *   file, or %NULL on error.
1808  *   Free the returned object with g_object_unref().
1809  */
1810 GFileOutputStream *
1811 g_file_create (GFile             *file,
1812                GFileCreateFlags   flags,
1813                GCancellable      *cancellable,
1814                GError           **error)
1815 {
1816   GFileIface *iface;
1817
1818   g_return_val_if_fail (G_IS_FILE (file), NULL);
1819
1820   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1821     return NULL;
1822
1823   iface = G_FILE_GET_IFACE (file);
1824
1825   if (iface->create == NULL)
1826     {
1827       g_set_error_literal (error, G_IO_ERROR,
1828                            G_IO_ERROR_NOT_SUPPORTED,
1829                            _("Operation not supported"));
1830       return NULL;
1831     }
1832
1833   return (* iface->create) (file, flags, cancellable, error);
1834 }
1835
1836 /**
1837  * g_file_replace:
1838  * @file: input #GFile
1839  * @etag: (nullable): an optional [entity tag][gfile-etag]
1840  *   for the current #GFile, or #NULL to ignore
1841  * @make_backup: %TRUE if a backup should be created
1842  * @flags: a set of #GFileCreateFlags
1843  * @cancellable: (nullable): optional #GCancellable object,
1844  *   %NULL to ignore
1845  * @error: a #GError, or %NULL
1846  *
1847  * Returns an output stream for overwriting the file, possibly
1848  * creating a backup copy of the file first. If the file doesn't exist,
1849  * it will be created.
1850  *
1851  * This will try to replace the file in the safest way possible so
1852  * that any errors during the writing will not affect an already
1853  * existing copy of the file. For instance, for local files it
1854  * may write to a temporary file and then atomically rename over
1855  * the destination when the stream is closed.
1856  *
1857  * By default files created are generally readable by everyone,
1858  * but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
1859  * will be made readable only to the current user, to the level that
1860  * is supported on the target filesystem.
1861  *
1862  * If @cancellable is not %NULL, then the operation can be cancelled
1863  * by triggering the cancellable object from another thread. If the
1864  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1865  * returned.
1866  *
1867  * If you pass in a non-%NULL @etag value and @file already exists, then
1868  * this value is compared to the current entity tag of the file, and if
1869  * they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This
1870  * generally means that the file has been changed since you last read
1871  * it. You can get the new etag from g_file_output_stream_get_etag()
1872  * after you've finished writing and closed the #GFileOutputStream. When
1873  * you load a new file you can use g_file_input_stream_query_info() to
1874  * get the etag of the file.
1875  *
1876  * If @make_backup is %TRUE, this function will attempt to make a
1877  * backup of the current file before overwriting it. If this fails
1878  * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
1879  * want to replace anyway, try again with @make_backup set to %FALSE.
1880  *
1881  * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
1882  * be returned, and if the file is some other form of non-regular file
1883  * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
1884  * file systems don't allow all file names, and may return an
1885  * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
1886  * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
1887  * possible too, and depend on what kind of filesystem the file is on.
1888  *
1889  * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
1890  *   Free the returned object with g_object_unref().
1891  */
1892 GFileOutputStream *
1893 g_file_replace (GFile             *file,
1894                 const char        *etag,
1895                 gboolean           make_backup,
1896                 GFileCreateFlags   flags,
1897                 GCancellable      *cancellable,
1898                 GError           **error)
1899 {
1900   GFileIface *iface;
1901
1902   g_return_val_if_fail (G_IS_FILE (file), NULL);
1903
1904   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1905     return NULL;
1906
1907   iface = G_FILE_GET_IFACE (file);
1908
1909   if (iface->replace == NULL)
1910     {
1911       g_set_error_literal (error, G_IO_ERROR,
1912                            G_IO_ERROR_NOT_SUPPORTED,
1913                            _("Operation not supported"));
1914       return NULL;
1915     }
1916
1917   /* Handle empty tag string as NULL in consistent way. */
1918   if (etag && *etag == 0)
1919     etag = NULL;
1920
1921   return (* iface->replace) (file, etag, make_backup, flags, cancellable, error);
1922 }
1923
1924 /**
1925  * g_file_open_readwrite:
1926  * @file: #GFile to open
1927  * @cancellable: (nullable): a #GCancellable
1928  * @error: a #GError, or %NULL
1929  *
1930  * Opens an existing file for reading and writing. The result is
1931  * a #GFileIOStream that can be used to read and write the contents
1932  * of the file.
1933  *
1934  * If @cancellable is not %NULL, then the operation can be cancelled
1935  * by triggering the cancellable object from another thread. If the
1936  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1937  * returned.
1938  *
1939  * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
1940  * be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
1941  * error will be returned. Other errors are possible too, and depend on
1942  * what kind of filesystem the file is on. Note that in many non-local
1943  * file cases read and write streams are not supported, so make sure you
1944  * really need to do read and write streaming, rather than just opening
1945  * for reading or writing.
1946  *
1947  * Returns: (transfer full): #GFileIOStream or %NULL on error.
1948  *   Free the returned object with g_object_unref().
1949  *
1950  * Since: 2.22
1951  */
1952 GFileIOStream *
1953 g_file_open_readwrite (GFile         *file,
1954                        GCancellable  *cancellable,
1955                        GError       **error)
1956 {
1957   GFileIface *iface;
1958
1959   g_return_val_if_fail (G_IS_FILE (file), NULL);
1960
1961   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1962     return NULL;
1963
1964   iface = G_FILE_GET_IFACE (file);
1965
1966   if (iface->open_readwrite == NULL)
1967     {
1968       g_set_error_literal (error, G_IO_ERROR,
1969                            G_IO_ERROR_NOT_SUPPORTED,
1970                            _("Operation not supported"));
1971       return NULL;
1972     }
1973
1974   return (* iface->open_readwrite) (file, cancellable, error);
1975 }
1976
1977 /**
1978  * g_file_create_readwrite:
1979  * @file: a #GFile
1980  * @flags: a set of #GFileCreateFlags
1981  * @cancellable: (nullable): optional #GCancellable object,
1982  *   %NULL to ignore
1983  * @error: return location for a #GError, or %NULL
1984  *
1985  * Creates a new file and returns a stream for reading and
1986  * writing to it. The file must not already exist.
1987  *
1988  * By default files created are generally readable by everyone,
1989  * but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
1990  * will be made readable only to the current user, to the level
1991  * that is supported on the target filesystem.
1992  *
1993  * If @cancellable is not %NULL, then the operation can be cancelled
1994  * by triggering the cancellable object from another thread. If the
1995  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1996  * returned.
1997  *
1998  * If a file or directory with this name already exists, the
1999  * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
2000  * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
2001  * error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
2002  * will be returned. Other errors are possible too, and depend on what
2003  * kind of filesystem the file is on.
2004  *
2005  * Note that in many non-local file cases read and write streams are
2006  * not supported, so make sure you really need to do read and write
2007  * streaming, rather than just opening for reading or writing.
2008  *
2009  * Returns: (transfer full): a #GFileIOStream for the newly created
2010  *   file, or %NULL on error.
2011  *   Free the returned object with g_object_unref().
2012  *
2013  * Since: 2.22
2014  */
2015 GFileIOStream *
2016 g_file_create_readwrite (GFile             *file,
2017                          GFileCreateFlags   flags,
2018                          GCancellable      *cancellable,
2019                          GError           **error)
2020 {
2021   GFileIface *iface;
2022
2023   g_return_val_if_fail (G_IS_FILE (file), NULL);
2024
2025   if (g_cancellable_set_error_if_cancelled (cancellable, error))
2026     return NULL;
2027
2028   iface = G_FILE_GET_IFACE (file);
2029
2030   if (iface->create_readwrite == NULL)
2031     {
2032       g_set_error_literal (error, G_IO_ERROR,
2033                            G_IO_ERROR_NOT_SUPPORTED,
2034                            _("Operation not supported"));
2035       return NULL;
2036     }
2037
2038   return (* iface->create_readwrite) (file, flags, cancellable, error);
2039 }
2040
2041 /**
2042  * g_file_replace_readwrite:
2043  * @file: a #GFile
2044  * @etag: (nullable): an optional [entity tag][gfile-etag]
2045  *   for the current #GFile, or #NULL to ignore
2046  * @make_backup: %TRUE if a backup should be created
2047  * @flags: a set of #GFileCreateFlags
2048  * @cancellable: (nullable): optional #GCancellable object,
2049  *   %NULL to ignore
2050  * @error: return location for a #GError, or %NULL
2051  *
2052  * Returns an output stream for overwriting the file in readwrite mode,
2053  * possibly creating a backup copy of the file first. If the file doesn't
2054  * exist, it will be created.
2055  *
2056  * For details about the behaviour, see g_file_replace() which does the
2057  * same thing but returns an output stream only.
2058  *
2059  * Note that in many non-local file cases read and write streams are not
2060  * supported, so make sure you really need to do read and write streaming,
2061  * rather than just opening for reading or writing.
2062  *
2063  * Returns: (transfer full): a #GFileIOStream or %NULL on error.
2064  *   Free the returned object with g_object_unref().
2065  *
2066  * Since: 2.22
2067  */
2068 GFileIOStream *
2069 g_file_replace_readwrite (GFile             *file,
2070                           const char        *etag,
2071                           gboolean           make_backup,
2072                           GFileCreateFlags   flags,
2073                           GCancellable      *cancellable,
2074                           GError           **error)
2075 {
2076   GFileIface *iface;
2077
2078   g_return_val_if_fail (G_IS_FILE (file), NULL);
2079
2080   if (g_cancellable_set_error_if_cancelled (cancellable, error))
2081     return NULL;
2082
2083   iface = G_FILE_GET_IFACE (file);
2084
2085   if (iface->replace_readwrite == NULL)
2086     {
2087       g_set_error_literal (error, G_IO_ERROR,
2088                            G_IO_ERROR_NOT_SUPPORTED,
2089                            _("Operation not supported"));
2090       return NULL;
2091     }
2092
2093   return (* iface->replace_readwrite) (file, etag, make_backup, flags, cancellable, error);
2094 }
2095
2096 /**
2097  * g_file_read_async:
2098  * @file: input #GFile
2099  * @io_priority: the [I/O priority][io-priority] of the request
2100  * @cancellable: (nullable): optional #GCancellable object,
2101  *   %NULL to ignore
2102  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
2103  *   to call when the request is satisfied
2104  * @user_data: the data to pass to callback function
2105  *
2106  * Asynchronously opens @file for reading.
2107  *
2108  * For more details, see g_file_read() which is
2109  * the synchronous version of this call.
2110  *
2111  * When the operation is finished, @callback will be called.
2112  * You can then call g_file_read_finish() to get the result
2113  * of the operation.
2114  */
2115 void
2116 g_file_read_async (GFile               *file,
2117                    int                  io_priority,
2118                    GCancellable        *cancellable,
2119                    GAsyncReadyCallback  callback,
2120                    gpointer             user_data)
2121 {
2122   GFileIface *iface;
2123
2124   g_return_if_fail (G_IS_FILE (file));
2125
2126   iface = G_FILE_GET_IFACE (file);
2127   (* iface->read_async) (file,
2128                          io_priority,
2129                          cancellable,
2130                          callback,
2131                          user_data);
2132 }
2133
2134 /**
2135  * g_file_read_finish:
2136  * @file: input #GFile
2137  * @res: a #GAsyncResult
2138  * @error: a #GError, or %NULL
2139  *
2140  * Finishes an asynchronous file read operation started with
2141  * g_file_read_async().
2142  *
2143  * Returns: (transfer full): a #GFileInputStream or %NULL on error.
2144  *   Free the returned object with g_object_unref().
2145  */
2146 GFileInputStream *
2147 g_file_read_finish (GFile         *file,
2148                     GAsyncResult  *res,
2149                     GError       **error)
2150 {
2151   GFileIface *iface;
2152
2153   g_return_val_if_fail (G_IS_FILE (file), NULL);
2154   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2155
2156   if (g_async_result_legacy_propagate_error (res, error))
2157     return NULL;
2158
2159   iface = G_FILE_GET_IFACE (file);
2160   return (* iface->read_finish) (file, res, error);
2161 }
2162
2163 /**
2164  * g_file_append_to_async:
2165  * @file: input #GFile
2166  * @flags: a set of #GFileCreateFlags
2167  * @io_priority: the [I/O priority][io-priority] of the request
2168  * @cancellable: (nullable): optional #GCancellable object,
2169  *   %NULL to ignore
2170  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
2171  *   to call when the request is satisfied
2172  * @user_data: the data to pass to callback function
2173  *
2174  * Asynchronously opens @file for appending.
2175  *
2176  * For more details, see g_file_append_to() which is
2177  * the synchronous version of this call.
2178  *
2179  * When the operation is finished, @callback will be called.
2180  * You can then call g_file_append_to_finish() to get the result
2181  * of the operation.
2182  */
2183 void
2184 g_file_append_to_async (GFile               *file,
2185                         GFileCreateFlags     flags,
2186                         int                  io_priority,
2187                         GCancellable        *cancellable,
2188                         GAsyncReadyCallback  callback,
2189                         gpointer             user_data)
2190 {
2191   GFileIface *iface;
2192
2193   g_return_if_fail (G_IS_FILE (file));
2194
2195   iface = G_FILE_GET_IFACE (file);
2196   (* iface->append_to_async) (file,
2197                               flags,
2198                               io_priority,
2199                               cancellable,
2200                               callback,
2201                               user_data);
2202 }
2203
2204 /**
2205  * g_file_append_to_finish:
2206  * @file: input #GFile
2207  * @res: #GAsyncResult
2208  * @error: a #GError, or %NULL
2209  *
2210  * Finishes an asynchronous file append operation started with
2211  * g_file_append_to_async().
2212  *
2213  * Returns: (transfer full): a valid #GFileOutputStream
2214  *   or %NULL on error.
2215  *   Free the returned object with g_object_unref().
2216  */
2217 GFileOutputStream *
2218 g_file_append_to_finish (GFile         *file,
2219                          GAsyncResult  *res,
2220                          GError       **error)
2221 {
2222   GFileIface *iface;
2223
2224   g_return_val_if_fail (G_IS_FILE (file), NULL);
2225   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2226
2227   if (g_async_result_legacy_propagate_error (res, error))
2228     return NULL;
2229
2230   iface = G_FILE_GET_IFACE (file);
2231   return (* iface->append_to_finish) (file, res, error);
2232 }
2233
2234 /**
2235  * g_file_create_async:
2236  * @file: input #GFile
2237  * @flags: a set of #GFileCreateFlags
2238  * @io_priority: the [I/O priority][io-priority] of the request
2239  * @cancellable: (nullable): optional #GCancellable object,
2240  *   %NULL to ignore
2241  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
2242  *   to call when the request is satisfied
2243  * @user_data: the data to pass to callback function
2244  *
2245  * Asynchronously creates a new file and returns an output stream
2246  * for writing to it. The file must not already exist.
2247  *
2248  * For more details, see g_file_create() which is
2249  * the synchronous version of this call.
2250  *
2251  * When the operation is finished, @callback will be called.
2252  * You can then call g_file_create_finish() to get the result
2253  * of the operation.
2254  */
2255 void
2256 g_file_create_async (GFile               *file,
2257                      GFileCreateFlags     flags,
2258                      int                  io_priority,
2259                      GCancellable        *cancellable,
2260                      GAsyncReadyCallback  callback,
2261                      gpointer             user_data)
2262 {
2263   GFileIface *iface;
2264
2265   g_return_if_fail (G_IS_FILE (file));
2266
2267   iface = G_FILE_GET_IFACE (file);
2268   (* iface->create_async) (file,
2269                            flags,
2270                            io_priority,
2271                            cancellable,
2272                            callback,
2273                            user_data);
2274 }
2275
2276 /**
2277  * g_file_create_finish:
2278  * @file: input #GFile
2279  * @res: a #GAsyncResult
2280  * @error: a #GError, or %NULL
2281  *
2282  * Finishes an asynchronous file create operation started with
2283  * g_file_create_async().
2284  *
2285  * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
2286  *   Free the returned object with g_object_unref().
2287  */
2288 GFileOutputStream *
2289 g_file_create_finish (GFile         *file,
2290                       GAsyncResult  *res,
2291                       GError       **error)
2292 {
2293   GFileIface *iface;
2294
2295   g_return_val_if_fail (G_IS_FILE (file), NULL);
2296   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2297
2298   if (g_async_result_legacy_propagate_error (res, error))
2299     return NULL;
2300
2301   iface = G_FILE_GET_IFACE (file);
2302   return (* iface->create_finish) (file, res, error);
2303 }
2304
2305 /**
2306  * g_file_replace_async:
2307  * @file: input #GFile
2308  * @etag: (nullable): an [entity tag][gfile-etag] for the current #GFile,
2309  *   or %NULL to ignore
2310  * @make_backup: %TRUE if a backup should be created
2311  * @flags: a set of #GFileCreateFlags
2312  * @io_priority: the [I/O priority][io-priority] of the request
2313  * @cancellable: (nullable): optional #GCancellable object,
2314  *   %NULL to ignore
2315  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
2316  *   to call when the request is satisfied
2317  * @user_data: the data to pass to callback function
2318  *
2319  * Asynchronously overwrites the file, replacing the contents,
2320  * possibly creating a backup copy of the file first.
2321  *
2322  * For more details, see g_file_replace() which is
2323  * the synchronous version of this call.
2324  *
2325  * When the operation is finished, @callback will be called.
2326  * You can then call g_file_replace_finish() to get the result
2327  * of the operation.
2328  */
2329 void
2330 g_file_replace_async (GFile               *file,
2331                       const char          *etag,
2332                       gboolean             make_backup,
2333                       GFileCreateFlags     flags,
2334                       int                  io_priority,
2335                       GCancellable        *cancellable,
2336                       GAsyncReadyCallback  callback,
2337                       gpointer             user_data)
2338 {
2339   GFileIface *iface;
2340
2341   g_return_if_fail (G_IS_FILE (file));
2342
2343   iface = G_FILE_GET_IFACE (file);
2344   (* iface->replace_async) (file,
2345                             etag,
2346                             make_backup,
2347                             flags,
2348                             io_priority,
2349                             cancellable,
2350                             callback,
2351                             user_data);
2352 }
2353
2354 /**
2355  * g_file_replace_finish:
2356  * @file: input #GFile
2357  * @res: a #GAsyncResult
2358  * @error: a #GError, or %NULL
2359  *
2360  * Finishes an asynchronous file replace operation started with
2361  * g_file_replace_async().
2362  *
2363  * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
2364  *   Free the returned object with g_object_unref().
2365  */
2366 GFileOutputStream *
2367 g_file_replace_finish (GFile         *file,
2368                        GAsyncResult  *res,
2369                        GError       **error)
2370 {
2371   GFileIface *iface;
2372
2373   g_return_val_if_fail (G_IS_FILE (file), NULL);
2374   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2375
2376   if (g_async_result_legacy_propagate_error (res, error))
2377     return NULL;
2378
2379   iface = G_FILE_GET_IFACE (file);
2380   return (* iface->replace_finish) (file, res, error);
2381 }
2382
2383 /**
2384  * g_file_open_readwrite_async
2385  * @file: input #GFile
2386  * @io_priority: the [I/O priority][io-priority] of the request
2387  * @cancellable: (nullable): optional #GCancellable object,
2388  *   %NULL to ignore
2389  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
2390  *   to call when the request is satisfied
2391  * @user_data: the data to pass to callback function
2392  *
2393  * Asynchronously opens @file for reading and writing.
2394  *
2395  * For more details, see g_file_open_readwrite() which is
2396  * the synchronous version of this call.
2397  *
2398  * When the operation is finished, @callback will be called.
2399  * You can then call g_file_open_readwrite_finish() to get
2400  * the result of the operation.
2401  *
2402  * Since: 2.22
2403  */
2404 void
2405 g_file_open_readwrite_async (GFile               *file,
2406                              int                  io_priority,
2407                              GCancellable        *cancellable,
2408                              GAsyncReadyCallback  callback,
2409                              gpointer             user_data)
2410 {
2411   GFileIface *iface;
2412
2413   g_return_if_fail (G_IS_FILE (file));
2414
2415   iface = G_FILE_GET_IFACE (file);
2416   (* iface->open_readwrite_async) (file,
2417                                    io_priority,
2418                                    cancellable,
2419                                    callback,
2420                                    user_data);
2421 }
2422
2423 /**
2424  * g_file_open_readwrite_finish:
2425  * @file: input #GFile
2426  * @res: a #GAsyncResult
2427  * @error: a #GError, or %NULL
2428  *
2429  * Finishes an asynchronous file read operation started with
2430  * g_file_open_readwrite_async().
2431  *
2432  * Returns: (transfer full): a #GFileIOStream or %NULL on error.
2433  *   Free the returned object with g_object_unref().
2434  *
2435  * Since: 2.22
2436  */
2437 GFileIOStream *
2438 g_file_open_readwrite_finish (GFile         *file,
2439                               GAsyncResult  *res,
2440                               GError       **error)
2441 {
2442   GFileIface *iface;
2443
2444   g_return_val_if_fail (G_IS_FILE (file), NULL);
2445   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2446
2447   if (g_async_result_legacy_propagate_error (res, error))
2448     return NULL;
2449
2450   iface = G_FILE_GET_IFACE (file);
2451   return (* iface->open_readwrite_finish) (file, res, error);
2452 }
2453
2454 /**
2455  * g_file_create_readwrite_async:
2456  * @file: input #GFile
2457  * @flags: a set of #GFileCreateFlags
2458  * @io_priority: the [I/O priority][io-priority] of the request
2459  * @cancellable: (nullable): optional #GCancellable object,
2460  *   %NULL to ignore
2461  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
2462  *   to call when the request is satisfied
2463  * @user_data: the data to pass to callback function
2464  *
2465  * Asynchronously creates a new file and returns a stream
2466  * for reading and writing to it. The file must not already exist.
2467  *
2468  * For more details, see g_file_create_readwrite() which is
2469  * the synchronous version of this call.
2470  *
2471  * When the operation is finished, @callback will be called.
2472  * You can then call g_file_create_readwrite_finish() to get
2473  * the result of the operation.
2474  *
2475  * Since: 2.22
2476  */
2477 void
2478 g_file_create_readwrite_async (GFile               *file,
2479                                GFileCreateFlags     flags,
2480                                int                  io_priority,
2481                                GCancellable        *cancellable,
2482                                GAsyncReadyCallback  callback,
2483                                gpointer             user_data)
2484 {
2485   GFileIface *iface;
2486
2487   g_return_if_fail (G_IS_FILE (file));
2488
2489   iface = G_FILE_GET_IFACE (file);
2490   (* iface->create_readwrite_async) (file,
2491                                      flags,
2492                                      io_priority,
2493                                      cancellable,
2494                                      callback,
2495                                      user_data);
2496 }
2497
2498 /**
2499  * g_file_create_readwrite_finish:
2500  * @file: input #GFile
2501  * @res: a #GAsyncResult
2502  * @error: a #GError, or %NULL
2503  *
2504  * Finishes an asynchronous file create operation started with
2505  * g_file_create_readwrite_async().
2506  *
2507  * Returns: (transfer full): a #GFileIOStream or %NULL on error.
2508  *   Free the returned object with g_object_unref().
2509  *
2510  * Since: 2.22
2511  */
2512 GFileIOStream *
2513 g_file_create_readwrite_finish (GFile         *file,
2514                                 GAsyncResult  *res,
2515                                 GError       **error)
2516 {
2517   GFileIface *iface;
2518
2519   g_return_val_if_fail (G_IS_FILE (file), NULL);
2520   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2521
2522   if (g_async_result_legacy_propagate_error (res, error))
2523     return NULL;
2524
2525   iface = G_FILE_GET_IFACE (file);
2526   return (* iface->create_readwrite_finish) (file, res, error);
2527 }
2528
2529 /**
2530  * g_file_replace_readwrite_async:
2531  * @file: input #GFile
2532  * @etag: (nullable): an [entity tag][gfile-etag] for the current #GFile,
2533  *   or %NULL to ignore
2534  * @make_backup: %TRUE if a backup should be created
2535  * @flags: a set of #GFileCreateFlags
2536  * @io_priority: the [I/O priority][io-priority] of the request
2537  * @cancellable: (nullable): optional #GCancellable object,
2538  *   %NULL to ignore
2539  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
2540  *   to call when the request is satisfied
2541  * @user_data: the data to pass to callback function
2542  *
2543  * Asynchronously overwrites the file in read-write mode,
2544  * replacing the contents, possibly creating a backup copy
2545  * of the file first.
2546  *
2547  * For more details, see g_file_replace_readwrite() which is
2548  * the synchronous version of this call.
2549  *
2550  * When the operation is finished, @callback will be called.
2551  * You can then call g_file_replace_readwrite_finish() to get
2552  * the result of the operation.
2553  *
2554  * Since: 2.22
2555  */
2556 void
2557 g_file_replace_readwrite_async (GFile               *file,
2558                                 const char          *etag,
2559                                 gboolean             make_backup,
2560                                 GFileCreateFlags     flags,
2561                                 int                  io_priority,
2562                                 GCancellable        *cancellable,
2563                                 GAsyncReadyCallback  callback,
2564                                 gpointer             user_data)
2565 {
2566   GFileIface *iface;
2567
2568   g_return_if_fail (G_IS_FILE (file));
2569
2570   iface = G_FILE_GET_IFACE (file);
2571   (* iface->replace_readwrite_async) (file,
2572                                       etag,
2573                                       make_backup,
2574                                       flags,
2575                                       io_priority,
2576                                       cancellable,
2577                                       callback,
2578                                       user_data);
2579 }
2580
2581 /**
2582  * g_file_replace_readwrite_finish:
2583  * @file: input #GFile
2584  * @res: a #GAsyncResult
2585  * @error: a #GError, or %NULL
2586  *
2587  * Finishes an asynchronous file replace operation started with
2588  * g_file_replace_readwrite_async().
2589  *
2590  * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
2591  *   Free the returned object with g_object_unref().
2592  *
2593  * Since: 2.22
2594  */
2595 GFileIOStream *
2596 g_file_replace_readwrite_finish (GFile         *file,
2597                                  GAsyncResult  *res,
2598                                  GError       **error)
2599 {
2600   GFileIface *iface;
2601
2602   g_return_val_if_fail (G_IS_FILE (file), NULL);
2603   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2604
2605   if (g_async_result_legacy_propagate_error (res, error))
2606     return NULL;
2607
2608   iface = G_FILE_GET_IFACE (file);
2609   return (* iface->replace_readwrite_finish) (file, res, error);
2610 }
2611
2612 static gboolean
2613 copy_symlink (GFile           *destination,
2614               GFileCopyFlags   flags,
2615               GCancellable    *cancellable,
2616               const char      *target,
2617               GError         **error)
2618 {
2619   GError *my_error;
2620   gboolean tried_delete;
2621   GFileInfo *info;
2622   GFileType file_type;
2623
2624   tried_delete = FALSE;
2625
2626  retry:
2627   my_error = NULL;
2628   if (!g_file_make_symbolic_link (destination, target, cancellable, &my_error))
2629     {
2630       /* Maybe it already existed, and we want to overwrite? */
2631       if (!tried_delete && (flags & G_FILE_COPY_OVERWRITE) &&
2632           my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_EXISTS)
2633         {
2634           g_clear_error (&my_error);
2635
2636           /* Don't overwrite if the destination is a directory */
2637           info = g_file_query_info (destination, G_FILE_ATTRIBUTE_STANDARD_TYPE,
2638                                     G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2639                                     cancellable, &my_error);
2640           if (info != NULL)
2641             {
2642               file_type = g_file_info_get_file_type (info);
2643               g_object_unref (info);
2644
2645               if (file_type == G_FILE_TYPE_DIRECTORY)
2646                 {
2647                   g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_IS_DIRECTORY,
2648                                        _("Can’t copy over directory"));
2649                   return FALSE;
2650                 }
2651             }
2652
2653           if (!g_file_delete (destination, cancellable, error))
2654             return FALSE;
2655
2656           tried_delete = TRUE;
2657           goto retry;
2658         }
2659             /* Nah, fail */
2660       g_propagate_error (error, my_error);
2661       return FALSE;
2662     }
2663
2664   return TRUE;
2665 }
2666
2667 static GFileInputStream *
2668 open_source_for_copy (GFile           *source,
2669                       GFile           *destination,
2670                       GFileCopyFlags   flags,
2671                       GCancellable    *cancellable,
2672                       GError         **error)
2673 {
2674   GError *my_error;
2675   GFileInputStream *ret;
2676   GFileInfo *info;
2677   GFileType file_type;
2678
2679   my_error = NULL;
2680   ret = g_file_read (source, cancellable, &my_error);
2681   if (ret != NULL)
2682     return ret;
2683
2684   /* There was an error opening the source, try to set a good error for it: */
2685   if (my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_IS_DIRECTORY)
2686     {
2687       /* The source is a directory, don't fail with WOULD_RECURSE immediately,
2688        * as that is less useful to the app. Better check for errors on the
2689        * target instead.
2690        */
2691       g_error_free (my_error);
2692       my_error = NULL;
2693
2694       info = g_file_query_info (destination, G_FILE_ATTRIBUTE_STANDARD_TYPE,
2695                                 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2696                                 cancellable, &my_error);
2697       if (info != NULL &&
2698           g_file_info_has_attribute (info, G_FILE_ATTRIBUTE_STANDARD_TYPE))
2699         {
2700           file_type = g_file_info_get_file_type (info);
2701           g_object_unref (info);
2702
2703           if (flags & G_FILE_COPY_OVERWRITE)
2704             {
2705               if (file_type == G_FILE_TYPE_DIRECTORY)
2706                 {
2707                   g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_WOULD_MERGE,
2708                                        _("Can’t copy directory over directory"));
2709                   return NULL;
2710                 }
2711               /* continue to would_recurse error */
2712             }
2713           else
2714             {
2715               g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_EXISTS,
2716                                    _("Target file exists"));
2717               return NULL;
2718             }
2719         }
2720       else
2721         {
2722           /* Error getting info from target, return that error
2723            * (except for NOT_FOUND, which is no error here)
2724            */
2725           g_clear_object (&info);
2726           if (my_error != NULL && !g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
2727             {
2728               g_propagate_error (error, my_error);
2729               return NULL;
2730             }
2731           g_clear_error (&my_error);
2732         }
2733
2734       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_WOULD_RECURSE,
2735                            _("Can’t recursively copy directory"));
2736       return NULL;
2737     }
2738
2739   g_propagate_error (error, my_error);
2740   return NULL;
2741 }
2742
2743 static gboolean
2744 should_copy (GFileAttributeInfo *info,
2745              gboolean            copy_all_attributes,
2746              gboolean            skip_perms)
2747 {
2748   if (skip_perms && strcmp(info->name, "unix::mode") == 0)
2749         return FALSE;
2750
2751   if (copy_all_attributes)
2752     return info->flags & G_FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED;
2753   return info->flags & G_FILE_ATTRIBUTE_INFO_COPY_WITH_FILE;
2754 }
2755
2756 /**
2757  * g_file_build_attribute_list_for_copy:
2758  * @file: a #GFile to copy attributes to
2759  * @flags: a set of #GFileCopyFlags
2760  * @cancellable: (nullable): optional #GCancellable object,
2761  *   %NULL to ignore
2762  * @error: a #GError, %NULL to ignore
2763  *
2764  * Prepares the file attribute query string for copying to @file.
2765  *
2766  * This function prepares an attribute query string to be
2767  * passed to g_file_query_info() to get a list of attributes
2768  * normally copied with the file (see g_file_copy_attributes()
2769  * for the detailed description). This function is used by the
2770  * implementation of g_file_copy_attributes() and is useful
2771  * when one needs to query and set the attributes in two
2772  * stages (e.g., for recursive move of a directory).
2773  *
2774  * Returns: an attribute query string for g_file_query_info(),
2775  *   or %NULL if an error occurs.
2776  *
2777  * Since: 2.68
2778  */
2779 char *
2780 g_file_build_attribute_list_for_copy (GFile                  *file,
2781                                       GFileCopyFlags          flags,
2782                                       GCancellable           *cancellable,
2783                                       GError                **error)
2784 {
2785   char *ret = NULL;
2786   GFileAttributeInfoList *attributes = NULL, *namespaces = NULL;
2787   GString *s = NULL;
2788   gboolean first;
2789   int i;
2790   gboolean copy_all_attributes;
2791   gboolean skip_perms;
2792
2793   g_return_val_if_fail (G_IS_FILE (file), NULL);
2794   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
2795   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
2796
2797   copy_all_attributes = flags & G_FILE_COPY_ALL_METADATA;
2798   skip_perms = (flags & G_FILE_COPY_TARGET_DEFAULT_PERMS) != 0;
2799
2800   /* Ignore errors here, if the target supports no attributes there is
2801    * nothing to copy.  We still honor the cancellable though.
2802    */
2803   attributes = g_file_query_settable_attributes (file, cancellable, NULL);
2804   if (g_cancellable_set_error_if_cancelled (cancellable, error))
2805     goto out;
2806
2807   namespaces = g_file_query_writable_namespaces (file, cancellable, NULL);
2808   if (g_cancellable_set_error_if_cancelled (cancellable, error))
2809     goto out;
2810
2811   if (attributes == NULL && namespaces == NULL)
2812     goto out;
2813
2814   first = TRUE;
2815   s = g_string_new ("");
2816
2817   /* Always query the source file size, even though we can’t set that on the
2818    * destination. This is useful for the copy functions. */
2819   first = FALSE;
2820   g_string_append (s, G_FILE_ATTRIBUTE_STANDARD_SIZE);
2821
2822   if (attributes)
2823     {
2824       for (i = 0; i < attributes->n_infos; i++)
2825         {
2826           if (should_copy (&attributes->infos[i], copy_all_attributes, skip_perms))
2827             {
2828               if (first)
2829                 first = FALSE;
2830               else
2831                 g_string_append_c (s, ',');
2832
2833               g_string_append (s, attributes->infos[i].name);
2834             }
2835         }
2836     }
2837
2838   if (namespaces)
2839     {
2840       for (i = 0; i < namespaces->n_infos; i++)
2841         {
2842           if (should_copy (&namespaces->infos[i], copy_all_attributes, FALSE))
2843             {
2844               if (first)
2845                 first = FALSE;
2846               else
2847                 g_string_append_c (s, ',');
2848
2849               g_string_append (s, namespaces->infos[i].name);
2850               g_string_append (s, "::*");
2851             }
2852         }
2853     }
2854
2855   ret = g_string_free (s, FALSE);
2856   s = NULL;
2857  out:
2858   if (s)
2859     g_string_free (s, TRUE);
2860   if (attributes)
2861     g_file_attribute_info_list_unref (attributes);
2862   if (namespaces)
2863     g_file_attribute_info_list_unref (namespaces);
2864
2865   return ret;
2866 }
2867
2868 /**
2869  * g_file_copy_attributes:
2870  * @source: a #GFile with attributes
2871  * @destination: a #GFile to copy attributes to
2872  * @flags: a set of #GFileCopyFlags
2873  * @cancellable: (nullable): optional #GCancellable object,
2874  *   %NULL to ignore
2875  * @error: a #GError, %NULL to ignore
2876  *
2877  * Copies the file attributes from @source to @destination.
2878  *
2879  * Normally only a subset of the file attributes are copied,
2880  * those that are copies in a normal file copy operation
2881  * (which for instance does not include e.g. owner). However
2882  * if %G_FILE_COPY_ALL_METADATA is specified in @flags, then
2883  * all the metadata that is possible to copy is copied. This
2884  * is useful when implementing move by copy + delete source.
2885  *
2886  * Returns: %TRUE if the attributes were copied successfully,
2887  *   %FALSE otherwise.
2888  */
2889 gboolean
2890 g_file_copy_attributes (GFile           *source,
2891                         GFile           *destination,
2892                         GFileCopyFlags   flags,
2893                         GCancellable    *cancellable,
2894                         GError         **error)
2895 {
2896   char *attrs_to_read;
2897   gboolean res;
2898   GFileInfo *info;
2899   gboolean source_nofollow_symlinks;
2900
2901   attrs_to_read = g_file_build_attribute_list_for_copy (destination, flags,
2902                                                         cancellable, error);
2903   if (!attrs_to_read)
2904     return FALSE;
2905
2906   source_nofollow_symlinks = flags & G_FILE_COPY_NOFOLLOW_SYMLINKS;
2907
2908   /* Ignore errors here, if we can't read some info (e.g. if it doesn't exist)
2909    * we just don't copy it.
2910    */
2911   info = g_file_query_info (source, attrs_to_read,
2912                             source_nofollow_symlinks ? G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS:0,
2913                             cancellable,
2914                             NULL);
2915
2916   g_free (attrs_to_read);
2917
2918   res = TRUE;
2919   if  (info)
2920     {
2921       res = g_file_set_attributes_from_info (destination,
2922                                              info,
2923                                              G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2924                                              cancellable,
2925                                              error);
2926       g_object_unref (info);
2927     }
2928
2929   return res;
2930 }
2931
2932 /* 256k minus malloc overhead */
2933 #define STREAM_BUFFER_SIZE (1024*256 - 2 *sizeof(gpointer))
2934
2935 static gboolean
2936 copy_stream_with_progress (GInputStream           *in,
2937                            GOutputStream          *out,
2938                            GFile                  *source,
2939                            GCancellable           *cancellable,
2940                            GFileProgressCallback   progress_callback,
2941                            gpointer                progress_callback_data,
2942                            GError                **error)
2943 {
2944   gssize n_read;
2945   gsize n_written;
2946   goffset current_size;
2947   char *buffer;
2948   gboolean res;
2949   goffset total_size;
2950   GFileInfo *info;
2951
2952   total_size = -1;
2953   /* avoid performance impact of querying total size when it's not needed */
2954   if (progress_callback)
2955     {
2956       info = g_file_input_stream_query_info (G_FILE_INPUT_STREAM (in),
2957                                              G_FILE_ATTRIBUTE_STANDARD_SIZE,
2958                                              cancellable, NULL);
2959       if (info)
2960         {
2961           if (g_file_info_has_attribute (info, G_FILE_ATTRIBUTE_STANDARD_SIZE))
2962             total_size = g_file_info_get_size (info);
2963           g_object_unref (info);
2964         }
2965
2966       if (total_size == -1)
2967         {
2968           info = g_file_query_info (source,
2969                                     G_FILE_ATTRIBUTE_STANDARD_SIZE,
2970                                     G_FILE_QUERY_INFO_NONE,
2971                                     cancellable, NULL);
2972           if (info)
2973             {
2974               if (g_file_info_has_attribute (info, G_FILE_ATTRIBUTE_STANDARD_SIZE))
2975                 total_size = g_file_info_get_size (info);
2976               g_object_unref (info);
2977             }
2978         }
2979     }
2980
2981   if (total_size == -1)
2982     total_size = 0;
2983
2984   buffer = g_malloc0 (STREAM_BUFFER_SIZE);
2985   current_size = 0;
2986   res = TRUE;
2987   while (TRUE)
2988     {
2989       n_read = g_input_stream_read (in, buffer, STREAM_BUFFER_SIZE, cancellable, error);
2990       if (n_read == -1)
2991         {
2992           res = FALSE;
2993           break;
2994         }
2995
2996       if (n_read == 0)
2997         break;
2998
2999       current_size += n_read;
3000
3001       res = g_output_stream_write_all (out, buffer, n_read, &n_written, cancellable, error);
3002       if (!res)
3003         break;
3004
3005       if (progress_callback)
3006         progress_callback (current_size, total_size, progress_callback_data);
3007     }
3008   g_free (buffer);
3009
3010   /* Make sure we send full copied size */
3011   if (progress_callback)
3012     progress_callback (current_size, total_size, progress_callback_data);
3013
3014   return res;
3015 }
3016
3017 #ifdef HAVE_COPY_FILE_RANGE
3018 static gboolean
3019 do_copy_file_range (int      fd_in,
3020                     loff_t  *off_in,
3021                     int      fd_out,
3022                     loff_t  *off_out,
3023                     size_t   len,
3024                     size_t  *bytes_transferred,
3025                     GError **error)
3026 {
3027   ssize_t result;
3028
3029   do
3030     {
3031       result = copy_file_range (fd_in, off_in, fd_out, off_out, len, 0);
3032
3033       if (result == -1)
3034         {
3035           int errsv = errno;
3036
3037           if (errsv == EINTR)
3038             {
3039               continue;
3040             }
3041           else if (errsv == ENOSYS || errsv == EINVAL || errsv == EOPNOTSUPP || errsv == EXDEV)
3042             {
3043               g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
3044                                    _("Copy file range not supported"));
3045             }
3046           else
3047             {
3048               g_set_error (error, G_IO_ERROR,
3049                            g_io_error_from_errno (errsv),
3050                            _("Error splicing file: %s"),
3051                            g_strerror (errsv));
3052             }
3053
3054           return FALSE;
3055         }
3056     } while (result == -1);
3057
3058   g_assert (result >= 0);
3059   *bytes_transferred = result;
3060
3061   return TRUE;
3062 }
3063
3064 static gboolean
3065 copy_file_range_with_progress (GInputStream           *in,
3066                                GFileInfo              *in_info,
3067                                GOutputStream          *out,
3068                                GCancellable           *cancellable,
3069                                GFileProgressCallback   progress_callback,
3070                                gpointer                progress_callback_data,
3071                                GError                **error)
3072 {
3073   goffset total_size, last_notified_size;
3074   size_t copy_len;
3075   loff_t offset_in;
3076   loff_t offset_out;
3077   int fd_in, fd_out;
3078
3079   fd_in = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (in));
3080   fd_out = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (out));
3081
3082   g_assert (g_file_info_has_attribute (in_info, G_FILE_ATTRIBUTE_STANDARD_SIZE));
3083   total_size = g_file_info_get_size (in_info);
3084
3085   /* Bail out if the reported size of the file is zero. It might be zero, but it
3086    * might also just be a kernel file in /proc. They report their file size as
3087    * zero, but then have data when you start reading. Go to the fallback code
3088    * path for those. */
3089   if (total_size == 0)
3090     {
3091       g_set_error (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
3092                    _("Copy file range not supported"));
3093       return FALSE;
3094     }
3095
3096   offset_in = offset_out = 0;
3097   copy_len = total_size;
3098   last_notified_size = 0;
3099
3100   /* Call copy_file_range() in a loop until the whole contents are copied. For
3101    * smaller files, this loop will iterate only once. For larger files, the
3102    * kernel (at least, kernel 6.1.6) will return after 2GB anyway, so that gives
3103    * us more loop iterations and more progress reporting. */
3104   while (copy_len > 0)
3105     {
3106       size_t n_copied;
3107
3108       if (g_cancellable_set_error_if_cancelled (cancellable, error) ||
3109           !do_copy_file_range (fd_in, &offset_in, fd_out, &offset_out, copy_len, &n_copied, error))
3110         return FALSE;
3111
3112       if (n_copied == 0)
3113         break;
3114
3115       g_assert (n_copied <= copy_len);
3116       copy_len -= n_copied;
3117
3118       if (progress_callback)
3119         {
3120           progress_callback (offset_in, total_size, progress_callback_data);
3121           last_notified_size = total_size;
3122         }
3123     }
3124
3125   /* Make sure we send full copied size */
3126   if (progress_callback && last_notified_size != total_size)
3127     progress_callback (offset_in, total_size, progress_callback_data);
3128
3129   return TRUE;
3130 }
3131 #endif  /* HAVE_COPY_FILE_RANGE */
3132
3133 #ifdef HAVE_SPLICE
3134
3135 static gboolean
3136 do_splice (int     fd_in,
3137            loff_t *off_in,
3138            int     fd_out,
3139            loff_t *off_out,
3140            size_t  len,
3141            long   *bytes_transferd,
3142            GError **error)
3143 {
3144   long result;
3145
3146 retry:
3147   result = splice (fd_in, off_in, fd_out, off_out, len, SPLICE_F_MORE);
3148
3149   if (result == -1)
3150     {
3151       int errsv = errno;
3152
3153       if (errsv == EINTR)
3154         goto retry;
3155       else if (errsv == ENOSYS || errsv == EINVAL || errsv == EOPNOTSUPP)
3156         g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
3157                              _("Splice not supported"));
3158       else
3159         g_set_error (error, G_IO_ERROR,
3160                      g_io_error_from_errno (errsv),
3161                      _("Error splicing file: %s"),
3162                      g_strerror (errsv));
3163
3164       return FALSE;
3165     }
3166
3167   *bytes_transferd = result;
3168   return TRUE;
3169 }
3170
3171 static gboolean
3172 splice_stream_with_progress (GInputStream           *in,
3173                              GFileInfo              *in_info,
3174                              GOutputStream          *out,
3175                              GCancellable           *cancellable,
3176                              GFileProgressCallback   progress_callback,
3177                              gpointer                progress_callback_data,
3178                              GError                **error)
3179 {
3180   int buffer[2] = { -1, -1 };
3181   int buffer_size;
3182   gboolean res;
3183   goffset total_size;
3184   loff_t offset_in;
3185   loff_t offset_out;
3186   int fd_in, fd_out;
3187
3188   fd_in = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (in));
3189   fd_out = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (out));
3190
3191   if (!g_unix_open_pipe (buffer, O_CLOEXEC, error))
3192     return FALSE;
3193
3194   /* Try a 1MiB buffer for improved throughput. If that fails, use the default
3195    * pipe size. See: https://bugzilla.gnome.org/791457 */
3196   buffer_size = fcntl (buffer[1], F_SETPIPE_SZ, 1024 * 1024);
3197   if (buffer_size <= 0)
3198     {
3199       buffer_size = fcntl (buffer[1], F_GETPIPE_SZ);
3200       if (buffer_size <= 0)
3201         {
3202           /* If #F_GETPIPE_SZ isn’t available, assume we’re on Linux < 2.6.35,
3203            * but ≥ 2.6.11, meaning the pipe capacity is 64KiB. Ignore the
3204            * possibility of running on Linux < 2.6.11 (where the capacity was
3205            * the system page size, typically 4KiB) because it’s ancient.
3206            * See pipe(7). */
3207           buffer_size = 1024 * 64;
3208         }
3209     }
3210
3211   g_assert (buffer_size > 0);
3212
3213   total_size = -1;
3214   /* avoid performance impact of querying total size when it's not needed */
3215   if (progress_callback)
3216     {
3217       g_assert (g_file_info_has_attribute (in_info, G_FILE_ATTRIBUTE_STANDARD_SIZE));
3218       total_size = g_file_info_get_size (in_info);
3219     }
3220
3221   if (total_size == -1)
3222     total_size = 0;
3223
3224   offset_in = offset_out = 0;
3225   res = FALSE;
3226   while (TRUE)
3227     {
3228       long n_read;
3229       long n_written;
3230
3231       if (g_cancellable_set_error_if_cancelled (cancellable, error))
3232         break;
3233
3234       if (!do_splice (fd_in, &offset_in, buffer[1], NULL, buffer_size, &n_read, error))
3235         break;
3236
3237       if (n_read == 0)
3238         {
3239           res = TRUE;
3240           break;
3241         }
3242
3243       while (n_read > 0)
3244         {
3245           if (g_cancellable_set_error_if_cancelled (cancellable, error))
3246             goto out;
3247
3248           if (!do_splice (buffer[0], NULL, fd_out, &offset_out, n_read, &n_written, error))
3249             goto out;
3250
3251           n_read -= n_written;
3252         }
3253
3254       if (progress_callback)
3255         progress_callback (offset_in, total_size, progress_callback_data);
3256     }
3257
3258   /* Make sure we send full copied size */
3259   if (progress_callback)
3260     progress_callback (offset_in, total_size, progress_callback_data);
3261
3262   if (!g_close (buffer[0], error))
3263     goto out;
3264   buffer[0] = -1;
3265   if (!g_close (buffer[1], error))
3266     goto out;
3267   buffer[1] = -1;
3268  out:
3269   if (buffer[0] != -1)
3270     (void) g_close (buffer[0], NULL);
3271   if (buffer[1] != -1)
3272     (void) g_close (buffer[1], NULL);
3273
3274   return res;
3275 }
3276 #endif
3277
3278 #ifdef __linux__
3279 static gboolean
3280 btrfs_reflink_with_progress (GInputStream           *in,
3281                              GFileInfo              *in_info,
3282                              GOutputStream          *out,
3283                              GFileInfo              *info,
3284                              GCancellable           *cancellable,
3285                              GFileProgressCallback   progress_callback,
3286                              gpointer                progress_callback_data,
3287                              GError                **error)
3288 {
3289   goffset total_size;
3290   int fd_in, fd_out;
3291   int ret, errsv;
3292
3293   fd_in = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (in));
3294   fd_out = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (out));
3295
3296   total_size = -1;
3297   /* avoid performance impact of querying total size when it's not needed */
3298   if (progress_callback)
3299     {
3300       g_assert (g_file_info_has_attribute (in_info, G_FILE_ATTRIBUTE_STANDARD_SIZE));
3301       total_size = g_file_info_get_size (in_info);
3302     }
3303
3304   if (total_size == -1)
3305     total_size = 0;
3306
3307   /* Btrfs clone ioctl properties:
3308    *  - Works at the inode level
3309    *  - Doesn't work with directories
3310    *  - Always follows symlinks (source and destination)
3311    *
3312    * By the time we get here, *in and *out are both regular files */
3313   ret = ioctl (fd_out, BTRFS_IOC_CLONE, fd_in);
3314   errsv = errno;
3315
3316   if (ret < 0)
3317     {
3318       if (errsv == EXDEV)
3319         g_set_error_literal (error, G_IO_ERROR,
3320                              G_IO_ERROR_NOT_SUPPORTED,
3321                              _("Copy (reflink/clone) between mounts is not supported"));
3322       else if (errsv == EINVAL)
3323         g_set_error_literal (error, G_IO_ERROR,
3324                              G_IO_ERROR_NOT_SUPPORTED,
3325                              _("Copy (reflink/clone) is not supported or invalid"));
3326       else
3327         /* Most probably something odd happened; retry with fallback */
3328         g_set_error_literal (error, G_IO_ERROR,
3329                              G_IO_ERROR_NOT_SUPPORTED,
3330                              _("Copy (reflink/clone) is not supported or didn’t work"));
3331       /* We retry with fallback for all error cases because Btrfs is currently
3332        * unstable, and so we can't trust it to do clone properly.
3333        * In addition, any hard errors here would cause the same failure in the
3334        * fallback manual copy as well. */
3335       return FALSE;
3336     }
3337
3338   /* Make sure we send full copied size */
3339   if (progress_callback)
3340     progress_callback (total_size, total_size, progress_callback_data);
3341
3342   return TRUE;
3343 }
3344 #endif
3345
3346 static gboolean
3347 file_copy_fallback (GFile                  *source,
3348                     GFile                  *destination,
3349                     GFileCopyFlags          flags,
3350                     GCancellable           *cancellable,
3351                     GFileProgressCallback   progress_callback,
3352                     gpointer                progress_callback_data,
3353                     GError                **error)
3354 {
3355   gboolean ret = FALSE;
3356   GFileInputStream *file_in = NULL;
3357   GInputStream *in = NULL;
3358   GOutputStream *out = NULL;
3359   GFileInfo *info = NULL;
3360   const char *target;
3361   char *attrs_to_read;
3362   gboolean do_set_attributes = FALSE;
3363   GFileCreateFlags create_flags;
3364   GError *tmp_error = NULL;
3365
3366   /* need to know the file type */
3367   info = g_file_query_info (source,
3368                             G_FILE_ATTRIBUTE_STANDARD_TYPE "," G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET,
3369                             G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3370                             cancellable,
3371                             error);
3372   if (!info)
3373     goto out;
3374
3375   /* Maybe copy the symlink? */
3376   if ((flags & G_FILE_COPY_NOFOLLOW_SYMLINKS) &&
3377       g_file_info_get_file_type (info) == G_FILE_TYPE_SYMBOLIC_LINK)
3378     {
3379       target = g_file_info_get_symlink_target (info);
3380       if (target)
3381         {
3382           if (!copy_symlink (destination, flags, cancellable, target, error))
3383             goto out;
3384
3385           ret = TRUE;
3386           goto out;
3387         }
3388         /* ... else fall back on a regular file copy */
3389     }
3390   /* Handle "special" files (pipes, device nodes, ...)? */
3391   else if (g_file_info_get_file_type (info) == G_FILE_TYPE_SPECIAL)
3392     {
3393       /* FIXME: could try to recreate device nodes and others? */
3394       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
3395                            _("Can’t copy special file"));
3396       goto out;
3397     }
3398
3399   /* Everything else should just fall back on a regular copy. */
3400
3401   file_in = open_source_for_copy (source, destination, flags, cancellable, error);
3402   if (!file_in)
3403     goto out;
3404   in = G_INPUT_STREAM (file_in);
3405
3406   attrs_to_read = g_file_build_attribute_list_for_copy (destination, flags,
3407                                                         cancellable, error);
3408   if (!attrs_to_read)
3409     goto out;
3410
3411   /* Ok, ditch the previous lightweight info (on Unix we just
3412    * called lstat()); at this point we gather all the information
3413    * we need about the source from the opened file descriptor.
3414    */
3415   g_object_unref (info);
3416
3417   info = g_file_input_stream_query_info (file_in, attrs_to_read,
3418                                          cancellable, &tmp_error);
3419   if (!info)
3420     {
3421       /* Not all gvfs backends implement query_info_on_read(), we
3422        * can just fall back to the pathname again.
3423        * https://bugzilla.gnome.org/706254
3424        */
3425       if (g_error_matches (tmp_error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED))
3426         {
3427           g_clear_error (&tmp_error);
3428           info = g_file_query_info (source, attrs_to_read, G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3429                                     cancellable, error);
3430         }
3431       else
3432         {
3433           g_free (attrs_to_read);
3434           g_propagate_error (error, tmp_error);
3435           goto out;
3436         }
3437     }
3438   g_free (attrs_to_read);
3439   if (!info)
3440     goto out;
3441
3442   do_set_attributes = TRUE;
3443
3444   /* In the local file path, we pass down the source info which
3445    * includes things like unix::mode, to ensure that the target file
3446    * is not created with different permissions from the source file.
3447    *
3448    * If a future API like g_file_replace_with_info() is added, switch
3449    * this code to use that.
3450    *
3451    * Use %G_FILE_CREATE_PRIVATE unless
3452    *  - we were told to create the file with default permissions (i.e. the
3453    *    process’ umask),
3454    *  - or if the source file is on a file system which doesn’t support
3455    *    `unix::mode` (in which case it probably also makes sense to create the
3456    *    destination with default permissions because the source cannot be
3457    *    private),
3458    *  - or if the destination file is a `GLocalFile`, in which case we can
3459    *    directly open() it with the permissions from the source file.
3460    */
3461   create_flags = G_FILE_CREATE_NONE;
3462   if (!(flags & G_FILE_COPY_TARGET_DEFAULT_PERMS) &&
3463       g_file_info_has_attribute (info, G_FILE_ATTRIBUTE_UNIX_MODE) &&
3464       !G_IS_LOCAL_FILE (destination))
3465     create_flags |= G_FILE_CREATE_PRIVATE;
3466   if (flags & G_FILE_COPY_OVERWRITE)
3467     create_flags |= G_FILE_CREATE_REPLACE_DESTINATION;
3468
3469   if (G_IS_LOCAL_FILE (destination))
3470     {
3471       if (flags & G_FILE_COPY_OVERWRITE)
3472         out = (GOutputStream*)_g_local_file_output_stream_replace (_g_local_file_get_filename (G_LOCAL_FILE (destination)),
3473                                                                    FALSE, NULL,
3474                                                                    flags & G_FILE_COPY_BACKUP,
3475                                                                    create_flags,
3476                                                                    (flags & G_FILE_COPY_TARGET_DEFAULT_PERMS) ? NULL : info,
3477                                                                    cancellable, error);
3478       else
3479         out = (GOutputStream*)_g_local_file_output_stream_create (_g_local_file_get_filename (G_LOCAL_FILE (destination)),
3480                                                                   FALSE, create_flags,
3481                                                                   (flags & G_FILE_COPY_TARGET_DEFAULT_PERMS) ? NULL : info,
3482                                                                   cancellable, error);
3483     }
3484   else if (flags & G_FILE_COPY_OVERWRITE)
3485     {
3486       out = (GOutputStream *)g_file_replace (destination,
3487                                              NULL,
3488                                              flags & G_FILE_COPY_BACKUP,
3489                                              create_flags,
3490                                              cancellable, error);
3491     }
3492   else
3493     {
3494       out = (GOutputStream *)g_file_create (destination, create_flags, cancellable, error);
3495     }
3496
3497   if (!out)
3498     goto out;
3499
3500 #ifdef __linux__
3501   if (G_IS_FILE_DESCRIPTOR_BASED (in) && G_IS_FILE_DESCRIPTOR_BASED (out))
3502     {
3503       GError *reflink_err = NULL;
3504
3505       if (!btrfs_reflink_with_progress (in, info, out, info, cancellable,
3506                                         progress_callback, progress_callback_data,
3507                                         &reflink_err))
3508         {
3509           if (g_error_matches (reflink_err, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED))
3510             {
3511               g_clear_error (&reflink_err);
3512             }
3513           else
3514             {
3515               g_propagate_error (error, reflink_err);
3516               goto out;
3517             }
3518         }
3519       else
3520         {
3521           ret = TRUE;
3522           goto out;
3523         }
3524     }
3525 #endif
3526
3527 #ifdef HAVE_COPY_FILE_RANGE
3528   if (G_IS_FILE_DESCRIPTOR_BASED (in) && G_IS_FILE_DESCRIPTOR_BASED (out))
3529     {
3530       GError *copy_file_range_error = NULL;
3531
3532       if (copy_file_range_with_progress (in, info, out, cancellable,
3533                                          progress_callback, progress_callback_data,
3534                                          &copy_file_range_error))
3535         {
3536           ret = TRUE;
3537           goto out;
3538         }
3539       else if (!g_error_matches (copy_file_range_error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED))
3540         {
3541           g_propagate_error (error, g_steal_pointer (&copy_file_range_error));
3542           goto out;
3543         }
3544       else
3545         {
3546           g_clear_error (&copy_file_range_error);
3547         }
3548     }
3549 #endif  /* HAVE_COPY_FILE_RANGE */
3550
3551 #ifdef HAVE_SPLICE
3552   if (G_IS_FILE_DESCRIPTOR_BASED (in) && G_IS_FILE_DESCRIPTOR_BASED (out))
3553     {
3554       GError *splice_err = NULL;
3555
3556       if (!splice_stream_with_progress (in, info, out, cancellable,
3557                                         progress_callback, progress_callback_data,
3558                                         &splice_err))
3559         {
3560           if (g_error_matches (splice_err, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED))
3561             {
3562               g_clear_error (&splice_err);
3563             }
3564           else
3565             {
3566               g_propagate_error (error, splice_err);
3567               goto out;
3568             }
3569         }
3570       else
3571         {
3572           ret = TRUE;
3573           goto out;
3574         }
3575     }
3576
3577 #endif
3578
3579   /* A plain read/write loop */
3580   if (!copy_stream_with_progress (in, out, source, cancellable,
3581                                   progress_callback, progress_callback_data,
3582                                   error))
3583     goto out;
3584
3585   ret = TRUE;
3586  out:
3587   if (in)
3588     {
3589       /* Don't care about errors in source here */
3590       (void) g_input_stream_close (in, cancellable, NULL);
3591       g_object_unref (in);
3592     }
3593
3594   if (out)
3595     {
3596       /* But write errors on close are bad! */
3597       if (!g_output_stream_close (out, cancellable, ret ? error : NULL))
3598         ret = FALSE;
3599       g_object_unref (out);
3600     }
3601
3602   /* Ignore errors here. Failure to copy metadata is not a hard error */
3603   /* TODO: set these attributes /before/ we do the rename() on Unix */
3604   if (ret && do_set_attributes)
3605     {
3606       g_file_set_attributes_from_info (destination,
3607                                        info,
3608                                        G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3609                                        cancellable,
3610                                        NULL);
3611     }
3612
3613   g_clear_object (&info);
3614
3615   return ret;
3616 }
3617
3618 /**
3619  * g_file_copy:
3620  * @source: input #GFile
3621  * @destination: destination #GFile
3622  * @flags: set of #GFileCopyFlags
3623  * @cancellable: (nullable): optional #GCancellable object,
3624  *   %NULL to ignore
3625  * @progress_callback: (nullable) (scope call) (closure progress_callback_data): function to callback with
3626  *   progress information, or %NULL if progress information is not needed
3627  * @progress_callback_data: user data to pass to @progress_callback
3628  * @error: #GError to set on error, or %NULL
3629  *
3630  * Copies the file @source to the location specified by @destination.
3631  * Can not handle recursive copies of directories.
3632  *
3633  * If the flag %G_FILE_COPY_OVERWRITE is specified an already
3634  * existing @destination file is overwritten.
3635  *
3636  * If the flag %G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
3637  * will be copied as symlinks, otherwise the target of the
3638  * @source symlink will be copied.
3639  *
3640  * If the flag %G_FILE_COPY_ALL_METADATA is specified then all the metadata
3641  * that is possible to copy is copied, not just the default subset (which,
3642  * for instance, does not include the owner, see #GFileInfo).
3643  *
3644  * If @cancellable is not %NULL, then the operation can be cancelled by
3645  * triggering the cancellable object from another thread. If the operation
3646  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3647  *
3648  * If @progress_callback is not %NULL, then the operation can be monitored
3649  * by setting this to a #GFileProgressCallback function.
3650  * @progress_callback_data will be passed to this function. It is guaranteed
3651  * that this callback will be called after all data has been transferred with
3652  * the total number of bytes copied during the operation.
3653  *
3654  * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
3655  * is returned, independent on the status of the @destination.
3656  *
3657  * If %G_FILE_COPY_OVERWRITE is not specified and the target exists, then
3658  * the error %G_IO_ERROR_EXISTS is returned.
3659  *
3660  * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
3661  * error is returned. If trying to overwrite a directory with a directory the
3662  * %G_IO_ERROR_WOULD_MERGE error is returned.
3663  *
3664  * If the source is a directory and the target does not exist, or
3665  * %G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
3666  * %G_IO_ERROR_WOULD_RECURSE error is returned.
3667  *
3668  * If you are interested in copying the #GFile object itself (not the on-disk
3669  * file), see g_file_dup().
3670  *
3671  * Returns: %TRUE on success, %FALSE otherwise.
3672  */
3673 gboolean
3674 g_file_copy (GFile                  *source,
3675              GFile                  *destination,
3676              GFileCopyFlags          flags,
3677              GCancellable           *cancellable,
3678              GFileProgressCallback   progress_callback,
3679              gpointer                progress_callback_data,
3680              GError                **error)
3681 {
3682   GFileIface *iface;
3683   GError *my_error;
3684   gboolean res;
3685
3686   g_return_val_if_fail (G_IS_FILE (source), FALSE);
3687   g_return_val_if_fail (G_IS_FILE (destination), FALSE);
3688
3689   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3690     return FALSE;
3691
3692   iface = G_FILE_GET_IFACE (destination);
3693   if (iface->copy)
3694     {
3695       my_error = NULL;
3696       res = (* iface->copy) (source, destination,
3697                              flags, cancellable,
3698                              progress_callback, progress_callback_data,
3699                              &my_error);
3700
3701       if (res)
3702         return TRUE;
3703
3704       if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3705         {
3706           g_propagate_error (error, my_error);
3707               return FALSE;
3708         }
3709       else
3710         g_clear_error (&my_error);
3711     }
3712
3713   /* If the types are different, and the destination method failed
3714    * also try the source method
3715    */
3716   if (G_OBJECT_TYPE (source) != G_OBJECT_TYPE (destination))
3717     {
3718       iface = G_FILE_GET_IFACE (source);
3719
3720       if (iface->copy)
3721         {
3722           my_error = NULL;
3723           res = (* iface->copy) (source, destination,
3724                                  flags, cancellable,
3725                                  progress_callback, progress_callback_data,
3726                                  &my_error);
3727
3728           if (res)
3729             return TRUE;
3730
3731           if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3732             {
3733               g_propagate_error (error, my_error);
3734               return FALSE;
3735             }
3736           else
3737             g_clear_error (&my_error);
3738         }
3739     }
3740
3741   return file_copy_fallback (source, destination, flags, cancellable,
3742                              progress_callback, progress_callback_data,
3743                              error);
3744 }
3745
3746 /**
3747  * g_file_copy_async:
3748  * @source: input #GFile
3749  * @destination: destination #GFile
3750  * @flags: set of #GFileCopyFlags
3751  * @io_priority: the [I/O priority][io-priority] of the request
3752  * @cancellable: (nullable): optional #GCancellable object,
3753  *   %NULL to ignore
3754  * @progress_callback: (nullable) (scope notified) (closure progress_callback_data):
3755  *   function to callback with progress information, or %NULL if
3756  *   progress information is not needed
3757  * @progress_callback_data: user data to pass to @progress_callback
3758  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
3759  *   to call when the request is satisfied
3760  * @user_data: the data to pass to callback
3761  *
3762  * Copies the file @source to the location specified by @destination
3763  * asynchronously. For details of the behaviour, see g_file_copy().
3764  *
3765  * If @progress_callback is not %NULL, then that function that will be called
3766  * just like in g_file_copy(). The callback will run in the default main context
3767  * of the thread calling g_file_copy_async() — the same context as @callback is
3768  * run in.
3769  *
3770  * When the operation is finished, @callback will be called. You can then call
3771  * g_file_copy_finish() to get the result of the operation.
3772  */
3773 void
3774 g_file_copy_async (GFile                  *source,
3775                    GFile                  *destination,
3776                    GFileCopyFlags          flags,
3777                    int                     io_priority,
3778                    GCancellable           *cancellable,
3779                    GFileProgressCallback   progress_callback,
3780                    gpointer                progress_callback_data,
3781                    GAsyncReadyCallback     callback,
3782                    gpointer                user_data)
3783 {
3784   GFileIface *iface;
3785
3786   g_return_if_fail (G_IS_FILE (source));
3787   g_return_if_fail (G_IS_FILE (destination));
3788
3789   iface = G_FILE_GET_IFACE (source);
3790   (* iface->copy_async) (source,
3791                          destination,
3792                          flags,
3793                          io_priority,
3794                          cancellable,
3795                          progress_callback,
3796                          progress_callback_data,
3797                          callback,
3798                          user_data);
3799 }
3800
3801 /**
3802  * g_file_copy_finish:
3803  * @file: input #GFile
3804  * @res: a #GAsyncResult
3805  * @error: a #GError, or %NULL
3806  *
3807  * Finishes copying the file started with g_file_copy_async().
3808  *
3809  * Returns: a %TRUE on success, %FALSE on error.
3810  */
3811 gboolean
3812 g_file_copy_finish (GFile         *file,
3813                     GAsyncResult  *res,
3814                     GError       **error)
3815 {
3816   GFileIface *iface;
3817
3818   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3819   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), FALSE);
3820
3821   if (g_async_result_legacy_propagate_error (res, error))
3822     return FALSE;
3823
3824   iface = G_FILE_GET_IFACE (file);
3825   return (* iface->copy_finish) (file, res, error);
3826 }
3827
3828 /**
3829  * g_file_move:
3830  * @source: #GFile pointing to the source location
3831  * @destination: #GFile pointing to the destination location
3832  * @flags: set of #GFileCopyFlags
3833  * @cancellable: (nullable): optional #GCancellable object,
3834  *   %NULL to ignore
3835  * @progress_callback: (nullable) (scope call) (closure progress_callback_data): #GFileProgressCallback
3836  *   function for updates
3837  * @progress_callback_data: gpointer to user data for
3838  *   the callback function
3839  * @error: #GError for returning error conditions, or %NULL
3840  *
3841  * Tries to move the file or directory @source to the location specified
3842  * by @destination. If native move operations are supported then this is
3843  * used, otherwise a copy + delete fallback is used. The native
3844  * implementation may support moving directories (for instance on moves
3845  * inside the same filesystem), but the fallback code does not.
3846  *
3847  * If the flag %G_FILE_COPY_OVERWRITE is specified an already
3848  * existing @destination file is overwritten.
3849  *
3850  * If @cancellable is not %NULL, then the operation can be cancelled by
3851  * triggering the cancellable object from another thread. If the operation
3852  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3853  *
3854  * If @progress_callback is not %NULL, then the operation can be monitored
3855  * by setting this to a #GFileProgressCallback function.
3856  * @progress_callback_data will be passed to this function. It is
3857  * guaranteed that this callback will be called after all data has been
3858  * transferred with the total number of bytes copied during the operation.
3859  *
3860  * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
3861  * error is returned, independent on the status of the @destination.
3862  *
3863  * If %G_FILE_COPY_OVERWRITE is not specified and the target exists,
3864  * then the error %G_IO_ERROR_EXISTS is returned.
3865  *
3866  * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
3867  * error is returned. If trying to overwrite a directory with a directory the
3868  * %G_IO_ERROR_WOULD_MERGE error is returned.
3869  *
3870  * If the source is a directory and the target does not exist, or
3871  * %G_FILE_COPY_OVERWRITE is specified and the target is a file, then
3872  * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
3873  * move operation isn't available).
3874  *
3875  * Returns: %TRUE on successful move, %FALSE otherwise.
3876  */
3877 gboolean
3878 g_file_move (GFile                  *source,
3879              GFile                  *destination,
3880              GFileCopyFlags          flags,
3881              GCancellable           *cancellable,
3882              GFileProgressCallback   progress_callback,
3883              gpointer                progress_callback_data,
3884              GError                **error)
3885 {
3886   GFileIface *iface;
3887   GError *my_error;
3888   gboolean res;
3889
3890   g_return_val_if_fail (G_IS_FILE (source), FALSE);
3891   g_return_val_if_fail (G_IS_FILE (destination), FALSE);
3892
3893   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3894     return FALSE;
3895
3896   iface = G_FILE_GET_IFACE (destination);
3897   if (iface->move)
3898     {
3899       my_error = NULL;
3900       res = (* iface->move) (source, destination,
3901                              flags, cancellable,
3902                              progress_callback, progress_callback_data,
3903                              &my_error);
3904
3905       if (res)
3906         return TRUE;
3907
3908       if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3909         {
3910           g_propagate_error (error, my_error);
3911           return FALSE;
3912         }
3913       else
3914         g_clear_error (&my_error);
3915     }
3916
3917   /* If the types are different, and the destination method failed
3918    * also try the source method
3919    */
3920   if (G_OBJECT_TYPE (source) != G_OBJECT_TYPE (destination))
3921     {
3922       iface = G_FILE_GET_IFACE (source);
3923
3924       if (iface->move)
3925         {
3926           my_error = NULL;
3927           res = (* iface->move) (source, destination,
3928                                  flags, cancellable,
3929                                  progress_callback, progress_callback_data,
3930                                  &my_error);
3931
3932           if (res)
3933             return TRUE;
3934
3935           if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3936             {
3937               g_propagate_error (error, my_error);
3938               return FALSE;
3939             }
3940           else
3941             g_clear_error (&my_error);
3942         }
3943     }
3944
3945   if (flags & G_FILE_COPY_NO_FALLBACK_FOR_MOVE)
3946     {
3947       g_set_error_literal (error, G_IO_ERROR,
3948                            G_IO_ERROR_NOT_SUPPORTED,
3949                            _("Operation not supported"));
3950       return FALSE;
3951     }
3952
3953   flags |= G_FILE_COPY_ALL_METADATA | G_FILE_COPY_NOFOLLOW_SYMLINKS;
3954   if (!g_file_copy (source, destination, flags, cancellable,
3955                     progress_callback, progress_callback_data,
3956                     error))
3957     return FALSE;
3958
3959   return g_file_delete (source, cancellable, error);
3960 }
3961
3962 /**
3963  * g_file_move_async:
3964  * @source: #GFile pointing to the source location
3965  * @destination: #GFile pointing to the destination location
3966  * @flags: set of #GFileCopyFlags
3967  * @io_priority: the [I/O priority][io-priority] of the request
3968  * @cancellable: (nullable): optional #GCancellable object,
3969  *   %NULL to ignore
3970  * @progress_callback: (nullable) (scope call) (closure progress_callback_data):
3971  *   #GFileProgressCallback function for updates
3972  * @progress_callback_data: gpointer to user data for the callback function
3973  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
3974  *   to call when the request is satisfied
3975  * @user_data: the data to pass to callback function
3976  *
3977  * Asynchronously moves a file @source to the location of @destination. For details of the behaviour, see g_file_move().
3978  *
3979  * If @progress_callback is not %NULL, then that function that will be called
3980  * just like in g_file_move(). The callback will run in the default main context
3981  * of the thread calling g_file_move_async() — the same context as @callback is
3982  * run in.
3983  *
3984  * When the operation is finished, @callback will be called. You can then call
3985  * g_file_move_finish() to get the result of the operation.
3986  *
3987  * Since: 2.72
3988  */
3989 void
3990 g_file_move_async (GFile                *source,
3991                    GFile                *destination,
3992                    GFileCopyFlags        flags,
3993                    int                   io_priority,
3994                    GCancellable         *cancellable,
3995                    GFileProgressCallback progress_callback,
3996                    gpointer              progress_callback_data,
3997                    GAsyncReadyCallback   callback,
3998                    gpointer              user_data)
3999 {
4000   GFileIface *iface;
4001
4002   g_return_if_fail (G_IS_FILE (source));
4003   g_return_if_fail (G_IS_FILE (destination));
4004   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
4005
4006   iface = G_FILE_GET_IFACE (source);
4007   (* iface->move_async) (source,
4008                          destination,
4009                          flags,
4010                          io_priority,
4011                          cancellable,
4012                          progress_callback,
4013                          progress_callback_data,
4014                          callback,
4015                          user_data);
4016 }
4017
4018 /**
4019  * g_file_move_finish:
4020  * @file: input source #GFile
4021  * @result: a #GAsyncResult
4022  * @error: a #GError, or %NULL
4023  *
4024  * Finishes an asynchronous file movement, started with
4025  * g_file_move_async().
4026  *
4027  * Returns: %TRUE on successful file move, %FALSE otherwise.
4028  *
4029  * Since: 2.72
4030  */
4031 gboolean
4032 g_file_move_finish (GFile         *file,
4033                     GAsyncResult  *result,
4034                     GError       **error)
4035 {
4036   GFileIface *iface;
4037
4038   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4039   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4040   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
4041
4042   iface = G_FILE_GET_IFACE (file);
4043   return (* iface->move_finish) (file, result, error);
4044 }
4045
4046 /**
4047  * g_file_make_directory:
4048  * @file: input #GFile
4049  * @cancellable: (nullable): optional #GCancellable object,
4050  *   %NULL to ignore
4051  * @error: a #GError, or %NULL
4052  *
4053  * Creates a directory. Note that this will only create a child directory
4054  * of the immediate parent directory of the path or URI given by the #GFile.
4055  * To recursively create directories, see g_file_make_directory_with_parents().
4056  * This function will fail if the parent directory does not exist, setting
4057  * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
4058  * creating directories, this function will fail, setting @error to
4059  * %G_IO_ERROR_NOT_SUPPORTED.
4060  *
4061  * For a local #GFile the newly created directory will have the default
4062  * (current) ownership and permissions of the current process.
4063  *
4064  * If @cancellable is not %NULL, then the operation can be cancelled by
4065  * triggering the cancellable object from another thread. If the operation
4066  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4067  *
4068  * Returns: %TRUE on successful creation, %FALSE otherwise.
4069  */
4070 gboolean
4071 g_file_make_directory (GFile         *file,
4072                        GCancellable  *cancellable,
4073                        GError       **error)
4074 {
4075   GFileIface *iface;
4076
4077   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4078
4079   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4080     return FALSE;
4081
4082   iface = G_FILE_GET_IFACE (file);
4083
4084   if (iface->make_directory == NULL)
4085     {
4086       g_set_error_literal (error, G_IO_ERROR,
4087                            G_IO_ERROR_NOT_SUPPORTED,
4088                            _("Operation not supported"));
4089       return FALSE;
4090     }
4091
4092   return (* iface->make_directory) (file, cancellable, error);
4093 }
4094
4095 /**
4096  * g_file_make_directory_async:
4097  * @file: input #GFile
4098  * @io_priority: the [I/O priority][io-priority] of the request
4099  * @cancellable: (nullable): optional #GCancellable object,
4100  *   %NULL to ignore
4101  * @callback: a #GAsyncReadyCallback to call
4102  *   when the request is satisfied
4103  * @user_data: the data to pass to callback function
4104  *
4105  * Asynchronously creates a directory.
4106  *
4107  * Virtual: make_directory_async
4108  * Since: 2.38
4109  */
4110 void
4111 g_file_make_directory_async (GFile               *file,
4112                              int                  io_priority,
4113                              GCancellable        *cancellable,
4114                              GAsyncReadyCallback  callback,
4115                              gpointer             user_data)
4116 {
4117   GFileIface *iface;
4118
4119   g_return_if_fail (G_IS_FILE (file));
4120
4121   iface = G_FILE_GET_IFACE (file);
4122   (* iface->make_directory_async) (file,
4123                                    io_priority,
4124                                    cancellable,
4125                                    callback,
4126                                    user_data);
4127 }
4128
4129 /**
4130  * g_file_make_directory_finish:
4131  * @file: input #GFile
4132  * @result: a #GAsyncResult
4133  * @error: a #GError, or %NULL
4134  *
4135  * Finishes an asynchronous directory creation, started with
4136  * g_file_make_directory_async().
4137  *
4138  * Virtual: make_directory_finish
4139  * Returns: %TRUE on successful directory creation, %FALSE otherwise.
4140  * Since: 2.38
4141  */
4142 gboolean
4143 g_file_make_directory_finish (GFile         *file,
4144                               GAsyncResult  *result,
4145                               GError       **error)
4146 {
4147   GFileIface *iface;
4148
4149   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4150   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4151
4152   iface = G_FILE_GET_IFACE (file);
4153   return (* iface->make_directory_finish) (file, result, error);
4154 }
4155
4156 /**
4157  * g_file_make_directory_with_parents:
4158  * @file: input #GFile
4159  * @cancellable: (nullable): optional #GCancellable object,
4160  *   %NULL to ignore
4161  * @error: a #GError, or %NULL
4162  *
4163  * Creates a directory and any parent directories that may not
4164  * exist similar to 'mkdir -p'. If the file system does not support
4165  * creating directories, this function will fail, setting @error to
4166  * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
4167  * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
4168  * the similar g_mkdir_with_parents().
4169  *
4170  * For a local #GFile the newly created directories will have the default
4171  * (current) ownership and permissions of the current process.
4172  *
4173  * If @cancellable is not %NULL, then the operation can be cancelled by
4174  * triggering the cancellable object from another thread. If the operation
4175  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4176  *
4177  * Returns: %TRUE if all directories have been successfully created, %FALSE
4178  * otherwise.
4179  *
4180  * Since: 2.18
4181  */
4182 gboolean
4183 g_file_make_directory_with_parents (GFile         *file,
4184                                     GCancellable  *cancellable,
4185                                     GError       **error)
4186 {
4187   GFile *work_file = NULL;
4188   GList *list = NULL, *l;
4189   GError *my_error = NULL;
4190
4191   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4192
4193   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4194     return FALSE;
4195
4196   /* Try for the simple case of not having to create any parent
4197    * directories.  If any parent directory needs to be created, this
4198    * call will fail with NOT_FOUND. If that happens, then that value of
4199    * my_error persists into the while loop below.
4200    */
4201   g_file_make_directory (file, cancellable, &my_error);
4202   if (!g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
4203     {
4204       if (my_error)
4205         g_propagate_error (error, my_error);
4206       return my_error == NULL;
4207     }
4208
4209   work_file = g_object_ref (file);
4210
4211   /* Creates the parent directories as needed. In case any particular
4212    * creation operation fails for lack of other parent directories
4213    * (NOT_FOUND), the directory is added to a list of directories to
4214    * create later, and the value of my_error is retained until the next
4215    * iteration of the loop.  After the loop my_error should either be
4216    * empty or contain a real failure condition.
4217    */
4218   while (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
4219     {
4220       GFile *parent_file;
4221
4222       parent_file = g_file_get_parent (work_file);
4223       if (parent_file == NULL)
4224         break;
4225
4226       g_clear_error (&my_error);
4227       g_file_make_directory (parent_file, cancellable, &my_error);
4228       /* Another process may have created the directory in between the
4229        * G_IO_ERROR_NOT_FOUND and now
4230        */
4231       if (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_EXISTS))
4232         g_clear_error (&my_error);
4233
4234       g_object_unref (work_file);
4235       work_file = g_object_ref (parent_file);
4236
4237       if (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
4238         list = g_list_prepend (list, parent_file);  /* Transfer ownership of ref */
4239       else
4240         g_object_unref (parent_file);
4241     }
4242
4243   /* All directories should be able to be created now, so an error at
4244    * this point means the whole operation must fail -- except an EXISTS
4245    * error, which means that another process already created the
4246    * directory in between the previous failure and now.
4247    */
4248   for (l = list; my_error == NULL && l; l = l->next)
4249     {
4250       g_file_make_directory ((GFile *) l->data, cancellable, &my_error);
4251       if (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_EXISTS))
4252         g_clear_error (&my_error);
4253     }
4254
4255   if (work_file)
4256     g_object_unref (work_file);
4257
4258   /* Clean up */
4259   while (list != NULL)
4260     {
4261       g_object_unref ((GFile *) list->data);
4262       list = g_list_remove (list, list->data);
4263     }
4264
4265   /* At this point an error in my_error means a that something
4266    * unexpected failed in either of the loops above, so the whole
4267    * operation must fail.
4268    */
4269   if (my_error != NULL)
4270     {
4271       g_propagate_error (error, my_error);
4272       return FALSE;
4273     }
4274
4275   return g_file_make_directory (file, cancellable, error);
4276 }
4277
4278 /**
4279  * g_file_make_symbolic_link:
4280  * @file: a #GFile with the name of the symlink to create
4281  * @symlink_value: (type filename): a string with the path for the target
4282  *   of the new symlink
4283  * @cancellable: (nullable): optional #GCancellable object,
4284  *   %NULL to ignore
4285  * @error: a #GError
4286  *
4287  * Creates a symbolic link named @file which contains the string
4288  * @symlink_value.
4289  *
4290  * If @cancellable is not %NULL, then the operation can be cancelled by
4291  * triggering the cancellable object from another thread. If the operation
4292  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4293  *
4294  * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
4295  */
4296 gboolean
4297 g_file_make_symbolic_link (GFile         *file,
4298                            const char    *symlink_value,
4299                            GCancellable  *cancellable,
4300                            GError       **error)
4301 {
4302   GFileIface *iface;
4303
4304   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4305   g_return_val_if_fail (symlink_value != NULL, FALSE);
4306
4307   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4308     return FALSE;
4309
4310   if (*symlink_value == '\0')
4311     {
4312       g_set_error_literal (error, G_IO_ERROR,
4313                            G_IO_ERROR_INVALID_ARGUMENT,
4314                            _("Invalid symlink value given"));
4315       return FALSE;
4316     }
4317
4318   iface = G_FILE_GET_IFACE (file);
4319
4320   if (iface->make_symbolic_link == NULL)
4321     {
4322       g_set_error_literal (error, G_IO_ERROR,
4323                            G_IO_ERROR_NOT_SUPPORTED,
4324                            _("Symbolic links not supported"));
4325       return FALSE;
4326     }
4327
4328   return (* iface->make_symbolic_link) (file, symlink_value, cancellable, error);
4329 }
4330
4331 static void
4332 make_symbolic_link_async_thread (GTask         *task,
4333                                  gpointer       object,
4334                                  gpointer       task_data,
4335                                  GCancellable  *cancellable)
4336 {
4337   const char *symlink_value = task_data;
4338   GError *error = NULL;
4339
4340   if (g_file_make_symbolic_link (G_FILE (object), symlink_value, cancellable, &error))
4341     g_task_return_boolean (task, TRUE);
4342   else
4343     g_task_return_error (task, g_steal_pointer (&error));
4344 }
4345
4346 static void
4347 g_file_real_make_symbolic_link_async (GFile               *file,
4348                                       const char          *symlink_value,
4349                                       int                  io_priority,
4350                                       GCancellable        *cancellable,
4351                                       GAsyncReadyCallback  callback,
4352                                       gpointer             user_data)
4353 {
4354   GTask *task;
4355
4356   g_return_if_fail (G_IS_FILE (file));
4357   g_return_if_fail (symlink_value != NULL);
4358   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
4359
4360   task = g_task_new (file, cancellable, callback, user_data);
4361   g_task_set_source_tag (task, g_file_real_make_symbolic_link_async);
4362   g_task_set_task_data (task, g_strdup (symlink_value), g_free);
4363   g_task_set_priority (task, io_priority);
4364
4365   g_task_run_in_thread (task, make_symbolic_link_async_thread);
4366   g_object_unref (task);
4367 }
4368
4369 /**
4370  * g_file_make_symbolic_link_async:
4371  * @file: a #GFile with the name of the symlink to create
4372  * @symlink_value: (type filename): a string with the path for the target
4373  *   of the new symlink
4374  * @io_priority: the [I/O priority][io-priority] of the request
4375  * @cancellable: (nullable): optional #GCancellable object,
4376  *   %NULL to ignore
4377  * @callback: a #GAsyncReadyCallback to call
4378  *   when the request is satisfied
4379  * @user_data: the data to pass to callback function
4380  *
4381  * Asynchronously creates a symbolic link named @file which contains the
4382  * string @symlink_value.
4383  *
4384  * Virtual: make_symbolic_link_async
4385  * Since: 2.74
4386  */
4387 void
4388 g_file_make_symbolic_link_async (GFile               *file,
4389                                  const char          *symlink_value,
4390                                  int                  io_priority,
4391                                  GCancellable        *cancellable,
4392                                  GAsyncReadyCallback  callback,
4393                                  gpointer             user_data)
4394 {
4395   GFileIface *iface;
4396
4397   g_return_if_fail (G_IS_FILE (file));
4398   g_return_if_fail (symlink_value != NULL);
4399   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
4400
4401   iface = G_FILE_GET_IFACE (file);
4402
4403   /* Default implementation should always be provided by GFileIface */
4404   g_assert (iface->make_symbolic_link_async != NULL);
4405
4406   (* iface->make_symbolic_link_async) (file, symlink_value, io_priority,
4407                                        cancellable, callback, user_data);
4408 }
4409
4410 static gboolean
4411 g_file_real_make_symbolic_link_finish (GFile         *file,
4412                                        GAsyncResult  *result,
4413                                        GError       **error)
4414 {
4415   g_return_val_if_fail (g_task_is_valid (result, file), FALSE);
4416
4417   return g_task_propagate_boolean (G_TASK (result), error);
4418 }
4419
4420 /**
4421  * g_file_make_symbolic_link_finish:
4422  * @file: input #GFile
4423  * @result: a #GAsyncResult
4424  * @error: a #GError, or %NULL
4425  *
4426  * Finishes an asynchronous symbolic link creation, started with
4427  * g_file_make_symbolic_link_async().
4428  *
4429  * Virtual: make_symbolic_link_finish
4430  * Returns: %TRUE on successful directory creation, %FALSE otherwise.
4431  * Since: 2.74
4432  */
4433 gboolean
4434 g_file_make_symbolic_link_finish (GFile         *file,
4435                                   GAsyncResult  *result,
4436                                   GError       **error)
4437 {
4438   GFileIface *iface;
4439
4440   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4441   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
4442
4443   iface = G_FILE_GET_IFACE (file);
4444   /* Default implementation should always be provided by GFileIface */
4445   g_assert (iface->make_symbolic_link_finish != NULL);
4446
4447   return (* iface->make_symbolic_link_finish) (file, result, error);
4448 }
4449
4450 /**
4451  * g_file_delete:
4452  * @file: input #GFile
4453  * @cancellable: (nullable): optional #GCancellable object,
4454  *   %NULL to ignore
4455  * @error: a #GError, or %NULL
4456  *
4457  * Deletes a file. If the @file is a directory, it will only be
4458  * deleted if it is empty. This has the same semantics as g_unlink().
4459  *
4460  * If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows
4461  * for deletion to be implemented avoiding
4462  * [time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use):
4463  * |[
4464  * g_autoptr(GError) local_error = NULL;
4465  * if (!g_file_delete (my_file, my_cancellable, &local_error) &&
4466  *     !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
4467  *   {
4468  *     // deletion failed for some reason other than the file not existing:
4469  *     // so report the error
4470  *     g_warning ("Failed to delete %s: %s",
4471  *                g_file_peek_path (my_file), local_error->message);
4472  *   }
4473  * ]|
4474  *
4475  * If @cancellable is not %NULL, then the operation can be cancelled by
4476  * triggering the cancellable object from another thread. If the operation
4477  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4478  *
4479  * Virtual: delete_file
4480  * Returns: %TRUE if the file was deleted. %FALSE otherwise.
4481  */
4482 gboolean
4483 g_file_delete (GFile         *file,
4484                GCancellable  *cancellable,
4485                GError       **error)
4486 {
4487   GFileIface *iface;
4488
4489   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4490
4491   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4492     return FALSE;
4493
4494   iface = G_FILE_GET_IFACE (file);
4495
4496   if (iface->delete_file == NULL)
4497     {
4498       g_set_error_literal (error, G_IO_ERROR,
4499                            G_IO_ERROR_NOT_SUPPORTED,
4500                            _("Operation not supported"));
4501       return FALSE;
4502     }
4503
4504   return (* iface->delete_file) (file, cancellable, error);
4505 }
4506
4507 /**
4508  * g_file_delete_async:
4509  * @file: input #GFile
4510  * @io_priority: the [I/O priority][io-priority] of the request
4511  * @cancellable: (nullable): optional #GCancellable object,
4512  *   %NULL to ignore
4513  * @callback: a #GAsyncReadyCallback to call
4514  *   when the request is satisfied
4515  * @user_data: the data to pass to callback function
4516  *
4517  * Asynchronously delete a file. If the @file is a directory, it will
4518  * only be deleted if it is empty.  This has the same semantics as
4519  * g_unlink().
4520  *
4521  * Virtual: delete_file_async
4522  * Since: 2.34
4523  */
4524 void
4525 g_file_delete_async (GFile               *file,
4526                      int                  io_priority,
4527                      GCancellable        *cancellable,
4528                      GAsyncReadyCallback  callback,
4529                      gpointer             user_data)
4530 {
4531   GFileIface *iface;
4532
4533   g_return_if_fail (G_IS_FILE (file));
4534
4535   iface = G_FILE_GET_IFACE (file);
4536   (* iface->delete_file_async) (file,
4537                                 io_priority,
4538                                 cancellable,
4539                                 callback,
4540                                 user_data);
4541 }
4542
4543 /**
4544  * g_file_delete_finish:
4545  * @file: input #GFile
4546  * @result: a #GAsyncResult
4547  * @error: a #GError, or %NULL
4548  *
4549  * Finishes deleting a file started with g_file_delete_async().
4550  *
4551  * Virtual: delete_file_finish
4552  * Returns: %TRUE if the file was deleted. %FALSE otherwise.
4553  * Since: 2.34
4554  **/
4555 gboolean
4556 g_file_delete_finish (GFile         *file,
4557                       GAsyncResult  *result,
4558                       GError       **error)
4559 {
4560   GFileIface *iface;
4561
4562   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4563   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4564
4565   if (g_async_result_legacy_propagate_error (result, error))
4566     return FALSE;
4567
4568   iface = G_FILE_GET_IFACE (file);
4569   return (* iface->delete_file_finish) (file, result, error);
4570 }
4571
4572 /**
4573  * g_file_trash:
4574  * @file: #GFile to send to trash
4575  * @cancellable: (nullable): optional #GCancellable object,
4576  *   %NULL to ignore
4577  * @error: a #GError, or %NULL
4578  *
4579  * Sends @file to the "Trashcan", if possible. This is similar to
4580  * deleting it, but the user can recover it before emptying the trashcan.
4581  * Not all file systems support trashing, so this call can return the
4582  * %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix
4583  * mount option can be used to disable g_file_trash() support for certain
4584  * mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case.
4585  *
4586  * If @cancellable is not %NULL, then the operation can be cancelled by
4587  * triggering the cancellable object from another thread. If the operation
4588  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4589  *
4590  * Virtual: trash
4591  * Returns: %TRUE on successful trash, %FALSE otherwise.
4592  */
4593 gboolean
4594 g_file_trash (GFile         *file,
4595               GCancellable  *cancellable,
4596               GError       **error)
4597 {
4598   GFileIface *iface;
4599
4600   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4601
4602   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4603     return FALSE;
4604
4605   iface = G_FILE_GET_IFACE (file);
4606
4607   if (iface->trash == NULL)
4608     {
4609       g_set_error_literal (error,
4610                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4611                            _("Trash not supported"));
4612       return FALSE;
4613     }
4614
4615   return (* iface->trash) (file, cancellable, error);
4616 }
4617
4618 /**
4619  * g_file_trash_async:
4620  * @file: input #GFile
4621  * @io_priority: the [I/O priority][io-priority] of the request
4622  * @cancellable: (nullable): optional #GCancellable object,
4623  *   %NULL to ignore
4624  * @callback: a #GAsyncReadyCallback to call
4625  *   when the request is satisfied
4626  * @user_data: the data to pass to callback function
4627  *
4628  * Asynchronously sends @file to the Trash location, if possible.
4629  *
4630  * Virtual: trash_async
4631  * Since: 2.38
4632  */
4633 void
4634 g_file_trash_async (GFile               *file,
4635                     int                  io_priority,
4636                     GCancellable        *cancellable,
4637                     GAsyncReadyCallback  callback,
4638                     gpointer             user_data)
4639 {
4640   GFileIface *iface;
4641
4642   g_return_if_fail (G_IS_FILE (file));
4643
4644   iface = G_FILE_GET_IFACE (file);
4645   (* iface->trash_async) (file,
4646                           io_priority,
4647                           cancellable,
4648                           callback,
4649                           user_data);
4650 }
4651
4652 /**
4653  * g_file_trash_finish:
4654  * @file: input #GFile
4655  * @result: a #GAsyncResult
4656  * @error: a #GError, or %NULL
4657  *
4658  * Finishes an asynchronous file trashing operation, started with
4659  * g_file_trash_async().
4660  *
4661  * Virtual: trash_finish
4662  * Returns: %TRUE on successful trash, %FALSE otherwise.
4663  * Since: 2.38
4664  */
4665 gboolean
4666 g_file_trash_finish (GFile         *file,
4667                      GAsyncResult  *result,
4668                      GError       **error)
4669 {
4670   GFileIface *iface;
4671
4672   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4673   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4674
4675   iface = G_FILE_GET_IFACE (file);
4676   return (* iface->trash_finish) (file, result, error);
4677 }
4678
4679 /**
4680  * g_file_set_display_name:
4681  * @file: input #GFile
4682  * @display_name: a string
4683  * @cancellable: (nullable): optional #GCancellable object,
4684  *   %NULL to ignore
4685  * @error: a #GError, or %NULL
4686  *
4687  * Renames @file to the specified display name.
4688  *
4689  * The display name is converted from UTF-8 to the correct encoding
4690  * for the target filesystem if possible and the @file is renamed to this.
4691  *
4692  * If you want to implement a rename operation in the user interface the
4693  * edit name (%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
4694  * initial value in the rename widget, and then the result after editing
4695  * should be passed to g_file_set_display_name().
4696  *
4697  * On success the resulting converted filename is returned.
4698  *
4699  * If @cancellable is not %NULL, then the operation can be cancelled by
4700  * triggering the cancellable object from another thread. If the operation
4701  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4702  *
4703  * Returns: (transfer full): a #GFile specifying what @file was renamed to,
4704  *   or %NULL if there was an error.
4705  *   Free the returned object with g_object_unref().
4706  */
4707 GFile *
4708 g_file_set_display_name (GFile         *file,
4709                          const gchar   *display_name,
4710                          GCancellable  *cancellable,
4711                          GError       **error)
4712 {
4713   GFileIface *iface;
4714
4715   g_return_val_if_fail (G_IS_FILE (file), NULL);
4716   g_return_val_if_fail (display_name != NULL, NULL);
4717
4718   if (strchr (display_name, G_DIR_SEPARATOR) != NULL)
4719     {
4720       g_set_error (error,
4721                    G_IO_ERROR,
4722                    G_IO_ERROR_INVALID_ARGUMENT,
4723                    _("File names cannot contain “%c”"), G_DIR_SEPARATOR);
4724       return NULL;
4725     }
4726
4727   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4728     return NULL;
4729
4730   iface = G_FILE_GET_IFACE (file);
4731
4732   return (* iface->set_display_name) (file, display_name, cancellable, error);
4733 }
4734
4735 /**
4736  * g_file_set_display_name_async:
4737  * @file: input #GFile
4738  * @display_name: a string
4739  * @io_priority: the [I/O priority][io-priority] of the request
4740  * @cancellable: (nullable): optional #GCancellable object,
4741  *   %NULL to ignore
4742  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
4743  *   to call when the request is satisfied
4744  * @user_data: the data to pass to callback function
4745  *
4746  * Asynchronously sets the display name for a given #GFile.
4747  *
4748  * For more details, see g_file_set_display_name() which is
4749  * the synchronous version of this call.
4750  *
4751  * When the operation is finished, @callback will be called.
4752  * You can then call g_file_set_display_name_finish() to get
4753  * the result of the operation.
4754  */
4755 void
4756 g_file_set_display_name_async (GFile               *file,
4757                                const gchar         *display_name,
4758                                gint                 io_priority,
4759                                GCancellable        *cancellable,
4760                                GAsyncReadyCallback  callback,
4761                                gpointer             user_data)
4762 {
4763   GFileIface *iface;
4764
4765   g_return_if_fail (G_IS_FILE (file));
4766   g_return_if_fail (display_name != NULL);
4767
4768   iface = G_FILE_GET_IFACE (file);
4769   (* iface->set_display_name_async) (file,
4770                                      display_name,
4771                                      io_priority,
4772                                      cancellable,
4773                                      callback,
4774                                      user_data);
4775 }
4776
4777 /**
4778  * g_file_set_display_name_finish:
4779  * @file: input #GFile
4780  * @res: a #GAsyncResult
4781  * @error: a #GError, or %NULL
4782  *
4783  * Finishes setting a display name started with
4784  * g_file_set_display_name_async().
4785  *
4786  * Returns: (transfer full): a #GFile or %NULL on error.
4787  *   Free the returned object with g_object_unref().
4788  */
4789 GFile *
4790 g_file_set_display_name_finish (GFile         *file,
4791                                 GAsyncResult  *res,
4792                                 GError       **error)
4793 {
4794   GFileIface *iface;
4795
4796   g_return_val_if_fail (G_IS_FILE (file), NULL);
4797   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
4798
4799   if (g_async_result_legacy_propagate_error (res, error))
4800     return NULL;
4801
4802   iface = G_FILE_GET_IFACE (file);
4803   return (* iface->set_display_name_finish) (file, res, error);
4804 }
4805
4806 /**
4807  * g_file_query_settable_attributes:
4808  * @file: input #GFile
4809  * @cancellable: (nullable): optional #GCancellable object,
4810  *   %NULL to ignore
4811  * @error: a #GError, or %NULL
4812  *
4813  * Obtain the list of settable attributes for the file.
4814  *
4815  * Returns the type and full attribute name of all the attributes
4816  * that can be set on this file. This doesn't mean setting it will
4817  * always succeed though, you might get an access failure, or some
4818  * specific file may not support a specific attribute.
4819  *
4820  * If @cancellable is not %NULL, then the operation can be cancelled by
4821  * triggering the cancellable object from another thread. If the operation
4822  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4823  *
4824  * Returns: (transfer full): a #GFileAttributeInfoList describing the settable attributes.
4825  *   When you are done with it, release it with
4826  *   g_file_attribute_info_list_unref()
4827  */
4828 GFileAttributeInfoList *
4829 g_file_query_settable_attributes (GFile         *file,
4830                                   GCancellable  *cancellable,
4831                                   GError       **error)
4832 {
4833   GFileIface *iface;
4834   GError *my_error;
4835   GFileAttributeInfoList *list;
4836
4837   g_return_val_if_fail (G_IS_FILE (file), NULL);
4838
4839   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4840     return NULL;
4841
4842   iface = G_FILE_GET_IFACE (file);
4843
4844   if (iface->query_settable_attributes == NULL)
4845     return g_file_attribute_info_list_new ();
4846
4847   my_error = NULL;
4848   list = (* iface->query_settable_attributes) (file, cancellable, &my_error);
4849
4850   if (list == NULL)
4851     {
4852       if (my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_NOT_SUPPORTED)
4853         {
4854           list = g_file_attribute_info_list_new ();
4855           g_error_free (my_error);
4856         }
4857       else
4858         g_propagate_error (error, my_error);
4859     }
4860
4861   return list;
4862 }
4863
4864 /**
4865  * g_file_query_writable_namespaces:
4866  * @file: input #GFile
4867  * @cancellable: (nullable): optional #GCancellable object,
4868  *   %NULL to ignore
4869  * @error: a #GError, or %NULL
4870  *
4871  * Obtain the list of attribute namespaces where new attributes
4872  * can be created by a user. An example of this is extended
4873  * attributes (in the "xattr" namespace).
4874  *
4875  * If @cancellable is not %NULL, then the operation can be cancelled by
4876  * triggering the cancellable object from another thread. If the operation
4877  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4878  *
4879  * Returns: (transfer full): a #GFileAttributeInfoList describing the writable namespaces.
4880  *   When you are done with it, release it with
4881  *   g_file_attribute_info_list_unref()
4882  */
4883 GFileAttributeInfoList *
4884 g_file_query_writable_namespaces (GFile         *file,
4885                                   GCancellable  *cancellable,
4886                                   GError       **error)
4887 {
4888   GFileIface *iface;
4889   GError *my_error;
4890   GFileAttributeInfoList *list;
4891
4892   g_return_val_if_fail (G_IS_FILE (file), NULL);
4893
4894   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4895     return NULL;
4896
4897   iface = G_FILE_GET_IFACE (file);
4898
4899   if (iface->query_writable_namespaces == NULL)
4900     return g_file_attribute_info_list_new ();
4901
4902   my_error = NULL;
4903   list = (* iface->query_writable_namespaces) (file, cancellable, &my_error);
4904
4905   if (list == NULL)
4906     {
4907       g_warn_if_reached();
4908       list = g_file_attribute_info_list_new ();
4909     }
4910
4911   if (my_error != NULL)
4912     {
4913       if (my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_NOT_SUPPORTED)
4914         {
4915           g_error_free (my_error);
4916         }
4917       else
4918         g_propagate_error (error, my_error);
4919     }
4920
4921   return list;
4922 }
4923
4924 /**
4925  * g_file_set_attribute:
4926  * @file: input #GFile
4927  * @attribute: a string containing the attribute's name
4928  * @type: The type of the attribute
4929  * @value_p: (nullable): a pointer to the value (or the pointer
4930  *   itself if the type is a pointer type)
4931  * @flags: a set of #GFileQueryInfoFlags
4932  * @cancellable: (nullable): optional #GCancellable object,
4933  *   %NULL to ignore
4934  * @error: a #GError, or %NULL
4935  *
4936  * Sets an attribute in the file with attribute name @attribute to @value_p.
4937  *
4938  * Some attributes can be unset by setting @type to
4939  * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
4940  *
4941  * If @cancellable is not %NULL, then the operation can be cancelled by
4942  * triggering the cancellable object from another thread. If the operation
4943  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4944  *
4945  * Returns: %TRUE if the attribute was set, %FALSE otherwise.
4946  */
4947 gboolean
4948 g_file_set_attribute (GFile                *file,
4949                       const gchar          *attribute,
4950                       GFileAttributeType    type,
4951                       gpointer              value_p,
4952                       GFileQueryInfoFlags   flags,
4953                       GCancellable         *cancellable,
4954                       GError              **error)
4955 {
4956   GFileIface *iface;
4957
4958   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4959   g_return_val_if_fail (attribute != NULL && *attribute != '\0', FALSE);
4960
4961   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4962     return FALSE;
4963
4964   iface = G_FILE_GET_IFACE (file);
4965
4966   if (iface->set_attribute == NULL)
4967     {
4968       g_set_error_literal (error, G_IO_ERROR,
4969                            G_IO_ERROR_NOT_SUPPORTED,
4970                            _("Operation not supported"));
4971       return FALSE;
4972     }
4973
4974   return (* iface->set_attribute) (file, attribute, type, value_p, flags, cancellable, error);
4975 }
4976
4977 /**
4978  * g_file_set_attributes_from_info:
4979  * @file: input #GFile
4980  * @info: a #GFileInfo
4981  * @flags: #GFileQueryInfoFlags
4982  * @cancellable: (nullable): optional #GCancellable object,
4983  *   %NULL to ignore
4984  * @error: a #GError, or %NULL
4985  *
4986  * Tries to set all attributes in the #GFileInfo on the target
4987  * values, not stopping on the first error.
4988  *
4989  * If there is any error during this operation then @error will
4990  * be set to the first error. Error on particular fields are flagged
4991  * by setting the "status" field in the attribute value to
4992  * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
4993  * also detect further errors.
4994  *
4995  * If @cancellable is not %NULL, then the operation can be cancelled by
4996  * triggering the cancellable object from another thread. If the operation
4997  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4998  *
4999  * Returns: %FALSE if there was any error, %TRUE otherwise.
5000  */
5001 gboolean
5002 g_file_set_attributes_from_info (GFile                *file,
5003                                  GFileInfo            *info,
5004                                  GFileQueryInfoFlags   flags,
5005                                  GCancellable         *cancellable,
5006                                  GError              **error)
5007 {
5008   GFileIface *iface;
5009
5010   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5011   g_return_val_if_fail (G_IS_FILE_INFO (info), FALSE);
5012
5013   if (g_cancellable_set_error_if_cancelled (cancellable, error))
5014     return FALSE;
5015
5016   g_file_info_clear_status (info);
5017
5018   iface = G_FILE_GET_IFACE (file);
5019
5020   return (* iface->set_attributes_from_info) (file,
5021                                               info,
5022                                               flags,
5023                                               cancellable,
5024                                               error);
5025 }
5026
5027 static gboolean
5028 g_file_real_set_attributes_from_info (GFile                *file,
5029                                       GFileInfo            *info,
5030                                       GFileQueryInfoFlags   flags,
5031                                       GCancellable         *cancellable,
5032                                       GError              **error)
5033 {
5034   char **attributes;
5035   int i;
5036   gboolean res;
5037   GFileAttributeValue *value;
5038
5039   res = TRUE;
5040
5041   attributes = g_file_info_list_attributes (info, NULL);
5042
5043   for (i = 0; attributes[i] != NULL; i++)
5044     {
5045       value = _g_file_info_get_attribute_value (info, attributes[i]);
5046
5047       if (value->status != G_FILE_ATTRIBUTE_STATUS_UNSET)
5048         continue;
5049
5050       if (!g_file_set_attribute (file, attributes[i],
5051                                  value->type, _g_file_attribute_value_peek_as_pointer (value),
5052                                  flags, cancellable, error))
5053         {
5054           value->status = G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING;
5055           res = FALSE;
5056           /* Don't set error multiple times */
5057           error = NULL;
5058         }
5059       else
5060         value->status = G_FILE_ATTRIBUTE_STATUS_SET;
5061     }
5062
5063   g_strfreev (attributes);
5064
5065   return res;
5066 }
5067
5068 /**
5069  * g_file_set_attributes_async:
5070  * @file: input #GFile
5071  * @info: a #GFileInfo
5072  * @flags: a #GFileQueryInfoFlags
5073  * @io_priority: the [I/O priority][io-priority] of the request
5074  * @cancellable: (nullable): optional #GCancellable object,
5075  *   %NULL to ignore
5076  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
5077  *   to call when the request is satisfied
5078  * @user_data: the data to pass to callback function
5079  *
5080  * Asynchronously sets the attributes of @file with @info.
5081  *
5082  * For more details, see g_file_set_attributes_from_info(),
5083  * which is the synchronous version of this call.
5084  *
5085  * When the operation is finished, @callback will be called.
5086  * You can then call g_file_set_attributes_finish() to get
5087  * the result of the operation.
5088  */
5089 void
5090 g_file_set_attributes_async (GFile               *file,
5091                              GFileInfo           *info,
5092                              GFileQueryInfoFlags  flags,
5093                              int                  io_priority,
5094                              GCancellable        *cancellable,
5095                              GAsyncReadyCallback  callback,
5096                              gpointer             user_data)
5097 {
5098   GFileIface *iface;
5099
5100   g_return_if_fail (G_IS_FILE (file));
5101   g_return_if_fail (G_IS_FILE_INFO (info));
5102
5103   iface = G_FILE_GET_IFACE (file);
5104   (* iface->set_attributes_async) (file,
5105                                    info,
5106                                    flags,
5107                                    io_priority,
5108                                    cancellable,
5109                                    callback,
5110                                    user_data);
5111 }
5112
5113 /**
5114  * g_file_set_attributes_finish:
5115  * @file: input #GFile
5116  * @result: a #GAsyncResult
5117  * @info: (out) (transfer full): a #GFileInfo
5118  * @error: a #GError, or %NULL
5119  *
5120  * Finishes setting an attribute started in g_file_set_attributes_async().
5121  *
5122  * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
5123  */
5124 gboolean
5125 g_file_set_attributes_finish (GFile         *file,
5126                               GAsyncResult  *result,
5127                               GFileInfo    **info,
5128                               GError       **error)
5129 {
5130   GFileIface *iface;
5131
5132   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5133   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5134
5135   /* No standard handling of errors here, as we must set info even
5136    * on errors
5137    */
5138   iface = G_FILE_GET_IFACE (file);
5139   return (* iface->set_attributes_finish) (file, result, info, error);
5140 }
5141
5142 /**
5143  * g_file_set_attribute_string:
5144  * @file: input #GFile
5145  * @attribute: a string containing the attribute's name
5146  * @value: a string containing the attribute's value
5147  * @flags: #GFileQueryInfoFlags
5148  * @cancellable: (nullable): optional #GCancellable object,
5149  *   %NULL to ignore
5150  * @error: a #GError, or %NULL
5151  *
5152  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
5153  * If @attribute is of a different type, this operation will fail.
5154  *
5155  * If @cancellable is not %NULL, then the operation can be cancelled by
5156  * triggering the cancellable object from another thread. If the operation
5157  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5158  *
5159  * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
5160  */
5161 gboolean
5162 g_file_set_attribute_string (GFile                *file,
5163                              const char           *attribute,
5164                              const char           *value,
5165                              GFileQueryInfoFlags   flags,
5166                              GCancellable         *cancellable,
5167                              GError              **error)
5168 {
5169   return g_file_set_attribute (file, attribute,
5170                                G_FILE_ATTRIBUTE_TYPE_STRING, (gpointer)value,
5171                                flags, cancellable, error);
5172 }
5173
5174 /**
5175  * g_file_set_attribute_byte_string:
5176  * @file: input #GFile
5177  * @attribute: a string containing the attribute's name
5178  * @value: a string containing the attribute's new value
5179  * @flags: a #GFileQueryInfoFlags
5180  * @cancellable: (nullable): optional #GCancellable object,
5181  *   %NULL to ignore
5182  * @error: a #GError, or %NULL
5183  *
5184  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
5185  * If @attribute is of a different type, this operation will fail,
5186  * returning %FALSE.
5187  *
5188  * If @cancellable is not %NULL, then the operation can be cancelled by
5189  * triggering the cancellable object from another thread. If the operation
5190  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5191  *
5192  * Returns: %TRUE if the @attribute was successfully set to @value
5193  *   in the @file, %FALSE otherwise.
5194  */
5195 gboolean
5196 g_file_set_attribute_byte_string  (GFile                *file,
5197                                    const gchar          *attribute,
5198                                    const gchar          *value,
5199                                    GFileQueryInfoFlags   flags,
5200                                    GCancellable         *cancellable,
5201                                    GError              **error)
5202 {
5203   return g_file_set_attribute (file, attribute,
5204                                G_FILE_ATTRIBUTE_TYPE_BYTE_STRING, (gpointer)value,
5205                                flags, cancellable, error);
5206 }
5207
5208 /**
5209  * g_file_set_attribute_uint32:
5210  * @file: input #GFile
5211  * @attribute: a string containing the attribute's name
5212  * @value: a #guint32 containing the attribute's new value
5213  * @flags: a #GFileQueryInfoFlags
5214  * @cancellable: (nullable): optional #GCancellable object,
5215  *   %NULL to ignore
5216  * @error: a #GError, or %NULL
5217  *
5218  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
5219  * If @attribute is of a different type, this operation will fail.
5220  *
5221  * If @cancellable is not %NULL, then the operation can be cancelled by
5222  * triggering the cancellable object from another thread. If the operation
5223  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5224  *
5225  * Returns: %TRUE if the @attribute was successfully set to @value
5226  *   in the @file, %FALSE otherwise.
5227  */
5228 gboolean
5229 g_file_set_attribute_uint32 (GFile                *file,
5230                              const gchar          *attribute,
5231                              guint32               value,
5232                              GFileQueryInfoFlags   flags,
5233                              GCancellable         *cancellable,
5234                              GError              **error)
5235 {
5236   return g_file_set_attribute (file, attribute,
5237                                G_FILE_ATTRIBUTE_TYPE_UINT32, &value,
5238                                flags, cancellable, error);
5239 }
5240
5241 /**
5242  * g_file_set_attribute_int32:
5243  * @file: input #GFile
5244  * @attribute: a string containing the attribute's name
5245  * @value: a #gint32 containing the attribute's new value
5246  * @flags: a #GFileQueryInfoFlags
5247  * @cancellable: (nullable): optional #GCancellable object,
5248  *   %NULL to ignore
5249  * @error: a #GError, or %NULL
5250  *
5251  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
5252  * If @attribute is of a different type, this operation will fail.
5253  *
5254  * If @cancellable is not %NULL, then the operation can be cancelled by
5255  * triggering the cancellable object from another thread. If the operation
5256  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5257  *
5258  * Returns: %TRUE if the @attribute was successfully set to @value
5259  *   in the @file, %FALSE otherwise.
5260  */
5261 gboolean
5262 g_file_set_attribute_int32 (GFile                *file,
5263                             const gchar          *attribute,
5264                             gint32                value,
5265                             GFileQueryInfoFlags   flags,
5266                             GCancellable         *cancellable,
5267                             GError              **error)
5268 {
5269   return g_file_set_attribute (file, attribute,
5270                                G_FILE_ATTRIBUTE_TYPE_INT32, &value,
5271                                flags, cancellable, error);
5272 }
5273
5274 /**
5275  * g_file_set_attribute_uint64:
5276  * @file: input #GFile
5277  * @attribute: a string containing the attribute's name
5278  * @value: a #guint64 containing the attribute's new value
5279  * @flags: a #GFileQueryInfoFlags
5280  * @cancellable: (nullable): optional #GCancellable object,
5281  *   %NULL to ignore
5282  * @error: a #GError, or %NULL
5283  *
5284  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
5285  * If @attribute is of a different type, this operation will fail.
5286  *
5287  * If @cancellable is not %NULL, then the operation can be cancelled by
5288  * triggering the cancellable object from another thread. If the operation
5289  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5290  *
5291  * Returns: %TRUE if the @attribute was successfully set to @value
5292  *   in the @file, %FALSE otherwise.
5293  */
5294 gboolean
5295 g_file_set_attribute_uint64 (GFile                *file,
5296                              const gchar          *attribute,
5297                              guint64               value,
5298                              GFileQueryInfoFlags   flags,
5299                              GCancellable         *cancellable,
5300                              GError              **error)
5301  {
5302   return g_file_set_attribute (file, attribute,
5303                                G_FILE_ATTRIBUTE_TYPE_UINT64, &value,
5304                                flags, cancellable, error);
5305 }
5306
5307 /**
5308  * g_file_set_attribute_int64:
5309  * @file: input #GFile
5310  * @attribute: a string containing the attribute's name
5311  * @value: a #guint64 containing the attribute's new value
5312  * @flags: a #GFileQueryInfoFlags
5313  * @cancellable: (nullable): optional #GCancellable object,
5314  *   %NULL to ignore
5315  * @error: a #GError, or %NULL
5316  *
5317  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
5318  * If @attribute is of a different type, this operation will fail.
5319  *
5320  * If @cancellable is not %NULL, then the operation can be cancelled by
5321  * triggering the cancellable object from another thread. If the operation
5322  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5323  *
5324  * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
5325  */
5326 gboolean
5327 g_file_set_attribute_int64 (GFile                *file,
5328                             const gchar          *attribute,
5329                             gint64                value,
5330                             GFileQueryInfoFlags   flags,
5331                             GCancellable         *cancellable,
5332                             GError              **error)
5333 {
5334   return g_file_set_attribute (file, attribute,
5335                                G_FILE_ATTRIBUTE_TYPE_INT64, &value,
5336                                flags, cancellable, error);
5337 }
5338
5339 /**
5340  * g_file_mount_mountable:
5341  * @file: input #GFile
5342  * @flags: flags affecting the operation
5343  * @mount_operation: (nullable): a #GMountOperation,
5344  *   or %NULL to avoid user interaction
5345  * @cancellable: (nullable): optional #GCancellable object,
5346  *   %NULL to ignore
5347  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
5348  *   to call when the request is satisfied
5349  * @user_data: the data to pass to callback function
5350  *
5351  * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
5352  * Using @mount_operation, you can request callbacks when, for instance,
5353  * passwords are needed during authentication.
5354  *
5355  * If @cancellable is not %NULL, then the operation can be cancelled by
5356  * triggering the cancellable object from another thread. If the operation
5357  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5358  *
5359  * When the operation is finished, @callback will be called.
5360  * You can then call g_file_mount_mountable_finish() to get
5361  * the result of the operation.
5362  */
5363 void
5364 g_file_mount_mountable (GFile               *file,
5365                         GMountMountFlags     flags,
5366                         GMountOperation     *mount_operation,
5367                         GCancellable        *cancellable,
5368                         GAsyncReadyCallback  callback,
5369                         gpointer             user_data)
5370 {
5371   GFileIface *iface;
5372
5373   g_return_if_fail (G_IS_FILE (file));
5374
5375   iface = G_FILE_GET_IFACE (file);
5376
5377   if (iface->mount_mountable == NULL)
5378     {
5379       g_task_report_new_error (file, callback, user_data,
5380                                g_file_mount_mountable,
5381                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
5382                                _("Operation not supported"));
5383       return;
5384     }
5385
5386   (* iface->mount_mountable) (file,
5387                               flags,
5388                               mount_operation,
5389                               cancellable,
5390                               callback,
5391                               user_data);
5392 }
5393
5394 /**
5395  * g_file_mount_mountable_finish:
5396  * @file: input #GFile
5397  * @result: a #GAsyncResult
5398  * @error: a #GError, or %NULL
5399  *
5400  * Finishes a mount operation. See g_file_mount_mountable() for details.
5401  *
5402  * Finish an asynchronous mount operation that was started
5403  * with g_file_mount_mountable().
5404  *
5405  * Returns: (transfer full): a #GFile or %NULL on error.
5406  *   Free the returned object with g_object_unref().
5407  */
5408 GFile *
5409 g_file_mount_mountable_finish (GFile         *file,
5410                                GAsyncResult  *result,
5411                                GError       **error)
5412 {
5413   GFileIface *iface;
5414
5415   g_return_val_if_fail (G_IS_FILE (file), NULL);
5416   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
5417
5418   if (g_async_result_legacy_propagate_error (result, error))
5419     return NULL;
5420   else if (g_async_result_is_tagged (result, g_file_mount_mountable))
5421     return g_task_propagate_pointer (G_TASK (result), error);
5422
5423   iface = G_FILE_GET_IFACE (file);
5424   return (* iface->mount_mountable_finish) (file, result, error);
5425 }
5426
5427 /**
5428  * g_file_unmount_mountable:
5429  * @file: input #GFile
5430  * @flags: flags affecting the operation
5431  * @cancellable: (nullable): optional #GCancellable object,
5432  *   %NULL to ignore
5433  * @callback: (scope async) (nullable) (closure user_data): a #GAsyncReadyCallback
5434  *   to call when the request is satisfied
5435  * @user_data: the data to pass to callback function
5436  *
5437  * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
5438  *
5439  * If @cancellable is not %NULL, then the operation can be cancelled by
5440  * triggering the cancellable object from another thread. If the operation
5441  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5442  *
5443  * When the operation is finished, @callback will be called.
5444  * You can then call g_file_unmount_mountable_finish() to get
5445  * the result of the operation.
5446  *
5447  * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
5448  */
5449 void
5450 g_file_unmount_mountable (GFile               *file,
5451                           GMountUnmountFlags   flags,
5452                           GCancellable        *cancellable,
5453                           GAsyncReadyCallback  callback,
5454                           gpointer             user_data)
5455 {
5456   GFileIface *iface;
5457
5458   g_return_if_fail (G_IS_FILE (file));
5459
5460   iface = G_FILE_GET_IFACE (file);
5461
5462   if (iface->unmount_mountable == NULL)
5463     {
5464       g_task_report_new_error (file, callback, user_data,
5465                                g_file_unmount_mountable_with_operation,
5466                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
5467                                _("Operation not supported"));
5468       return;
5469     }
5470
5471   (* iface->unmount_mountable) (file,
5472                                 flags,
5473                                 cancellable,
5474                                 callback,
5475                                 user_data);
5476 }
5477
5478 /**
5479  * g_file_unmount_mountable_finish:
5480  * @file: input #GFile
5481  * @result: a #GAsyncResult
5482  * @error: a #GError, or %NULL
5483  *
5484  * Finishes an unmount operation, see g_file_unmount_mountable() for details.
5485  *
5486  * Finish an asynchronous unmount operation that was started
5487  * with g_file_unmount_mountable().
5488  *
5489  * Returns: %TRUE if the operation finished successfully.
5490  *   %FALSE otherwise.
5491  *
5492  * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish()
5493  *   instead.
5494  */
5495 gboolean
5496 g_file_unmount_mountable_finish (GFile         *file,
5497                                  GAsyncResult  *result,
5498                                  GError       **error)
5499 {
5500   GFileIface *iface;
5501
5502   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5503   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5504
5505   if (g_async_result_legacy_propagate_error (result, error))
5506     return FALSE;
5507   else if (g_async_result_is_tagged (result, g_file_unmount_mountable_with_operation))
5508     return g_task_propagate_boolean (G_TASK (result), error);
5509
5510   iface = G_FILE_GET_IFACE (file);
5511   return (* iface->unmount_mountable_finish) (file, result, error);
5512 }
5513
5514 /**
5515  * g_file_unmount_mountable_with_operation:
5516  * @file: input #GFile
5517  * @flags: flags affecting the operation
5518  * @mount_operation: (nullable): a #GMountOperation,
5519  *   or %NULL to avoid user interaction
5520  * @cancellable: (nullable): optional #GCancellable object,
5521  *   %NULL to ignore
5522  * @callback: (scope async) (nullable) (closure user_data): a #GAsyncReadyCallback
5523  *   to call when the request is satisfied
5524  * @user_data: the data to pass to callback function
5525  *
5526  * Unmounts a file of type %G_FILE_TYPE_MOUNTABLE.
5527  *
5528  * If @cancellable is not %NULL, then the operation can be cancelled by
5529  * triggering the cancellable object from another thread. If the operation
5530  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5531  *
5532  * When the operation is finished, @callback will be called.
5533  * You can then call g_file_unmount_mountable_finish() to get
5534  * the result of the operation.
5535  *
5536  * Since: 2.22
5537  */
5538 void
5539 g_file_unmount_mountable_with_operation (GFile               *file,
5540                                          GMountUnmountFlags   flags,
5541                                          GMountOperation     *mount_operation,
5542                                          GCancellable        *cancellable,
5543                                          GAsyncReadyCallback  callback,
5544                                          gpointer             user_data)
5545 {
5546   GFileIface *iface;
5547
5548   g_return_if_fail (G_IS_FILE (file));
5549
5550   iface = G_FILE_GET_IFACE (file);
5551
5552   if (iface->unmount_mountable == NULL && iface->unmount_mountable_with_operation == NULL)
5553     {
5554       g_task_report_new_error (file, callback, user_data,
5555                                g_file_unmount_mountable_with_operation,
5556                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
5557                                _("Operation not supported"));
5558       return;
5559     }
5560
5561   if (iface->unmount_mountable_with_operation != NULL)
5562     (* iface->unmount_mountable_with_operation) (file,
5563                                                  flags,
5564                                                  mount_operation,
5565                                                  cancellable,
5566                                                  callback,
5567                                                  user_data);
5568   else
5569     (* iface->unmount_mountable) (file,
5570                                   flags,
5571                                   cancellable,
5572                                   callback,
5573                                   user_data);
5574 }
5575
5576 /**
5577  * g_file_unmount_mountable_with_operation_finish:
5578  * @file: input #GFile
5579  * @result: a #GAsyncResult
5580  * @error: a #GError, or %NULL
5581  *
5582  * Finishes an unmount operation,
5583  * see g_file_unmount_mountable_with_operation() for details.
5584  *
5585  * Finish an asynchronous unmount operation that was started
5586  * with g_file_unmount_mountable_with_operation().
5587  *
5588  * Returns: %TRUE if the operation finished successfully.
5589  *   %FALSE otherwise.
5590  *
5591  * Since: 2.22
5592  */
5593 gboolean
5594 g_file_unmount_mountable_with_operation_finish (GFile         *file,
5595                                                 GAsyncResult  *result,
5596                                                 GError       **error)
5597 {
5598   GFileIface *iface;
5599
5600   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5601   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5602
5603   if (g_async_result_legacy_propagate_error (result, error))
5604     return FALSE;
5605   else if (g_async_result_is_tagged (result, g_file_unmount_mountable_with_operation))
5606     return g_task_propagate_boolean (G_TASK (result), error);
5607
5608   iface = G_FILE_GET_IFACE (file);
5609   if (iface->unmount_mountable_with_operation_finish != NULL)
5610     return (* iface->unmount_mountable_with_operation_finish) (file, result, error);
5611   else
5612     return (* iface->unmount_mountable_finish) (file, result, error);
5613 }
5614
5615 /**
5616  * g_file_eject_mountable:
5617  * @file: input #GFile
5618  * @flags: flags affecting the operation
5619  * @cancellable: (nullable): optional #GCancellable object,
5620  *   %NULL to ignore
5621  * @callback: (scope async) (nullable) (closure user_data): a #GAsyncReadyCallback
5622  *   to call when the request is satisfied
5623  * @user_data: the data to pass to callback function
5624  *
5625  * Starts an asynchronous eject on a mountable.
5626  * When this operation has completed, @callback will be called with
5627  * @user_user data, and the operation can be finalized with
5628  * g_file_eject_mountable_finish().
5629  *
5630  * If @cancellable is not %NULL, then the operation can be cancelled by
5631  * triggering the cancellable object from another thread. If the operation
5632  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5633  *
5634  * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
5635  */
5636 void
5637 g_file_eject_mountable (GFile               *file,
5638                         GMountUnmountFlags   flags,
5639                         GCancellable        *cancellable,
5640                         GAsyncReadyCallback  callback,
5641                         gpointer             user_data)
5642 {
5643   GFileIface *iface;
5644
5645   g_return_if_fail (G_IS_FILE (file));
5646
5647   iface = G_FILE_GET_IFACE (file);
5648
5649   if (iface->eject_mountable == NULL)
5650     {
5651       g_task_report_new_error (file, callback, user_data,
5652                                g_file_eject_mountable_with_operation,
5653                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
5654                                _("Operation not supported"));
5655       return;
5656     }
5657
5658   (* iface->eject_mountable) (file,
5659                               flags,
5660                               cancellable,
5661                               callback,
5662                               user_data);
5663 }
5664
5665 /**
5666  * g_file_eject_mountable_finish:
5667  * @file: input #GFile
5668  * @result: a #GAsyncResult
5669  * @error: a #GError, or %NULL
5670  *
5671  * Finishes an asynchronous eject operation started by
5672  * g_file_eject_mountable().
5673  *
5674  * Returns: %TRUE if the @file was ejected successfully.
5675  *   %FALSE otherwise.
5676  *
5677  * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
5678  *   instead.
5679  */
5680 gboolean
5681 g_file_eject_mountable_finish (GFile         *file,
5682                                GAsyncResult  *result,
5683                                GError       **error)
5684 {
5685   GFileIface *iface;
5686
5687   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5688   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5689
5690   if (g_async_result_legacy_propagate_error (result, error))
5691     return FALSE;
5692   else if (g_async_result_is_tagged (result, g_file_eject_mountable_with_operation))
5693     return g_task_propagate_boolean (G_TASK (result), error);
5694
5695   iface = G_FILE_GET_IFACE (file);
5696   return (* iface->eject_mountable_finish) (file, result, error);
5697 }
5698
5699 /**
5700  * g_file_eject_mountable_with_operation:
5701  * @file: input #GFile
5702  * @flags: flags affecting the operation
5703  * @mount_operation: (nullable): a #GMountOperation,
5704  *   or %NULL to avoid user interaction
5705  * @cancellable: (nullable): optional #GCancellable object,
5706  *   %NULL to ignore
5707  * @callback: (scope async) (nullable) (closure user_data): a #GAsyncReadyCallback
5708  *   to call when the request is satisfied
5709  * @user_data: the data to pass to callback function
5710  *
5711  * Starts an asynchronous eject on a mountable.
5712  * When this operation has completed, @callback will be called with
5713  * @user_user data, and the operation can be finalized with
5714  * g_file_eject_mountable_with_operation_finish().
5715  *
5716  * If @cancellable is not %NULL, then the operation can be cancelled by
5717  * triggering the cancellable object from another thread. If the operation
5718  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5719  *
5720  * Since: 2.22
5721  */
5722 void
5723 g_file_eject_mountable_with_operation (GFile               *file,
5724                                        GMountUnmountFlags   flags,
5725                                        GMountOperation     *mount_operation,
5726                                        GCancellable        *cancellable,
5727                                        GAsyncReadyCallback  callback,
5728                                        gpointer             user_data)
5729 {
5730   GFileIface *iface;
5731
5732   g_return_if_fail (G_IS_FILE (file));
5733
5734   iface = G_FILE_GET_IFACE (file);
5735
5736   if (iface->eject_mountable == NULL && iface->eject_mountable_with_operation == NULL)
5737     {
5738       g_task_report_new_error (file, callback, user_data,
5739                                g_file_eject_mountable_with_operation,
5740                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
5741                                _("Operation not supported"));
5742       return;
5743     }
5744
5745   if (iface->eject_mountable_with_operation != NULL)
5746     (* iface->eject_mountable_with_operation) (file,
5747                                                flags,
5748                                                mount_operation,
5749                                                cancellable,
5750                                                callback,
5751                                                user_data);
5752   else
5753     (* iface->eject_mountable) (file,
5754                                 flags,
5755                                 cancellable,
5756                                 callback,
5757                                 user_data);
5758 }
5759
5760 /**
5761  * g_file_eject_mountable_with_operation_finish:
5762  * @file: input #GFile
5763  * @result: a #GAsyncResult
5764  * @error: a #GError, or %NULL
5765  *
5766  * Finishes an asynchronous eject operation started by
5767  * g_file_eject_mountable_with_operation().
5768  *
5769  * Returns: %TRUE if the @file was ejected successfully.
5770  *   %FALSE otherwise.
5771  *
5772  * Since: 2.22
5773  */
5774 gboolean
5775 g_file_eject_mountable_with_operation_finish (GFile         *file,
5776                                               GAsyncResult  *result,
5777                                               GError       **error)
5778 {
5779   GFileIface *iface;
5780
5781   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5782   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5783
5784   if (g_async_result_legacy_propagate_error (result, error))
5785     return FALSE;
5786   else if (g_async_result_is_tagged (result, g_file_eject_mountable_with_operation))
5787     return g_task_propagate_boolean (G_TASK (result), error);
5788
5789   iface = G_FILE_GET_IFACE (file);
5790   if (iface->eject_mountable_with_operation_finish != NULL)
5791     return (* iface->eject_mountable_with_operation_finish) (file, result, error);
5792   else
5793     return (* iface->eject_mountable_finish) (file, result, error);
5794 }
5795
5796 /**
5797  * g_file_monitor_directory:
5798  * @file: input #GFile
5799  * @flags: a set of #GFileMonitorFlags
5800  * @cancellable: (nullable): optional #GCancellable object,
5801  *   %NULL to ignore
5802  * @error: a #GError, or %NULL
5803  *
5804  * Obtains a directory monitor for the given file.
5805  * This may fail if directory monitoring is not supported.
5806  *
5807  * If @cancellable is not %NULL, then the operation can be cancelled by
5808  * triggering the cancellable object from another thread. If the operation
5809  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5810  *
5811  * It does not make sense for @flags to contain
5812  * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
5813  * directories.  It is not possible to monitor all the files in a
5814  * directory for changes made via hard links; if you want to do this then
5815  * you must register individual watches with g_file_monitor().
5816  *
5817  * Virtual: monitor_dir
5818  * Returns: (transfer full): a #GFileMonitor for the given @file,
5819  *   or %NULL on error.
5820  *   Free the returned object with g_object_unref().
5821  */
5822 GFileMonitor *
5823 g_file_monitor_directory (GFile              *file,
5824                           GFileMonitorFlags   flags,
5825                           GCancellable       *cancellable,
5826                           GError            **error)
5827 {
5828   GFileIface *iface;
5829
5830   g_return_val_if_fail (G_IS_FILE (file), NULL);
5831   g_return_val_if_fail (~flags & G_FILE_MONITOR_WATCH_HARD_LINKS, NULL);
5832
5833   if (g_cancellable_set_error_if_cancelled (cancellable, error))
5834     return NULL;
5835
5836   iface = G_FILE_GET_IFACE (file);
5837
5838   if (iface->monitor_dir == NULL)
5839     {
5840       g_set_error_literal (error, G_IO_ERROR,
5841                            G_IO_ERROR_NOT_SUPPORTED,
5842                            _("Operation not supported"));
5843       return NULL;
5844     }
5845
5846   return (* iface->monitor_dir) (file, flags, cancellable, error);
5847 }
5848
5849 /**
5850  * g_file_monitor_file:
5851  * @file: input #GFile
5852  * @flags: a set of #GFileMonitorFlags
5853  * @cancellable: (nullable): optional #GCancellable object,
5854  *   %NULL to ignore
5855  * @error: a #GError, or %NULL
5856  *
5857  * Obtains a file monitor for the given file. If no file notification
5858  * mechanism exists, then regular polling of the file is used.
5859  *
5860  * If @cancellable is not %NULL, then the operation can be cancelled by
5861  * triggering the cancellable object from another thread. If the operation
5862  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5863  *
5864  * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
5865  * will also attempt to report changes made to the file via another
5866  * filename (ie, a hard link). Without this flag, you can only rely on
5867  * changes made through the filename contained in @file to be
5868  * reported. Using this flag may result in an increase in resource
5869  * usage, and may not have any effect depending on the #GFileMonitor
5870  * backend and/or filesystem type.
5871  *
5872  * Returns: (transfer full): a #GFileMonitor for the given @file,
5873  *   or %NULL on error.
5874  *   Free the returned object with g_object_unref().
5875  */
5876 GFileMonitor *
5877 g_file_monitor_file (GFile              *file,
5878                      GFileMonitorFlags   flags,
5879                      GCancellable       *cancellable,
5880                      GError            **error)
5881 {
5882   GFileIface *iface;
5883   GFileMonitor *monitor;
5884
5885   g_return_val_if_fail (G_IS_FILE (file), NULL);
5886
5887   if (g_cancellable_set_error_if_cancelled (cancellable, error))
5888     return NULL;
5889
5890   iface = G_FILE_GET_IFACE (file);
5891
5892   monitor = NULL;
5893
5894   if (iface->monitor_file)
5895     monitor = (* iface->monitor_file) (file, flags, cancellable, NULL);
5896
5897   /* Fallback to polling */
5898   if (monitor == NULL)
5899     monitor = _g_poll_file_monitor_new (file);
5900
5901   return monitor;
5902 }
5903
5904 /**
5905  * g_file_monitor:
5906  * @file: input #GFile
5907  * @flags: a set of #GFileMonitorFlags
5908  * @cancellable: (nullable): optional #GCancellable object,
5909  *   %NULL to ignore
5910  * @error: a #GError, or %NULL
5911  *
5912  * Obtains a file or directory monitor for the given file,
5913  * depending on the type of the file.
5914  *
5915  * If @cancellable is not %NULL, then the operation can be cancelled by
5916  * triggering the cancellable object from another thread. If the operation
5917  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5918  *
5919  * Returns: (transfer full): a #GFileMonitor for the given @file,
5920  *   or %NULL on error.
5921  *   Free the returned object with g_object_unref().
5922  *
5923  * Since: 2.18
5924  */
5925 GFileMonitor *
5926 g_file_monitor (GFile              *file,
5927                 GFileMonitorFlags   flags,
5928                 GCancellable       *cancellable,
5929                 GError            **error)
5930 {
5931   if (g_file_query_file_type (file, 0, cancellable) == G_FILE_TYPE_DIRECTORY)
5932     return g_file_monitor_directory (file,
5933                                      flags & ~G_FILE_MONITOR_WATCH_HARD_LINKS,
5934                                      cancellable, error);
5935   else
5936     return g_file_monitor_file (file, flags, cancellable, error);
5937 }
5938
5939 /********************************************
5940  *   Default implementation of async ops    *
5941  ********************************************/
5942
5943 typedef struct {
5944   char *attributes;
5945   GFileQueryInfoFlags flags;
5946 } QueryInfoAsyncData;
5947
5948 static void
5949 query_info_data_free (QueryInfoAsyncData *data)
5950 {
5951   g_free (data->attributes);
5952   g_free (data);
5953 }
5954
5955 static void
5956 query_info_async_thread (GTask         *task,
5957                          gpointer       object,
5958                          gpointer       task_data,
5959                          GCancellable  *cancellable)
5960 {
5961   QueryInfoAsyncData *data = task_data;
5962   GFileInfo *info;
5963   GError *error = NULL;
5964
5965   info = g_file_query_info (G_FILE (object), data->attributes, data->flags, cancellable, &error);
5966   if (info)
5967     g_task_return_pointer (task, info, g_object_unref);
5968   else
5969     g_task_return_error (task, error);
5970 }
5971
5972 static void
5973 g_file_real_query_info_async (GFile               *file,
5974                               const char          *attributes,
5975                               GFileQueryInfoFlags  flags,
5976                               int                  io_priority,
5977                               GCancellable        *cancellable,
5978                               GAsyncReadyCallback  callback,
5979                               gpointer             user_data)
5980 {
5981   GTask *task;
5982   QueryInfoAsyncData *data;
5983
5984   data = g_new0 (QueryInfoAsyncData, 1);
5985   data->attributes = g_strdup (attributes);
5986   data->flags = flags;
5987
5988   task = g_task_new (file, cancellable, callback, user_data);
5989   g_task_set_source_tag (task, g_file_real_query_info_async);
5990   g_task_set_task_data (task, data, (GDestroyNotify)query_info_data_free);
5991   g_task_set_priority (task, io_priority);
5992   g_task_run_in_thread (task, query_info_async_thread);
5993   g_object_unref (task);
5994 }
5995
5996 static GFileInfo *
5997 g_file_real_query_info_finish (GFile         *file,
5998                                GAsyncResult  *res,
5999                                GError       **error)
6000 {
6001   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6002
6003   return g_task_propagate_pointer (G_TASK (res), error);
6004 }
6005
6006 static void
6007 query_filesystem_info_async_thread (GTask         *task,
6008                                     gpointer       object,
6009                                     gpointer       task_data,
6010                                     GCancellable  *cancellable)
6011 {
6012   const char *attributes = task_data;
6013   GFileInfo *info;
6014   GError *error = NULL;
6015
6016   info = g_file_query_filesystem_info (G_FILE (object), attributes, cancellable, &error);
6017   if (info)
6018     g_task_return_pointer (task, info, g_object_unref);
6019   else
6020     g_task_return_error (task, error);
6021 }
6022
6023 static void
6024 g_file_real_query_filesystem_info_async (GFile               *file,
6025                                          const char          *attributes,
6026                                          int                  io_priority,
6027                                          GCancellable        *cancellable,
6028                                          GAsyncReadyCallback  callback,
6029                                          gpointer             user_data)
6030 {
6031   GTask *task;
6032
6033   task = g_task_new (file, cancellable, callback, user_data);
6034   g_task_set_source_tag (task, g_file_real_query_filesystem_info_async);
6035   g_task_set_task_data (task, g_strdup (attributes), g_free);
6036   g_task_set_priority (task, io_priority);
6037   g_task_run_in_thread (task, query_filesystem_info_async_thread);
6038   g_object_unref (task);
6039 }
6040
6041 static GFileInfo *
6042 g_file_real_query_filesystem_info_finish (GFile         *file,
6043                                           GAsyncResult  *res,
6044                                           GError       **error)
6045 {
6046   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6047
6048   return g_task_propagate_pointer (G_TASK (res), error);
6049 }
6050
6051 static void
6052 enumerate_children_async_thread (GTask         *task,
6053                                  gpointer       object,
6054                                  gpointer       task_data,
6055                                  GCancellable  *cancellable)
6056 {
6057   QueryInfoAsyncData *data = task_data;
6058   GFileEnumerator *enumerator;
6059   GError *error = NULL;
6060
6061   enumerator = g_file_enumerate_children (G_FILE (object), data->attributes, data->flags, cancellable, &error);
6062   if (error)
6063     g_task_return_error (task, error);
6064   else
6065     g_task_return_pointer (task, enumerator, g_object_unref);
6066 }
6067
6068 static void
6069 g_file_real_enumerate_children_async (GFile               *file,
6070                                       const char          *attributes,
6071                                       GFileQueryInfoFlags  flags,
6072                                       int                  io_priority,
6073                                       GCancellable        *cancellable,
6074                                       GAsyncReadyCallback  callback,
6075                                       gpointer             user_data)
6076 {
6077   GTask *task;
6078   QueryInfoAsyncData *data;
6079
6080   data = g_new0 (QueryInfoAsyncData, 1);
6081   data->attributes = g_strdup (attributes);
6082   data->flags = flags;
6083
6084   task = g_task_new (file, cancellable, callback, user_data);
6085   g_task_set_source_tag (task, g_file_real_enumerate_children_async);
6086   g_task_set_task_data (task, data, (GDestroyNotify)query_info_data_free);
6087   g_task_set_priority (task, io_priority);
6088   g_task_run_in_thread (task, enumerate_children_async_thread);
6089   g_object_unref (task);
6090 }
6091
6092 static GFileEnumerator *
6093 g_file_real_enumerate_children_finish (GFile         *file,
6094                                        GAsyncResult  *res,
6095                                        GError       **error)
6096 {
6097   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6098
6099   return g_task_propagate_pointer (G_TASK (res), error);
6100 }
6101
6102 static void
6103 open_read_async_thread (GTask         *task,
6104                         gpointer       object,
6105                         gpointer       task_data,
6106                         GCancellable  *cancellable)
6107 {
6108   GFileInputStream *stream;
6109   GError *error = NULL;
6110
6111   stream = g_file_read (G_FILE (object), cancellable, &error);
6112   if (stream)
6113     g_task_return_pointer (task, stream, g_object_unref);
6114   else
6115     g_task_return_error (task, error);
6116 }
6117
6118 static void
6119 g_file_real_read_async (GFile               *file,
6120                         int                  io_priority,
6121                         GCancellable        *cancellable,
6122                         GAsyncReadyCallback  callback,
6123                         gpointer             user_data)
6124 {
6125   GTask *task;
6126
6127   task = g_task_new (file, cancellable, callback, user_data);
6128   g_task_set_source_tag (task, g_file_real_read_async);
6129   g_task_set_priority (task, io_priority);
6130   g_task_run_in_thread (task, open_read_async_thread);
6131   g_object_unref (task);
6132 }
6133
6134 static GFileInputStream *
6135 g_file_real_read_finish (GFile         *file,
6136                          GAsyncResult  *res,
6137                          GError       **error)
6138 {
6139   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6140
6141   return g_task_propagate_pointer (G_TASK (res), error);
6142 }
6143
6144 static void
6145 append_to_async_thread (GTask         *task,
6146                         gpointer       source_object,
6147                         gpointer       task_data,
6148                         GCancellable  *cancellable)
6149 {
6150   GFileCreateFlags *data = task_data;
6151   GFileOutputStream *stream;
6152   GError *error = NULL;
6153
6154   stream = g_file_append_to (G_FILE (source_object), *data, cancellable, &error);
6155   if (stream)
6156     g_task_return_pointer (task, stream, g_object_unref);
6157   else
6158     g_task_return_error (task, error);
6159 }
6160
6161 static void
6162 g_file_real_append_to_async (GFile               *file,
6163                              GFileCreateFlags     flags,
6164                              int                  io_priority,
6165                              GCancellable        *cancellable,
6166                              GAsyncReadyCallback  callback,
6167                              gpointer             user_data)
6168 {
6169   GFileCreateFlags *data;
6170   GTask *task;
6171
6172   data = g_new0 (GFileCreateFlags, 1);
6173   *data = flags;
6174
6175   task = g_task_new (file, cancellable, callback, user_data);
6176   g_task_set_source_tag (task, g_file_real_append_to_async);
6177   g_task_set_task_data (task, data, g_free);
6178   g_task_set_priority (task, io_priority);
6179
6180   g_task_run_in_thread (task, append_to_async_thread);
6181   g_object_unref (task);
6182 }
6183
6184 static GFileOutputStream *
6185 g_file_real_append_to_finish (GFile         *file,
6186                               GAsyncResult  *res,
6187                               GError       **error)
6188 {
6189   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6190
6191   return g_task_propagate_pointer (G_TASK (res), error);
6192 }
6193
6194 static void
6195 create_async_thread (GTask         *task,
6196                      gpointer       source_object,
6197                      gpointer       task_data,
6198                      GCancellable  *cancellable)
6199 {
6200   GFileCreateFlags *data = task_data;
6201   GFileOutputStream *stream;
6202   GError *error = NULL;
6203
6204   stream = g_file_create (G_FILE (source_object), *data, cancellable, &error);
6205   if (stream)
6206     g_task_return_pointer (task, stream, g_object_unref);
6207   else
6208     g_task_return_error (task, error);
6209 }
6210
6211 static void
6212 g_file_real_create_async (GFile               *file,
6213                           GFileCreateFlags     flags,
6214                           int                  io_priority,
6215                           GCancellable        *cancellable,
6216                           GAsyncReadyCallback  callback,
6217                           gpointer             user_data)
6218 {
6219   GFileCreateFlags *data;
6220   GTask *task;
6221
6222   data = g_new0 (GFileCreateFlags, 1);
6223   *data = flags;
6224
6225   task = g_task_new (file, cancellable, callback, user_data);
6226   g_task_set_source_tag (task, g_file_real_create_async);
6227   g_task_set_task_data (task, data, g_free);
6228   g_task_set_priority (task, io_priority);
6229
6230   g_task_run_in_thread (task, create_async_thread);
6231   g_object_unref (task);
6232 }
6233
6234 static GFileOutputStream *
6235 g_file_real_create_finish (GFile         *file,
6236                            GAsyncResult  *res,
6237                            GError       **error)
6238 {
6239   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6240
6241   return g_task_propagate_pointer (G_TASK (res), error);
6242 }
6243
6244 typedef struct {
6245   GFileOutputStream *stream;
6246   char *etag;
6247   gboolean make_backup;
6248   GFileCreateFlags flags;
6249 } ReplaceAsyncData;
6250
6251 static void
6252 replace_async_data_free (ReplaceAsyncData *data)
6253 {
6254   if (data->stream)
6255     g_object_unref (data->stream);
6256   g_free (data->etag);
6257   g_free (data);
6258 }
6259
6260 static void
6261 replace_async_thread (GTask         *task,
6262                       gpointer       source_object,
6263                       gpointer       task_data,
6264                       GCancellable  *cancellable)
6265 {
6266   GFileOutputStream *stream;
6267   ReplaceAsyncData *data = task_data;
6268   GError *error = NULL;
6269
6270   stream = g_file_replace (G_FILE (source_object),
6271                            data->etag,
6272                            data->make_backup,
6273                            data->flags,
6274                            cancellable,
6275                            &error);
6276
6277   if (stream)
6278     g_task_return_pointer (task, stream, g_object_unref);
6279   else
6280     g_task_return_error (task, error);
6281 }
6282
6283 static void
6284 g_file_real_replace_async (GFile               *file,
6285                            const char          *etag,
6286                            gboolean             make_backup,
6287                            GFileCreateFlags     flags,
6288                            int                  io_priority,
6289                            GCancellable        *cancellable,
6290                            GAsyncReadyCallback  callback,
6291                            gpointer             user_data)
6292 {
6293   GTask *task;
6294   ReplaceAsyncData *data;
6295
6296   data = g_new0 (ReplaceAsyncData, 1);
6297   data->etag = g_strdup (etag);
6298   data->make_backup = make_backup;
6299   data->flags = flags;
6300
6301   task = g_task_new (file, cancellable, callback, user_data);
6302   g_task_set_source_tag (task, g_file_real_replace_async);
6303   g_task_set_task_data (task, data, (GDestroyNotify)replace_async_data_free);
6304   g_task_set_priority (task, io_priority);
6305
6306   g_task_run_in_thread (task, replace_async_thread);
6307   g_object_unref (task);
6308 }
6309
6310 static GFileOutputStream *
6311 g_file_real_replace_finish (GFile         *file,
6312                             GAsyncResult  *res,
6313                             GError       **error)
6314 {
6315   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6316
6317   return g_task_propagate_pointer (G_TASK (res), error);
6318 }
6319
6320 static void
6321 delete_async_thread (GTask        *task,
6322                      gpointer      object,
6323                      gpointer      task_data,
6324                      GCancellable *cancellable)
6325 {
6326   GError *error = NULL;
6327
6328   if (g_file_delete (G_FILE (object), cancellable, &error))
6329     g_task_return_boolean (task, TRUE);
6330   else
6331     g_task_return_error (task, error);
6332 }
6333
6334 static void
6335 g_file_real_delete_async (GFile               *file,
6336                           int                  io_priority,
6337                           GCancellable        *cancellable,
6338                           GAsyncReadyCallback  callback,
6339                           gpointer             user_data)
6340 {
6341   GTask *task;
6342
6343   task = g_task_new (file, cancellable, callback, user_data);
6344   g_task_set_source_tag (task, g_file_real_delete_async);
6345   g_task_set_priority (task, io_priority);
6346   g_task_run_in_thread (task, delete_async_thread);
6347   g_object_unref (task);
6348 }
6349
6350 static gboolean
6351 g_file_real_delete_finish (GFile         *file,
6352                            GAsyncResult  *res,
6353                            GError       **error)
6354 {
6355   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
6356
6357   return g_task_propagate_boolean (G_TASK (res), error);
6358 }
6359
6360 static void
6361 trash_async_thread (GTask        *task,
6362                     gpointer      object,
6363                     gpointer      task_data,
6364                     GCancellable *cancellable)
6365 {
6366   GError *error = NULL;
6367
6368   if (g_file_trash (G_FILE (object), cancellable, &error))
6369     g_task_return_boolean (task, TRUE);
6370   else
6371     g_task_return_error (task, error);
6372 }
6373
6374 static void
6375 g_file_real_trash_async (GFile               *file,
6376                          int                  io_priority,
6377                          GCancellable        *cancellable,
6378                          GAsyncReadyCallback  callback,
6379                          gpointer             user_data)
6380 {
6381   GTask *task;
6382
6383   task = g_task_new (file, cancellable, callback, user_data);
6384   g_task_set_source_tag (task, g_file_real_trash_async);
6385   g_task_set_priority (task, io_priority);
6386   g_task_run_in_thread (task, trash_async_thread);
6387   g_object_unref (task);
6388 }
6389
6390 static gboolean
6391 g_file_real_trash_finish (GFile         *file,
6392                           GAsyncResult  *res,
6393                           GError       **error)
6394 {
6395   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
6396
6397   return g_task_propagate_boolean (G_TASK (res), error);
6398 }
6399
6400
6401 typedef struct {
6402   GFile *source;  /* (owned) */
6403   GFile *destination;  /* (owned) */
6404   GFileCopyFlags flags;
6405   GFileProgressCallback progress_cb;
6406   gpointer progress_cb_data;
6407 } MoveAsyncData;
6408
6409 static void
6410 move_async_data_free (MoveAsyncData *data)
6411 {
6412   g_object_unref (data->source);
6413   g_object_unref (data->destination);
6414   g_slice_free (MoveAsyncData, data);
6415 }
6416
6417 typedef struct {
6418   MoveAsyncData *data;  /* (unowned) */
6419   goffset current_num_bytes;
6420   goffset total_num_bytes;
6421 } MoveProgressData;
6422
6423 static gboolean
6424 move_async_progress_in_main (gpointer user_data)
6425 {
6426   MoveProgressData *progress = user_data;
6427   MoveAsyncData *data = progress->data;
6428
6429   data->progress_cb (progress->current_num_bytes,
6430                      progress->total_num_bytes,
6431                      data->progress_cb_data);
6432
6433   return G_SOURCE_REMOVE;
6434 }
6435
6436 static void
6437 move_async_progress_callback (goffset  current_num_bytes,
6438                               goffset  total_num_bytes,
6439                               gpointer user_data)
6440 {
6441   GTask *task = user_data;
6442   MoveAsyncData *data = g_task_get_task_data (task);
6443   MoveProgressData *progress;
6444
6445   progress = g_new0 (MoveProgressData, 1);
6446   progress->data = data;
6447   progress->current_num_bytes = current_num_bytes;
6448   progress->total_num_bytes = total_num_bytes;
6449
6450   g_main_context_invoke_full (g_task_get_context (task),
6451                               g_task_get_priority (task),
6452                               move_async_progress_in_main,
6453                               g_steal_pointer (&progress),
6454                               g_free);
6455 }
6456
6457 static void
6458 move_async_thread (GTask        *task,
6459                    gpointer      source,
6460                    gpointer      task_data,
6461                    GCancellable *cancellable)
6462 {
6463   MoveAsyncData *data = task_data;
6464   gboolean result;
6465   GError *error = NULL;
6466
6467   result = g_file_move (data->source,
6468                         data->destination,
6469                         data->flags,
6470                         cancellable,
6471                         (data->progress_cb != NULL) ? move_async_progress_callback : NULL,
6472                         task,
6473                         &error);
6474   if (result)
6475     g_task_return_boolean (task, TRUE);
6476   else
6477     g_task_return_error (task, g_steal_pointer (&error));
6478 }
6479
6480 static void
6481 g_file_real_move_async (GFile                  *source,
6482                         GFile                  *destination,
6483                         GFileCopyFlags          flags,
6484                         int                     io_priority,
6485                         GCancellable           *cancellable,
6486                         GFileProgressCallback   progress_callback,
6487                         gpointer                progress_callback_data,
6488                         GAsyncReadyCallback     callback,
6489                         gpointer                user_data)
6490 {
6491   GTask *task;
6492   MoveAsyncData *data;
6493
6494   data = g_slice_new0 (MoveAsyncData);
6495   data->source = g_object_ref (source);
6496   data->destination = g_object_ref (destination);
6497   data->flags = flags;
6498   data->progress_cb = progress_callback;
6499   data->progress_cb_data = progress_callback_data;
6500
6501   task = g_task_new (source, cancellable, callback, user_data);
6502   g_task_set_source_tag (task, g_file_real_move_async);
6503   g_task_set_task_data (task, g_steal_pointer (&data), (GDestroyNotify) move_async_data_free);
6504   g_task_set_priority (task, io_priority);
6505   g_task_run_in_thread (task, move_async_thread);
6506   g_object_unref (task);
6507 }
6508
6509 static gboolean
6510 g_file_real_move_finish (GFile        *file,
6511                          GAsyncResult *result,
6512                          GError      **error)
6513 {
6514   g_return_val_if_fail (g_task_is_valid (result, file), FALSE);
6515
6516   return g_task_propagate_boolean (G_TASK (result), error);
6517 }
6518
6519 static void
6520 make_directory_async_thread (GTask        *task,
6521                              gpointer      object,
6522                              gpointer      task_data,
6523                              GCancellable *cancellable)
6524 {
6525   GError *error = NULL;
6526
6527   if (g_file_make_directory (G_FILE (object), cancellable, &error))
6528     g_task_return_boolean (task, TRUE);
6529   else
6530     g_task_return_error (task, error);
6531 }
6532
6533 static void
6534 g_file_real_make_directory_async (GFile               *file,
6535                                   int                  io_priority,
6536                                   GCancellable        *cancellable,
6537                                   GAsyncReadyCallback  callback,
6538                                   gpointer             user_data)
6539 {
6540   GTask *task;
6541
6542   task = g_task_new (file, cancellable, callback, user_data);
6543   g_task_set_source_tag (task, g_file_real_make_directory_async);
6544   g_task_set_priority (task, io_priority);
6545   g_task_run_in_thread (task, make_directory_async_thread);
6546   g_object_unref (task);
6547 }
6548
6549 static gboolean
6550 g_file_real_make_directory_finish (GFile         *file,
6551                                    GAsyncResult  *res,
6552                                    GError       **error)
6553 {
6554   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
6555
6556   return g_task_propagate_boolean (G_TASK (res), error);
6557 }
6558
6559 static void
6560 open_readwrite_async_thread (GTask        *task,
6561                              gpointer      object,
6562                              gpointer      task_data,
6563                              GCancellable *cancellable)
6564 {
6565   GFileIOStream *stream;
6566   GError *error = NULL;
6567
6568   stream = g_file_open_readwrite (G_FILE (object), cancellable, &error);
6569
6570   if (stream == NULL)
6571     g_task_return_error (task, error);
6572   else
6573     g_task_return_pointer (task, stream, g_object_unref);
6574 }
6575
6576 static void
6577 g_file_real_open_readwrite_async (GFile               *file,
6578                                   int                  io_priority,
6579                                   GCancellable        *cancellable,
6580                                   GAsyncReadyCallback  callback,
6581                                   gpointer             user_data)
6582 {
6583   GTask *task;
6584
6585   task = g_task_new (file, cancellable, callback, user_data);
6586   g_task_set_source_tag (task, g_file_real_open_readwrite_async);
6587   g_task_set_priority (task, io_priority);
6588
6589   g_task_run_in_thread (task, open_readwrite_async_thread);
6590   g_object_unref (task);
6591 }
6592
6593 static GFileIOStream *
6594 g_file_real_open_readwrite_finish (GFile         *file,
6595                                    GAsyncResult  *res,
6596                                    GError       **error)
6597 {
6598   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6599
6600   return g_task_propagate_pointer (G_TASK (res), error);
6601 }
6602
6603 static void
6604 create_readwrite_async_thread (GTask        *task,
6605                                gpointer      object,
6606                                gpointer      task_data,
6607                                GCancellable *cancellable)
6608 {
6609   GFileCreateFlags *data = task_data;
6610   GFileIOStream *stream;
6611   GError *error = NULL;
6612
6613   stream = g_file_create_readwrite (G_FILE (object), *data, cancellable, &error);
6614
6615   if (stream == NULL)
6616     g_task_return_error (task, error);
6617   else
6618     g_task_return_pointer (task, stream, g_object_unref);
6619 }
6620
6621 static void
6622 g_file_real_create_readwrite_async (GFile               *file,
6623                                     GFileCreateFlags     flags,
6624                                     int                  io_priority,
6625                                     GCancellable        *cancellable,
6626                                     GAsyncReadyCallback  callback,
6627                                     gpointer             user_data)
6628 {
6629   GFileCreateFlags *data;
6630   GTask *task;
6631
6632   data = g_new0 (GFileCreateFlags, 1);
6633   *data = flags;
6634
6635   task = g_task_new (file, cancellable, callback, user_data);
6636   g_task_set_source_tag (task, g_file_real_create_readwrite_async);
6637   g_task_set_task_data (task, data, g_free);
6638   g_task_set_priority (task, io_priority);
6639
6640   g_task_run_in_thread (task, create_readwrite_async_thread);
6641   g_object_unref (task);
6642 }
6643
6644 static GFileIOStream *
6645 g_file_real_create_readwrite_finish (GFile         *file,
6646                                      GAsyncResult  *res,
6647                                      GError       **error)
6648 {
6649   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6650
6651   return g_task_propagate_pointer (G_TASK (res), error);
6652 }
6653
6654 typedef struct {
6655   char *etag;
6656   gboolean make_backup;
6657   GFileCreateFlags flags;
6658 } ReplaceRWAsyncData;
6659
6660 static void
6661 replace_rw_async_data_free (ReplaceRWAsyncData *data)
6662 {
6663   g_free (data->etag);
6664   g_free (data);
6665 }
6666
6667 static void
6668 replace_readwrite_async_thread (GTask        *task,
6669                                 gpointer      object,
6670                                 gpointer      task_data,
6671                                 GCancellable *cancellable)
6672 {
6673   GFileIOStream *stream;
6674   GError *error = NULL;
6675   ReplaceRWAsyncData *data = task_data;
6676
6677   stream = g_file_replace_readwrite (G_FILE (object),
6678                                      data->etag,
6679                                      data->make_backup,
6680                                      data->flags,
6681                                      cancellable,
6682                                      &error);
6683
6684   if (stream == NULL)
6685     g_task_return_error (task, error);
6686   else
6687     g_task_return_pointer (task, stream, g_object_unref);
6688 }
6689
6690 static void
6691 g_file_real_replace_readwrite_async (GFile               *file,
6692                                      const char          *etag,
6693                                      gboolean             make_backup,
6694                                      GFileCreateFlags     flags,
6695                                      int                  io_priority,
6696                                      GCancellable        *cancellable,
6697                                      GAsyncReadyCallback  callback,
6698                                      gpointer             user_data)
6699 {
6700   GTask *task;
6701   ReplaceRWAsyncData *data;
6702
6703   data = g_new0 (ReplaceRWAsyncData, 1);
6704   data->etag = g_strdup (etag);
6705   data->make_backup = make_backup;
6706   data->flags = flags;
6707
6708   task = g_task_new (file, cancellable, callback, user_data);
6709   g_task_set_source_tag (task, g_file_real_replace_readwrite_async);
6710   g_task_set_task_data (task, data, (GDestroyNotify)replace_rw_async_data_free);
6711   g_task_set_priority (task, io_priority);
6712
6713   g_task_run_in_thread (task, replace_readwrite_async_thread);
6714   g_object_unref (task);
6715 }
6716
6717 static GFileIOStream *
6718 g_file_real_replace_readwrite_finish (GFile         *file,
6719                                       GAsyncResult  *res,
6720                                       GError       **error)
6721 {
6722   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6723
6724   return g_task_propagate_pointer (G_TASK (res), error);
6725 }
6726
6727 static void
6728 set_display_name_async_thread (GTask        *task,
6729                                gpointer      object,
6730                                gpointer      task_data,
6731                                GCancellable *cancellable)
6732 {
6733   GError *error = NULL;
6734   char *name = task_data;
6735   GFile *file;
6736
6737   file = g_file_set_display_name (G_FILE (object), name, cancellable, &error);
6738
6739   if (file == NULL)
6740     g_task_return_error (task, error);
6741   else
6742     g_task_return_pointer (task, file, g_object_unref);
6743 }
6744
6745 static void
6746 g_file_real_set_display_name_async (GFile               *file,
6747                                     const char          *display_name,
6748                                     int                  io_priority,
6749                                     GCancellable        *cancellable,
6750                                     GAsyncReadyCallback  callback,
6751                                     gpointer             user_data)
6752 {
6753   GTask *task;
6754
6755   task = g_task_new (file, cancellable, callback, user_data);
6756   g_task_set_source_tag (task, g_file_real_set_display_name_async);
6757   g_task_set_task_data (task, g_strdup (display_name), g_free);
6758   g_task_set_priority (task, io_priority);
6759
6760   g_task_run_in_thread (task, set_display_name_async_thread);
6761   g_object_unref (task);
6762 }
6763
6764 static GFile *
6765 g_file_real_set_display_name_finish (GFile         *file,
6766                                      GAsyncResult  *res,
6767                                      GError       **error)
6768 {
6769   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6770
6771   return g_task_propagate_pointer (G_TASK (res), error);
6772 }
6773
6774 typedef struct {
6775   GFileQueryInfoFlags flags;
6776   GFileInfo *info;
6777 } SetInfoAsyncData;
6778
6779 static void
6780 set_info_data_free (SetInfoAsyncData *data)
6781 {
6782   if (data->info)
6783     g_object_unref (data->info);
6784   g_free (data);
6785 }
6786
6787 static void
6788 set_info_async_thread (GTask        *task,
6789                        gpointer      object,
6790                        gpointer      task_data,
6791                        GCancellable *cancellable)
6792 {
6793   SetInfoAsyncData *data = task_data;
6794   GError *error = NULL;
6795
6796   if (g_file_set_attributes_from_info (G_FILE (object),
6797                                        data->info,
6798                                        data->flags,
6799                                        cancellable,
6800                                        &error))
6801     g_task_return_boolean (task, TRUE);
6802   else
6803     g_task_return_error (task, error);
6804 }
6805
6806 static void
6807 g_file_real_set_attributes_async (GFile               *file,
6808                                   GFileInfo           *info,
6809                                   GFileQueryInfoFlags  flags,
6810                                   int                  io_priority,
6811                                   GCancellable        *cancellable,
6812                                   GAsyncReadyCallback  callback,
6813                                   gpointer             user_data)
6814 {
6815   GTask *task;
6816   SetInfoAsyncData *data;
6817
6818   data = g_new0 (SetInfoAsyncData, 1);
6819   data->info = g_file_info_dup (info);
6820   data->flags = flags;
6821
6822   task = g_task_new (file, cancellable, callback, user_data);
6823   g_task_set_source_tag (task, g_file_real_set_attributes_async);
6824   g_task_set_task_data (task, data, (GDestroyNotify)set_info_data_free);
6825   g_task_set_priority (task, io_priority);
6826
6827   g_task_run_in_thread (task, set_info_async_thread);
6828   g_object_unref (task);
6829 }
6830
6831 static gboolean
6832 g_file_real_set_attributes_finish (GFile         *file,
6833                                    GAsyncResult  *res,
6834                                    GFileInfo    **info,
6835                                    GError       **error)
6836 {
6837   SetInfoAsyncData *data;
6838
6839   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
6840
6841   data = g_task_get_task_data (G_TASK (res));
6842
6843   if (info)
6844     *info = g_object_ref (data->info);
6845
6846   return g_task_propagate_boolean (G_TASK (res), error);
6847 }
6848
6849 static void
6850 find_enclosing_mount_async_thread (GTask        *task,
6851                                    gpointer      object,
6852                                    gpointer      task_data,
6853                                    GCancellable *cancellable)
6854 {
6855   GError *error = NULL;
6856   GMount *mount;
6857
6858   mount = g_file_find_enclosing_mount (G_FILE (object), cancellable, &error);
6859
6860   if (mount == NULL)
6861     g_task_return_error (task, error);
6862   else
6863     g_task_return_pointer (task, mount, g_object_unref);
6864 }
6865
6866 static void
6867 g_file_real_find_enclosing_mount_async (GFile               *file,
6868                                         int                  io_priority,
6869                                         GCancellable        *cancellable,
6870                                         GAsyncReadyCallback  callback,
6871                                         gpointer             user_data)
6872 {
6873   GTask *task;
6874
6875   task = g_task_new (file, cancellable, callback, user_data);
6876   g_task_set_source_tag (task, g_file_real_find_enclosing_mount_async);
6877   g_task_set_priority (task, io_priority);
6878
6879   g_task_run_in_thread (task, find_enclosing_mount_async_thread);
6880   g_object_unref (task);
6881 }
6882
6883 static GMount *
6884 g_file_real_find_enclosing_mount_finish (GFile         *file,
6885                                          GAsyncResult  *res,
6886                                          GError       **error)
6887 {
6888   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6889
6890   return g_task_propagate_pointer (G_TASK (res), error);
6891 }
6892
6893
6894 typedef struct {
6895   GFile *source;
6896   GFile *destination;
6897   GFileCopyFlags flags;
6898   GFileProgressCallback progress_cb;
6899   gpointer progress_cb_data;
6900 } CopyAsyncData;
6901
6902 static void
6903 copy_async_data_free (CopyAsyncData *data)
6904 {
6905   g_object_unref (data->source);
6906   g_object_unref (data->destination);
6907   g_slice_free (CopyAsyncData, data);
6908 }
6909
6910 typedef struct {
6911   CopyAsyncData *data;
6912   goffset current_num_bytes;
6913   goffset total_num_bytes;
6914 } CopyProgressData;
6915
6916 static gboolean
6917 copy_async_progress_in_main (gpointer user_data)
6918 {
6919   CopyProgressData *progress = user_data;
6920   CopyAsyncData *data = progress->data;
6921
6922   data->progress_cb (progress->current_num_bytes,
6923                      progress->total_num_bytes,
6924                      data->progress_cb_data);
6925
6926   return FALSE;
6927 }
6928
6929 static void
6930 copy_async_progress_callback (goffset  current_num_bytes,
6931                               goffset  total_num_bytes,
6932                               gpointer user_data)
6933 {
6934   GTask *task = user_data;
6935   CopyAsyncData *data = g_task_get_task_data (task);
6936   CopyProgressData *progress;
6937
6938   progress = g_new (CopyProgressData, 1);
6939   progress->data = data;
6940   progress->current_num_bytes = current_num_bytes;
6941   progress->total_num_bytes = total_num_bytes;
6942
6943   g_main_context_invoke_full (g_task_get_context (task),
6944                               g_task_get_priority (task),
6945                               copy_async_progress_in_main,
6946                               progress,
6947                               g_free);
6948 }
6949
6950 static void
6951 copy_async_thread (GTask        *task,
6952                    gpointer      source,
6953                    gpointer      task_data,
6954                    GCancellable *cancellable)
6955 {
6956   CopyAsyncData *data = task_data;
6957   gboolean result;
6958   GError *error = NULL;
6959
6960   result = g_file_copy (data->source,
6961                         data->destination,
6962                         data->flags,
6963                         cancellable,
6964                         (data->progress_cb != NULL) ? copy_async_progress_callback : NULL,
6965                         task,
6966                         &error);
6967   if (result)
6968     g_task_return_boolean (task, TRUE);
6969   else
6970     g_task_return_error (task, error);
6971 }
6972
6973 static void
6974 g_file_real_copy_async (GFile                  *source,
6975                         GFile                  *destination,
6976                         GFileCopyFlags          flags,
6977                         int                     io_priority,
6978                         GCancellable           *cancellable,
6979                         GFileProgressCallback   progress_callback,
6980                         gpointer                progress_callback_data,
6981                         GAsyncReadyCallback     callback,
6982                         gpointer                user_data)
6983 {
6984   GTask *task;
6985   CopyAsyncData *data;
6986
6987   data = g_slice_new (CopyAsyncData);
6988   data->source = g_object_ref (source);
6989   data->destination = g_object_ref (destination);
6990   data->flags = flags;
6991   data->progress_cb = progress_callback;
6992   data->progress_cb_data = progress_callback_data;
6993
6994   task = g_task_new (source, cancellable, callback, user_data);
6995   g_task_set_source_tag (task, g_file_real_copy_async);
6996   g_task_set_task_data (task, data, (GDestroyNotify)copy_async_data_free);
6997   g_task_set_priority (task, io_priority);
6998   g_task_run_in_thread (task, copy_async_thread);
6999   g_object_unref (task);
7000 }
7001
7002 static gboolean
7003 g_file_real_copy_finish (GFile        *file,
7004                          GAsyncResult *res,
7005                          GError      **error)
7006 {
7007   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
7008
7009   return g_task_propagate_boolean (G_TASK (res), error);
7010 }
7011
7012
7013 /********************************************
7014  *   Default VFS operations                 *
7015  ********************************************/
7016
7017 /**
7018  * g_file_new_for_path:
7019  * @path: (type filename): a string containing a relative or absolute path.
7020  *   The string must be encoded in the glib filename encoding.
7021  *
7022  * Constructs a #GFile for a given path. This operation never
7023  * fails, but the returned object might not support any I/O
7024  * operation if @path is malformed.
7025  *
7026  * Returns: (transfer full): a new #GFile for the given @path.
7027  *   Free the returned object with g_object_unref().
7028  */
7029 GFile *
7030 g_file_new_for_path (const char *path)
7031 {
7032   g_return_val_if_fail (path != NULL, NULL);
7033
7034   return g_vfs_get_file_for_path (g_vfs_get_default (), path);
7035 }
7036
7037 /**
7038  * g_file_new_for_uri:
7039  * @uri: a UTF-8 string containing a URI
7040  *
7041  * Constructs a #GFile for a given URI. This operation never
7042  * fails, but the returned object might not support any I/O
7043  * operation if @uri is malformed or if the uri type is
7044  * not supported.
7045  *
7046  * Returns: (transfer full): a new #GFile for the given @uri.
7047  *   Free the returned object with g_object_unref().
7048  */
7049 GFile *
7050 g_file_new_for_uri (const char *uri)
7051 {
7052   g_return_val_if_fail (uri != NULL, NULL);
7053
7054   return g_vfs_get_file_for_uri (g_vfs_get_default (), uri);
7055 }
7056
7057 /**
7058  * g_file_new_tmp:
7059  * @tmpl: (type filename) (nullable): Template for the file
7060  *   name, as in g_file_open_tmp(), or %NULL for a default template
7061  * @iostream: (out): on return, a #GFileIOStream for the created file
7062  * @error: a #GError, or %NULL
7063  *
7064  * Opens a file in the preferred directory for temporary files (as
7065  * returned by g_get_tmp_dir()) and returns a #GFile and
7066  * #GFileIOStream pointing to it.
7067  *
7068  * @tmpl should be a string in the GLib file name encoding
7069  * containing a sequence of six 'X' characters, and containing no
7070  * directory components. If it is %NULL, a default template is used.
7071  *
7072  * Unlike the other #GFile constructors, this will return %NULL if
7073  * a temporary file could not be created.
7074  *
7075  * Returns: (transfer full): a new #GFile.
7076  *   Free the returned object with g_object_unref().
7077  *
7078  * Since: 2.32
7079  */
7080 GFile *
7081 g_file_new_tmp (const char     *tmpl,
7082                 GFileIOStream **iostream,
7083                 GError        **error)
7084 {
7085   gint fd;
7086   gchar *path;
7087   GFile *file;
7088   GFileOutputStream *output;
7089
7090   g_return_val_if_fail (iostream != NULL, NULL);
7091
7092   fd = g_file_open_tmp (tmpl, &path, error);
7093   if (fd == -1)
7094     return NULL;
7095
7096   file = g_file_new_for_path (path);
7097
7098   output = _g_local_file_output_stream_new (fd);
7099   *iostream = _g_local_file_io_stream_new (G_LOCAL_FILE_OUTPUT_STREAM (output));
7100
7101   g_object_unref (output);
7102   g_free (path);
7103
7104   return file;
7105 }
7106
7107 typedef struct {
7108   GFile *file;
7109   GFileIOStream *iostream;
7110 } NewTmpAsyncData;
7111
7112 static void
7113 new_tmp_data_free (NewTmpAsyncData *data)
7114 {
7115   g_clear_object (&data->file);
7116   g_clear_object (&data->iostream);
7117   g_free (data);
7118 }
7119
7120 static void
7121 new_tmp_async_thread (GTask         *task,
7122                       gpointer       object,
7123                       gpointer       task_data,
7124                       GCancellable  *cancellable)
7125 {
7126   GFile *file;
7127   const char *tmpl = task_data;
7128   GFileIOStream *iostream = NULL;
7129   GError *error = NULL;
7130   NewTmpAsyncData *return_data;
7131
7132   if (g_task_return_error_if_cancelled (task))
7133     return;
7134
7135   file = g_file_new_tmp (tmpl, &iostream, &error);
7136
7137   if (!file)
7138     {
7139       int error_code = G_IO_ERROR_FAILED;
7140
7141       if (error->domain == G_IO_ERROR)
7142         {
7143           g_task_return_error (task, g_steal_pointer (&error));
7144           return;
7145         }
7146
7147       if (error->domain == G_FILE_ERROR)
7148         error_code = g_io_error_from_file_error (error->code);
7149
7150       g_task_return_new_error (task, G_IO_ERROR, error_code,
7151                                _("Failed to create a temporary directory for "
7152                                  "template “%s”: %s"),
7153                                tmpl, error->message);
7154
7155       g_clear_error (&error);
7156       return;
7157     }
7158
7159   return_data = g_new0 (NewTmpAsyncData, 1);
7160   return_data->file = g_steal_pointer (&file);
7161   return_data->iostream = g_steal_pointer (&iostream);
7162
7163   g_task_return_pointer (task, g_steal_pointer (&return_data),
7164                          (GDestroyNotify) new_tmp_data_free);
7165 }
7166
7167 /**
7168  * g_file_new_tmp_async:
7169  * @tmpl: (type filename) (nullable): Template for the file
7170  *   name, as in g_file_open_tmp(), or %NULL for a default template
7171  * @io_priority: the [I/O priority][io-priority] of the request
7172  * @cancellable: optional #GCancellable object, %NULL to ignore
7173  * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done
7174  * @user_data: (nullable): data to pass to @callback
7175  *
7176  * Asynchronously opens a file in the preferred directory for temporary files
7177  *  (as returned by g_get_tmp_dir()) as g_file_new_tmp().
7178  *
7179  * @tmpl should be a string in the GLib file name encoding
7180  * containing a sequence of six 'X' characters, and containing no
7181  * directory components. If it is %NULL, a default template is used.
7182  *
7183  * Since: 2.74
7184  */
7185 void
7186 g_file_new_tmp_async (const char          *tmpl,
7187                       int                  io_priority,
7188                       GCancellable        *cancellable,
7189                       GAsyncReadyCallback  callback,
7190                       gpointer             user_data)
7191 {
7192   GTask *task;
7193
7194   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
7195
7196   task = g_task_new (NULL, cancellable, callback, user_data);
7197   g_task_set_source_tag (task, g_file_new_tmp_async);
7198   g_task_set_task_data (task, g_strdup (tmpl), g_free);
7199   g_task_set_priority (task, io_priority);
7200   g_task_set_check_cancellable (task, TRUE);
7201   g_task_run_in_thread (task, new_tmp_async_thread);
7202   g_object_unref (task);
7203 }
7204
7205 /**
7206  * g_file_new_tmp_finish:
7207  * @result: a #GAsyncResult
7208  * @iostream: (out) (not optional) (not nullable) (transfer full): on return, a #GFileIOStream for the created file
7209  * @error: a #GError, or %NULL
7210  *
7211  * Finishes a temporary file creation started by g_file_new_tmp_async().
7212  *
7213  * Returns: (transfer full): a new #GFile.
7214  *   Free the returned object with g_object_unref().
7215  *
7216  * Since: 2.74
7217  */
7218 GFile *
7219 g_file_new_tmp_finish (GAsyncResult   *result,
7220                        GFileIOStream **iostream,
7221                        GError        **error)
7222 {
7223   GFile *file;
7224   NewTmpAsyncData *data;
7225
7226   g_return_val_if_fail (g_task_is_valid (result, NULL), NULL);
7227   g_return_val_if_fail (g_task_get_source_tag (G_TASK (result)) ==
7228                         g_file_new_tmp_async, NULL);
7229   g_return_val_if_fail (iostream != NULL, NULL);
7230   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
7231
7232   data = g_task_propagate_pointer (G_TASK (result), error);
7233
7234   if (!data)
7235     {
7236       *iostream = NULL;
7237       return NULL;
7238     }
7239
7240   file = g_steal_pointer (&data->file);
7241   *iostream = g_steal_pointer (&data->iostream);
7242
7243   new_tmp_data_free (data);
7244
7245   return file;
7246 }
7247
7248 static void
7249 new_tmp_dir_async_thread (GTask         *task,
7250                           gpointer       object,
7251                           gpointer       task_data,
7252                           GCancellable  *cancellable)
7253 {
7254   gchar *path;
7255   const char *tmpl = task_data;
7256   GError *error = NULL;
7257
7258   if (g_task_return_error_if_cancelled (task))
7259     return;
7260
7261   path = g_dir_make_tmp (tmpl, &error);
7262
7263   if (!path)
7264     {
7265       int error_code = G_IO_ERROR_FAILED;
7266
7267       if (error->domain == G_IO_ERROR)
7268         {
7269           g_task_return_error (task, g_steal_pointer (&error));
7270           return;
7271         }
7272
7273       if (error->domain == G_FILE_ERROR)
7274         error_code = g_io_error_from_file_error (error->code);
7275
7276       g_task_return_new_error (task, G_IO_ERROR, error_code,
7277                                _("Failed to create a temporary directory for "
7278                                  "template “%s”: %s"),
7279                                tmpl, error->message);
7280
7281       g_clear_error (&error);
7282       return;
7283     }
7284
7285   g_task_return_pointer (task, g_file_new_for_path (path), g_object_unref);
7286
7287   g_free (path);
7288 }
7289
7290 /**
7291  * g_file_new_tmp_dir_async:
7292  * @tmpl: (type filename) (nullable): Template for the file
7293  *   name, as in g_dir_make_tmp(), or %NULL for a default template
7294  * @io_priority: the [I/O priority][io-priority] of the request
7295  * @cancellable: optional #GCancellable object, %NULL to ignore
7296  * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done
7297  * @user_data: (nullable): data to pass to @callback
7298  *
7299  * Asynchronously creates a directory in the preferred directory for
7300  * temporary files (as returned by g_get_tmp_dir()) as g_dir_make_tmp().
7301  *
7302  * @tmpl should be a string in the GLib file name encoding
7303  * containing a sequence of six 'X' characters, and containing no
7304  * directory components. If it is %NULL, a default template is used.
7305  *
7306  * Since: 2.74
7307  */
7308 void
7309 g_file_new_tmp_dir_async (const char          *tmpl,
7310                           int                  io_priority,
7311                           GCancellable        *cancellable,
7312                           GAsyncReadyCallback  callback,
7313                           gpointer             user_data)
7314 {
7315   GTask *task;
7316
7317   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
7318
7319   task = g_task_new (NULL, cancellable, callback, user_data);
7320   g_task_set_source_tag (task, g_file_new_tmp_dir_async);
7321   g_task_set_task_data (task, g_strdup (tmpl), g_free);
7322   g_task_set_priority (task, io_priority);
7323   g_task_set_check_cancellable (task, TRUE);
7324   g_task_run_in_thread (task, new_tmp_dir_async_thread);
7325   g_object_unref (task);
7326 }
7327
7328 /**
7329  * g_file_new_tmp_dir_finish:
7330  * @result: a #GAsyncResult
7331  * @error: a #GError, or %NULL
7332  *
7333  * Finishes a temporary directory creation started by
7334  * g_file_new_tmp_dir_async().
7335  *
7336  * Returns: (transfer full): a new #GFile.
7337  *   Free the returned object with g_object_unref().
7338  *
7339  * Since: 2.74
7340  */
7341 GFile *
7342 g_file_new_tmp_dir_finish (GAsyncResult  *result,
7343                            GError       **error)
7344 {
7345   g_return_val_if_fail (g_task_is_valid (result, NULL), NULL);
7346   g_return_val_if_fail (g_task_get_source_tag (G_TASK (result)) ==
7347                         g_file_new_tmp_dir_async, NULL);
7348   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
7349
7350   return g_task_propagate_pointer (G_TASK (result), error);
7351 }
7352
7353 /**
7354  * g_file_parse_name:
7355  * @parse_name: a file name or path to be parsed
7356  *
7357  * Constructs a #GFile with the given @parse_name (i.e. something
7358  * given by g_file_get_parse_name()). This operation never fails,
7359  * but the returned object might not support any I/O operation if
7360  * the @parse_name cannot be parsed.
7361  *
7362  * Returns: (transfer full): a new #GFile.
7363  */
7364 GFile *
7365 g_file_parse_name (const char *parse_name)
7366 {
7367   g_return_val_if_fail (parse_name != NULL, NULL);
7368
7369   return g_vfs_parse_name (g_vfs_get_default (), parse_name);
7370 }
7371
7372 /**
7373  * g_file_new_build_filename:
7374  * @first_element: (type filename): the first element in the path
7375  * @...: remaining elements in path, terminated by %NULL
7376  *
7377  * Constructs a #GFile from a series of elements using the correct
7378  * separator for filenames.
7379  *
7380  * Using this function is equivalent to calling g_build_filename(),
7381  * followed by g_file_new_for_path() on the result.
7382  *
7383  * Returns: (transfer full): a new #GFile
7384  *
7385  * Since: 2.56
7386  */
7387 GFile *
7388 g_file_new_build_filename (const gchar *first_element,
7389                            ...)
7390 {
7391   gchar *str;
7392   GFile *file;
7393   va_list args;
7394
7395   g_return_val_if_fail (first_element != NULL, NULL);
7396
7397   va_start (args, first_element);
7398   str = g_build_filename_valist (first_element, &args);
7399   va_end (args);
7400
7401   file = g_file_new_for_path (str);
7402   g_free (str);
7403
7404   return file;
7405 }
7406
7407
7408 /**
7409  * g_file_new_build_filenamev:
7410  * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
7411  *   array of strings containing the path elements.
7412  *
7413  * Constructs a #GFile from a vector of elements using the correct
7414  * separator for filenames.
7415  *
7416  * Using this function is equivalent to calling g_build_filenamev(),
7417  * followed by g_file_new_for_path() on the result.
7418  *
7419  * Returns: (transfer full): a new #GFile
7420  *
7421  * Since: 2.78
7422  */
7423 GFile *
7424 g_file_new_build_filenamev (const gchar * const *args)
7425 {
7426   gchar *str;
7427   GFile *file;
7428
7429   str = g_build_filenamev ((gchar **) args);
7430   file = g_file_new_for_path (str);
7431   g_free (str);
7432
7433   return file;
7434 }
7435
7436 static gboolean
7437 is_valid_scheme_character (char c)
7438 {
7439   return g_ascii_isalnum (c) || c == '+' || c == '-' || c == '.';
7440 }
7441
7442 /* Following RFC 2396, valid schemes are built like:
7443  *       scheme        = alpha *( alpha | digit | "+" | "-" | "." )
7444  */
7445 static gboolean
7446 has_valid_scheme (const char *uri)
7447 {
7448   const char *p;
7449
7450   p = uri;
7451
7452   if (!g_ascii_isalpha (*p))
7453     return FALSE;
7454
7455   do {
7456     p++;
7457   } while (is_valid_scheme_character (*p));
7458
7459   return *p == ':';
7460 }
7461
7462 static GFile *
7463 new_for_cmdline_arg (const gchar *arg,
7464                      const gchar *cwd)
7465 {
7466   GFile *file;
7467   char *filename;
7468
7469   if (g_path_is_absolute (arg))
7470     return g_file_new_for_path (arg);
7471
7472   if (has_valid_scheme (arg))
7473     return g_file_new_for_uri (arg);
7474
7475   if (cwd == NULL)
7476     {
7477       char *current_dir;
7478
7479       current_dir = g_get_current_dir ();
7480       filename = g_build_filename (current_dir, arg, NULL);
7481       g_free (current_dir);
7482     }
7483   else
7484     filename = g_build_filename (cwd, arg, NULL);
7485
7486   file = g_file_new_for_path (filename);
7487   g_free (filename);
7488
7489   return file;
7490 }
7491
7492 /**
7493  * g_file_new_for_commandline_arg:
7494  * @arg: (type filename): a command line string
7495  *
7496  * Creates a #GFile with the given argument from the command line.
7497  * The value of @arg can be either a URI, an absolute path or a
7498  * relative path resolved relative to the current working directory.
7499  * This operation never fails, but the returned object might not
7500  * support any I/O operation if @arg points to a malformed path.
7501  *
7502  * Note that on Windows, this function expects its argument to be in
7503  * UTF-8 -- not the system code page.  This means that you
7504  * should not use this function with string from argv as it is passed
7505  * to main().  g_win32_get_command_line() will return a UTF-8 version of
7506  * the commandline.  #GApplication also uses UTF-8 but
7507  * g_application_command_line_create_file_for_arg() may be more useful
7508  * for you there.  It is also always possible to use this function with
7509  * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
7510  *
7511  * Returns: (transfer full): a new #GFile.
7512  *   Free the returned object with g_object_unref().
7513  */
7514 GFile *
7515 g_file_new_for_commandline_arg (const char *arg)
7516 {
7517   g_return_val_if_fail (arg != NULL, NULL);
7518
7519   return new_for_cmdline_arg (arg, NULL);
7520 }
7521
7522 /**
7523  * g_file_new_for_commandline_arg_and_cwd:
7524  * @arg: (type filename): a command line string
7525  * @cwd: (type filename): the current working directory of the commandline
7526  *
7527  * Creates a #GFile with the given argument from the command line.
7528  *
7529  * This function is similar to g_file_new_for_commandline_arg() except
7530  * that it allows for passing the current working directory as an
7531  * argument instead of using the current working directory of the
7532  * process.
7533  *
7534  * This is useful if the commandline argument was given in a context
7535  * other than the invocation of the current process.
7536  *
7537  * See also g_application_command_line_create_file_for_arg().
7538  *
7539  * Returns: (transfer full): a new #GFile
7540  *
7541  * Since: 2.36
7542  **/
7543 GFile *
7544 g_file_new_for_commandline_arg_and_cwd (const gchar *arg,
7545                                         const gchar *cwd)
7546 {
7547   g_return_val_if_fail (arg != NULL, NULL);
7548   g_return_val_if_fail (cwd != NULL, NULL);
7549
7550   return new_for_cmdline_arg (arg, cwd);
7551 }
7552
7553 /**
7554  * g_file_mount_enclosing_volume:
7555  * @location: input #GFile
7556  * @flags: flags affecting the operation
7557  * @mount_operation: (nullable): a #GMountOperation
7558  *   or %NULL to avoid user interaction
7559  * @cancellable: (nullable): optional #GCancellable object,
7560  *   %NULL to ignore
7561  * @callback: (nullable): a #GAsyncReadyCallback to call
7562  *   when the request is satisfied, or %NULL
7563  * @user_data: the data to pass to callback function
7564  *
7565  * Starts a @mount_operation, mounting the volume that contains
7566  * the file @location.
7567  *
7568  * When this operation has completed, @callback will be called with
7569  * @user_user data, and the operation can be finalized with
7570  * g_file_mount_enclosing_volume_finish().
7571  *
7572  * If @cancellable is not %NULL, then the operation can be cancelled by
7573  * triggering the cancellable object from another thread. If the operation
7574  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7575  */
7576 void
7577 g_file_mount_enclosing_volume (GFile               *location,
7578                                GMountMountFlags     flags,
7579                                GMountOperation     *mount_operation,
7580                                GCancellable        *cancellable,
7581                                GAsyncReadyCallback  callback,
7582                                gpointer             user_data)
7583 {
7584   GFileIface *iface;
7585
7586   g_return_if_fail (G_IS_FILE (location));
7587
7588   iface = G_FILE_GET_IFACE (location);
7589
7590   if (iface->mount_enclosing_volume == NULL)
7591     {
7592       g_task_report_new_error (location, callback, user_data,
7593                                g_file_mount_enclosing_volume,
7594                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7595                                _("volume doesn’t implement mount"));
7596       return;
7597     }
7598
7599   (* iface->mount_enclosing_volume) (location, flags, mount_operation, cancellable, callback, user_data);
7600
7601 }
7602
7603 /**
7604  * g_file_mount_enclosing_volume_finish:
7605  * @location: input #GFile
7606  * @result: a #GAsyncResult
7607  * @error: a #GError, or %NULL
7608  *
7609  * Finishes a mount operation started by g_file_mount_enclosing_volume().
7610  *
7611  * Returns: %TRUE if successful. If an error has occurred,
7612  *   this function will return %FALSE and set @error
7613  *   appropriately if present.
7614  */
7615 gboolean
7616 g_file_mount_enclosing_volume_finish (GFile         *location,
7617                                       GAsyncResult  *result,
7618                                       GError       **error)
7619 {
7620   GFileIface *iface;
7621
7622   g_return_val_if_fail (G_IS_FILE (location), FALSE);
7623   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
7624
7625   if (g_async_result_legacy_propagate_error (result, error))
7626     return FALSE;
7627   else if (g_async_result_is_tagged (result, g_file_mount_enclosing_volume))
7628     return g_task_propagate_boolean (G_TASK (result), error);
7629
7630   iface = G_FILE_GET_IFACE (location);
7631
7632   return (* iface->mount_enclosing_volume_finish) (location, result, error);
7633 }
7634
7635 /********************************************
7636  *   Utility functions                      *
7637  ********************************************/
7638
7639 /**
7640  * g_file_query_default_handler:
7641  * @file: a #GFile to open
7642  * @cancellable: optional #GCancellable object, %NULL to ignore
7643  * @error: a #GError, or %NULL
7644  *
7645  * Returns the #GAppInfo that is registered as the default
7646  * application to handle the file specified by @file.
7647  *
7648  * If @cancellable is not %NULL, then the operation can be cancelled by
7649  * triggering the cancellable object from another thread. If the operation
7650  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7651  *
7652  * Returns: (transfer full): a #GAppInfo if the handle was found,
7653  *   %NULL if there were errors.
7654  *   When you are done with it, release it with g_object_unref()
7655  */
7656 GAppInfo *
7657 g_file_query_default_handler (GFile         *file,
7658                               GCancellable  *cancellable,
7659                               GError       **error)
7660 {
7661   char *uri_scheme;
7662   const char *content_type;
7663   GAppInfo *appinfo;
7664   GFileInfo *info;
7665   char *path;
7666
7667   uri_scheme = g_file_get_uri_scheme (file);
7668   if (uri_scheme && uri_scheme[0] != '\0')
7669     {
7670       appinfo = g_app_info_get_default_for_uri_scheme (uri_scheme);
7671       g_free (uri_scheme);
7672
7673       if (appinfo != NULL)
7674         return appinfo;
7675     }
7676   else
7677     g_free (uri_scheme);
7678
7679   info = g_file_query_info (file,
7680                             G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE ","
7681                             G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE,
7682                             0,
7683                             cancellable,
7684                             error);
7685   if (info == NULL)
7686     return NULL;
7687
7688   appinfo = NULL;
7689
7690   content_type = g_file_info_get_content_type (info);
7691   if (content_type == NULL)
7692     content_type = g_file_info_get_attribute_string (info, G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE);
7693   if (content_type)
7694     {
7695       /* Don't use is_native(), as we want to support fuse paths if available */
7696       path = g_file_get_path (file);
7697       appinfo = g_app_info_get_default_for_type (content_type,
7698                                                  path == NULL);
7699       g_free (path);
7700     }
7701
7702   g_object_unref (info);
7703
7704   if (appinfo != NULL)
7705     return appinfo;
7706
7707   g_set_error_literal (error, G_IO_ERROR,
7708                        G_IO_ERROR_NOT_SUPPORTED,
7709                        _("No application is registered as handling this file"));
7710   return NULL;
7711 }
7712
7713 static void
7714 query_default_handler_query_app_info_for_type_cb (GObject      *object,
7715                                                   GAsyncResult *result,
7716                                                   gpointer      user_data)
7717 {
7718   GTask *task = G_TASK (user_data);
7719   GAppInfo *appinfo;
7720   GError *error = NULL;
7721
7722   appinfo = g_app_info_get_default_for_type_finish (result, &error);
7723
7724   if (appinfo != NULL)
7725     {
7726       g_task_return_pointer (task, g_steal_pointer (&appinfo), g_object_unref);
7727     }
7728   else if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
7729     {
7730       g_task_return_new_error (task,
7731                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7732                                "%s", error->message);
7733     }
7734   else
7735     {
7736       g_task_return_error (task, g_steal_pointer (&error));
7737     }
7738
7739   g_clear_error (&error);
7740   g_object_unref (task);
7741 }
7742
7743 static void
7744 query_default_handler_query_info_cb (GObject      *object,
7745                                      GAsyncResult *result,
7746                                      gpointer      user_data)
7747 {
7748   GFile *file = G_FILE (object);
7749   GTask *task = G_TASK (user_data);
7750   GError *error = NULL;
7751   GFileInfo *info;
7752   const char *content_type;
7753
7754   info = g_file_query_info_finish (file, result, &error);
7755   if (info == NULL)
7756     {
7757       g_task_return_error (task, g_steal_pointer (&error));
7758       g_object_unref (task);
7759       return;
7760     }
7761
7762   content_type = g_file_info_get_content_type (info);
7763   if (content_type == NULL)
7764     content_type = g_file_info_get_attribute_string (info, G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE);
7765   if (content_type)
7766     {
7767       GCancellable *cancellable = g_task_get_cancellable (task);
7768       char *path;
7769
7770       /* Don't use is_native(), as we want to support fuse paths if available */
7771       path = g_file_get_path (file);
7772
7773       g_app_info_get_default_for_type_async (content_type,
7774                                              path == NULL,
7775                                              cancellable,
7776                                              query_default_handler_query_app_info_for_type_cb,
7777                                              g_steal_pointer (&task));
7778
7779       g_free (path);
7780     }
7781   else
7782     {
7783       g_task_return_new_error (task,
7784                                G_IO_ERROR,
7785                                G_IO_ERROR_NOT_SUPPORTED,
7786                                _("No application is registered as handling this file"));
7787     }
7788
7789   g_object_unref (info);
7790   g_clear_object (&task);
7791 }
7792
7793 static void
7794 on_query_default_handler_for_uri_cb (GObject      *object,
7795                                      GAsyncResult *result,
7796                                      gpointer      user_data)
7797 {
7798   GTask *task = user_data;
7799   GAppInfo *app_info;
7800
7801   app_info = g_app_info_get_default_for_uri_scheme_finish (result, NULL);
7802
7803   if (app_info)
7804     {
7805       g_task_return_pointer (task, g_steal_pointer (&app_info), g_object_unref);
7806       g_object_unref (task);
7807     }
7808   else
7809     {
7810       g_file_query_info_async (g_task_get_source_object (task),
7811                                G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE ","
7812                                G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE,
7813                                0,
7814                                g_task_get_priority (task),
7815                                g_task_get_cancellable (task),
7816                                query_default_handler_query_info_cb,
7817                                task);
7818     }
7819 }
7820
7821 /**
7822  * g_file_query_default_handler_async:
7823  * @file: a #GFile to open
7824  * @io_priority: the [I/O priority][io-priority] of the request
7825  * @cancellable: optional #GCancellable object, %NULL to ignore
7826  * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done
7827  * @user_data: (nullable): data to pass to @callback
7828  *
7829  * Async version of g_file_query_default_handler().
7830  *
7831  * Since: 2.60
7832  */
7833 void
7834 g_file_query_default_handler_async (GFile              *file,
7835                                     int                 io_priority,
7836                                     GCancellable       *cancellable,
7837                                     GAsyncReadyCallback callback,
7838                                     gpointer            user_data)
7839 {
7840   GTask *task;
7841   char *uri_scheme;
7842
7843   task = g_task_new (file, cancellable, callback, user_data);
7844   g_task_set_source_tag (task, g_file_query_default_handler_async);
7845
7846   uri_scheme = g_file_get_uri_scheme (file);
7847   if (uri_scheme && uri_scheme[0] != '\0')
7848     {
7849       g_app_info_get_default_for_uri_scheme_async (uri_scheme,
7850                                                    cancellable,
7851                                                    on_query_default_handler_for_uri_cb,
7852                                                    g_steal_pointer (&task));
7853       g_free (uri_scheme);
7854       return;
7855     }
7856
7857   g_file_query_info_async (file,
7858                            G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE ","
7859                            G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE,
7860                            0,
7861                            io_priority,
7862                            cancellable,
7863                            query_default_handler_query_info_cb,
7864                            g_steal_pointer (&task));
7865
7866   g_free (uri_scheme);
7867 }
7868
7869 /**
7870  * g_file_query_default_handler_finish:
7871  * @file: a #GFile to open
7872  * @result: a #GAsyncResult
7873  * @error: (nullable): a #GError
7874  *
7875  * Finishes a g_file_query_default_handler_async() operation.
7876  *
7877  * Returns: (transfer full): a #GAppInfo if the handle was found,
7878  *   %NULL if there were errors.
7879  *   When you are done with it, release it with g_object_unref()
7880  *
7881  * Since: 2.60
7882  */
7883 GAppInfo *
7884 g_file_query_default_handler_finish (GFile        *file,
7885                                      GAsyncResult *result,
7886                                      GError      **error)
7887 {
7888   g_return_val_if_fail (G_IS_FILE (file), NULL);
7889   g_return_val_if_fail (g_task_is_valid (result, file), NULL);
7890
7891   return g_task_propagate_pointer (G_TASK (result), error);
7892 }
7893
7894 #define GET_CONTENT_BLOCK_SIZE 8192
7895
7896 /**
7897  * g_file_load_contents:
7898  * @file: input #GFile
7899  * @cancellable: optional #GCancellable object, %NULL to ignore
7900  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
7901  * @length: (out) (optional): a location to place the length of the contents of the file,
7902  *   or %NULL if the length is not needed
7903  * @etag_out: (out) (optional) (nullable): a location to place the current entity tag for the file,
7904  *   or %NULL if the entity tag is not needed
7905  * @error: a #GError, or %NULL
7906  *
7907  * Loads the content of the file into memory. The data is always
7908  * zero-terminated, but this is not included in the resultant @length.
7909  * The returned @contents should be freed with g_free() when no longer
7910  * needed.
7911  *
7912  * If @cancellable is not %NULL, then the operation can be cancelled by
7913  * triggering the cancellable object from another thread. If the operation
7914  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7915  *
7916  * Returns: %TRUE if the @file's contents were successfully loaded.
7917  *   %FALSE if there were errors.
7918  */
7919 gboolean
7920 g_file_load_contents (GFile         *file,
7921                       GCancellable  *cancellable,
7922                       char         **contents,
7923                       gsize         *length,
7924                       char         **etag_out,
7925                       GError       **error)
7926 {
7927   GFileInputStream *in;
7928   GByteArray *content;
7929   gsize pos;
7930   gssize res;
7931   GFileInfo *info;
7932
7933   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7934   g_return_val_if_fail (contents != NULL, FALSE);
7935
7936   in = g_file_read (file, cancellable, error);
7937   if (in == NULL)
7938     return FALSE;
7939
7940   content = g_byte_array_new ();
7941   pos = 0;
7942
7943   g_byte_array_set_size (content, pos + GET_CONTENT_BLOCK_SIZE + 1);
7944   while ((res = g_input_stream_read (G_INPUT_STREAM (in),
7945                                      content->data + pos,
7946                                      GET_CONTENT_BLOCK_SIZE,
7947                                      cancellable, error)) > 0)
7948     {
7949       pos += res;
7950       g_byte_array_set_size (content, pos + GET_CONTENT_BLOCK_SIZE + 1);
7951     }
7952
7953   if (etag_out)
7954     {
7955       *etag_out = NULL;
7956
7957       info = g_file_input_stream_query_info (in,
7958                                              G_FILE_ATTRIBUTE_ETAG_VALUE,
7959                                              cancellable,
7960                                              NULL);
7961       if (info)
7962         {
7963           *etag_out = g_file_info_has_attribute (info, G_FILE_ATTRIBUTE_ETAG_VALUE) ? g_strdup (g_file_info_get_etag (info)) : NULL;
7964           g_object_unref (info);
7965         }
7966     }
7967
7968   /* Ignore errors on close */
7969   g_input_stream_close (G_INPUT_STREAM (in), cancellable, NULL);
7970   g_object_unref (in);
7971
7972   if (res < 0)
7973     {
7974       /* error is set already */
7975       g_byte_array_free (content, TRUE);
7976       return FALSE;
7977     }
7978
7979   if (length)
7980     *length = pos;
7981
7982   /* Zero terminate (we got an extra byte allocated for this */
7983   content->data[pos] = 0;
7984
7985   *contents = (char *)g_byte_array_free (content, FALSE);
7986
7987   return TRUE;
7988 }
7989
7990 typedef struct {
7991   GTask *task;
7992   GFileReadMoreCallback read_more_callback;
7993   GByteArray *content;
7994   gsize pos;
7995   char *etag;
7996 } LoadContentsData;
7997
7998
7999 static void
8000 load_contents_data_free (LoadContentsData *data)
8001 {
8002   if (data->content)
8003     g_byte_array_free (data->content, TRUE);
8004   g_free (data->etag);
8005   g_free (data);
8006 }
8007
8008 static void
8009 load_contents_close_callback (GObject      *obj,
8010                               GAsyncResult *close_res,
8011                               gpointer      user_data)
8012 {
8013   GInputStream *stream = G_INPUT_STREAM (obj);
8014   LoadContentsData *data = user_data;
8015
8016   /* Ignore errors here, we're only reading anyway */
8017   g_input_stream_close_finish (stream, close_res, NULL);
8018   g_object_unref (stream);
8019
8020   g_task_return_boolean (data->task, TRUE);
8021   g_object_unref (data->task);
8022 }
8023
8024 static void
8025 load_contents_fstat_callback (GObject      *obj,
8026                               GAsyncResult *stat_res,
8027                               gpointer      user_data)
8028 {
8029   GInputStream *stream = G_INPUT_STREAM (obj);
8030   LoadContentsData *data = user_data;
8031   GFileInfo *info;
8032
8033   info = g_file_input_stream_query_info_finish (G_FILE_INPUT_STREAM (stream),
8034                                                 stat_res, NULL);
8035   if (info)
8036     {
8037       data->etag = g_file_info_has_attribute (info, G_FILE_ATTRIBUTE_ETAG_VALUE) ? g_strdup (g_file_info_get_etag (info)) : NULL;
8038       g_object_unref (info);
8039     }
8040
8041   g_input_stream_close_async (stream, 0,
8042                               g_task_get_cancellable (data->task),
8043                               load_contents_close_callback, data);
8044 }
8045
8046 static void
8047 load_contents_read_callback (GObject      *obj,
8048                              GAsyncResult *read_res,
8049                              gpointer      user_data)
8050 {
8051   GInputStream *stream = G_INPUT_STREAM (obj);
8052   LoadContentsData *data = user_data;
8053   GError *error = NULL;
8054   gssize read_size;
8055
8056   read_size = g_input_stream_read_finish (stream, read_res, &error);
8057
8058   if (read_size < 0)
8059     {
8060       g_task_return_error (data->task, error);
8061       g_object_unref (data->task);
8062
8063       /* Close the file ignoring any error */
8064       g_input_stream_close_async (stream, 0, NULL, NULL, NULL);
8065       g_object_unref (stream);
8066     }
8067   else if (read_size == 0)
8068     {
8069       g_file_input_stream_query_info_async (G_FILE_INPUT_STREAM (stream),
8070                                             G_FILE_ATTRIBUTE_ETAG_VALUE,
8071                                             0,
8072                                             g_task_get_cancellable (data->task),
8073                                             load_contents_fstat_callback,
8074                                             data);
8075     }
8076   else if (read_size > 0)
8077     {
8078       data->pos += read_size;
8079
8080       g_byte_array_set_size (data->content,
8081                              data->pos + GET_CONTENT_BLOCK_SIZE);
8082
8083
8084       if (data->read_more_callback &&
8085           !data->read_more_callback ((char *)data->content->data, data->pos,
8086                                      g_async_result_get_user_data (G_ASYNC_RESULT (data->task))))
8087         g_file_input_stream_query_info_async (G_FILE_INPUT_STREAM (stream),
8088                                               G_FILE_ATTRIBUTE_ETAG_VALUE,
8089                                               0,
8090                                               g_task_get_cancellable (data->task),
8091                                               load_contents_fstat_callback,
8092                                               data);
8093       else
8094         g_input_stream_read_async (stream,
8095                                    data->content->data + data->pos,
8096                                    GET_CONTENT_BLOCK_SIZE,
8097                                    0,
8098                                    g_task_get_cancellable (data->task),
8099                                    load_contents_read_callback,
8100                                    data);
8101     }
8102 }
8103
8104 static void
8105 load_contents_open_callback (GObject      *obj,
8106                              GAsyncResult *open_res,
8107                              gpointer      user_data)
8108 {
8109   GFile *file = G_FILE (obj);
8110   GFileInputStream *stream;
8111   LoadContentsData *data = user_data;
8112   GError *error = NULL;
8113
8114   stream = g_file_read_finish (file, open_res, &error);
8115
8116   if (stream)
8117     {
8118       g_byte_array_set_size (data->content,
8119                              data->pos + GET_CONTENT_BLOCK_SIZE);
8120       g_input_stream_read_async (G_INPUT_STREAM (stream),
8121                                  data->content->data + data->pos,
8122                                  GET_CONTENT_BLOCK_SIZE,
8123                                  0,
8124                                  g_task_get_cancellable (data->task),
8125                                  load_contents_read_callback,
8126                                  data);
8127     }
8128   else
8129     {
8130       g_task_return_error (data->task, error);
8131       g_object_unref (data->task);
8132     }
8133 }
8134
8135 /**
8136  * g_file_load_partial_contents_async: (skip)
8137  * @file: input #GFile
8138  * @cancellable: optional #GCancellable object, %NULL to ignore
8139  * @read_more_callback: (scope call) (closure user_data): a
8140  *   #GFileReadMoreCallback to receive partial data
8141  *   and to specify whether further data should be read
8142  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback to call
8143  *   when the request is satisfied
8144  * @user_data: the data to pass to the callback functions
8145  *
8146  * Reads the partial contents of a file. A #GFileReadMoreCallback should
8147  * be used to stop reading from the file when appropriate, else this
8148  * function will behave exactly as g_file_load_contents_async(). This
8149  * operation can be finished by g_file_load_partial_contents_finish().
8150  *
8151  * Users of this function should be aware that @user_data is passed to
8152  * both the @read_more_callback and the @callback.
8153  *
8154  * If @cancellable is not %NULL, then the operation can be cancelled by
8155  * triggering the cancellable object from another thread. If the operation
8156  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
8157  */
8158 void
8159 g_file_load_partial_contents_async (GFile                 *file,
8160                                     GCancellable          *cancellable,
8161                                     GFileReadMoreCallback  read_more_callback,
8162                                     GAsyncReadyCallback    callback,
8163                                     gpointer               user_data)
8164 {
8165   LoadContentsData *data;
8166
8167   g_return_if_fail (G_IS_FILE (file));
8168
8169   data = g_new0 (LoadContentsData, 1);
8170   data->read_more_callback = read_more_callback;
8171   data->content = g_byte_array_new ();
8172
8173   data->task = g_task_new (file, cancellable, callback, user_data);
8174   g_task_set_source_tag (data->task, g_file_load_partial_contents_async);
8175   g_task_set_task_data (data->task, data, (GDestroyNotify)load_contents_data_free);
8176
8177   g_file_read_async (file,
8178                      0,
8179                      g_task_get_cancellable (data->task),
8180                      load_contents_open_callback,
8181                      data);
8182 }
8183
8184 /**
8185  * g_file_load_partial_contents_finish:
8186  * @file: input #GFile
8187  * @res: a #GAsyncResult
8188  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
8189  * @length: (out) (optional): a location to place the length of the contents of the file,
8190  *   or %NULL if the length is not needed
8191  * @etag_out: (out) (optional) (nullable): a location to place the current entity tag for the file,
8192  *   or %NULL if the entity tag is not needed
8193  * @error: a #GError, or %NULL
8194  *
8195  * Finishes an asynchronous partial load operation that was started
8196  * with g_file_load_partial_contents_async(). The data is always
8197  * zero-terminated, but this is not included in the resultant @length.
8198  * The returned @contents should be freed with g_free() when no longer
8199  * needed.
8200  *
8201  * Returns: %TRUE if the load was successful. If %FALSE and @error is
8202  *   present, it will be set appropriately.
8203  */
8204 gboolean
8205 g_file_load_partial_contents_finish (GFile         *file,
8206                                      GAsyncResult  *res,
8207                                      char         **contents,
8208                                      gsize         *length,
8209                                      char         **etag_out,
8210                                      GError       **error)
8211 {
8212   GTask *task;
8213   LoadContentsData *data;
8214
8215   g_return_val_if_fail (G_IS_FILE (file), FALSE);
8216   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
8217   g_return_val_if_fail (contents != NULL, FALSE);
8218
8219   task = G_TASK (res);
8220
8221   if (!g_task_propagate_boolean (task, error))
8222     {
8223       if (length)
8224         *length = 0;
8225       return FALSE;
8226     }
8227
8228   data = g_task_get_task_data (task);
8229
8230   if (length)
8231     *length = data->pos;
8232
8233   if (etag_out)
8234     {
8235       *etag_out = data->etag;
8236       data->etag = NULL;
8237     }
8238
8239   /* Zero terminate */
8240   g_byte_array_set_size (data->content, data->pos + 1);
8241   data->content->data[data->pos] = 0;
8242
8243   *contents = (char *)g_byte_array_free (data->content, FALSE);
8244   data->content = NULL;
8245
8246   return TRUE;
8247 }
8248
8249 /**
8250  * g_file_load_contents_async:
8251  * @file: input #GFile
8252  * @cancellable: optional #GCancellable object, %NULL to ignore
8253  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
8254  * @user_data: the data to pass to callback function
8255  *
8256  * Starts an asynchronous load of the @file's contents.
8257  *
8258  * For more details, see g_file_load_contents() which is
8259  * the synchronous version of this call.
8260  *
8261  * When the load operation has completed, @callback will be called
8262  * with @user data. To finish the operation, call
8263  * g_file_load_contents_finish() with the #GAsyncResult returned by
8264  * the @callback.
8265  *
8266  * If @cancellable is not %NULL, then the operation can be cancelled by
8267  * triggering the cancellable object from another thread. If the operation
8268  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
8269  */
8270 void
8271 g_file_load_contents_async (GFile               *file,
8272                            GCancellable        *cancellable,
8273                            GAsyncReadyCallback  callback,
8274                            gpointer             user_data)
8275 {
8276   g_file_load_partial_contents_async (file,
8277                                       cancellable,
8278                                       NULL,
8279                                       callback, user_data);
8280 }
8281
8282 /**
8283  * g_file_load_contents_finish:
8284  * @file: input #GFile
8285  * @res: a #GAsyncResult
8286  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
8287  * @length: (out) (optional): a location to place the length of the contents of the file,
8288  *   or %NULL if the length is not needed
8289  * @etag_out: (out) (optional) (nullable): a location to place the current entity tag for the file,
8290  *   or %NULL if the entity tag is not needed
8291  * @error: a #GError, or %NULL
8292  *
8293  * Finishes an asynchronous load of the @file's contents.
8294  * The contents are placed in @contents, and @length is set to the
8295  * size of the @contents string. The @contents should be freed with
8296  * g_free() when no longer needed. If @etag_out is present, it will be
8297  * set to the new entity tag for the @file.
8298  *
8299  * Returns: %TRUE if the load was successful. If %FALSE and @error is
8300  *   present, it will be set appropriately.
8301  */
8302 gboolean
8303 g_file_load_contents_finish (GFile         *file,
8304                              GAsyncResult  *res,
8305                              char         **contents,
8306                              gsize         *length,
8307                              char         **etag_out,
8308                              GError       **error)
8309 {
8310   return g_file_load_partial_contents_finish (file,
8311                                               res,
8312                                               contents,
8313                                               length,
8314                                               etag_out,
8315                                               error);
8316 }
8317
8318 /**
8319  * g_file_replace_contents:
8320  * @file: input #GFile
8321  * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
8322  * @length: the length of @contents in bytes
8323  * @etag: (nullable): the old [entity-tag][gfile-etag] for the document,
8324  *   or %NULL
8325  * @make_backup: %TRUE if a backup should be created
8326  * @flags: a set of #GFileCreateFlags
8327  * @new_etag: (out) (optional) (nullable): a location to a new [entity tag][gfile-etag]
8328  *   for the document. This should be freed with g_free() when no longer
8329  *   needed, or %NULL
8330  * @cancellable: optional #GCancellable object, %NULL to ignore
8331  * @error: a #GError, or %NULL
8332  *
8333  * Replaces the contents of @file with @contents of @length bytes.
8334  *
8335  * If @etag is specified (not %NULL), any existing file must have that etag,
8336  * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
8337  *
8338  * If @make_backup is %TRUE, this function will attempt to make a backup
8339  * of @file. Internally, it uses g_file_replace(), so will try to replace the
8340  * file contents in the safest way possible. For example, atomic renames are
8341  * used when replacing local files’ contents.
8342  *
8343  * If @cancellable is not %NULL, then the operation can be cancelled by
8344  * triggering the cancellable object from another thread. If the operation
8345  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
8346  *
8347  * The returned @new_etag can be used to verify that the file hasn't
8348  * changed the next time it is saved over.
8349  *
8350  * Returns: %TRUE if successful. If an error has occurred, this function
8351  *   will return %FALSE and set @error appropriately if present.
8352  */
8353 gboolean
8354 g_file_replace_contents (GFile             *file,
8355                          const char        *contents,
8356                          gsize              length,
8357                          const char        *etag,
8358                          gboolean           make_backup,
8359                          GFileCreateFlags   flags,
8360                          char             **new_etag,
8361                          GCancellable      *cancellable,
8362                          GError           **error)
8363 {
8364   GFileOutputStream *out;
8365   gsize pos, remainder;
8366   gssize res = -1;
8367   gboolean ret;
8368
8369   g_return_val_if_fail (G_IS_FILE (file), FALSE);
8370   g_return_val_if_fail (contents != NULL, FALSE);
8371
8372   out = g_file_replace (file, etag, make_backup, flags, cancellable, error);
8373   if (out == NULL)
8374     return FALSE;
8375
8376   pos = 0;
8377   remainder = length;
8378   while (remainder > 0 &&
8379          (res = g_output_stream_write (G_OUTPUT_STREAM (out),
8380                                        contents + pos,
8381                                        MIN (remainder, GET_CONTENT_BLOCK_SIZE),
8382                                        cancellable,
8383                                        error)) > 0)
8384     {
8385       pos += res;
8386       remainder -= res;
8387     }
8388
8389   if (remainder > 0 && res < 0)
8390     {
8391       /* Ignore errors on close */
8392       g_output_stream_close (G_OUTPUT_STREAM (out), cancellable, NULL);
8393       g_object_unref (out);
8394
8395       /* error is set already */
8396       return FALSE;
8397     }
8398
8399   ret = g_output_stream_close (G_OUTPUT_STREAM (out), cancellable, error);
8400
8401   if (new_etag)
8402     *new_etag = g_file_output_stream_get_etag (out);
8403
8404   g_object_unref (out);
8405
8406   return ret;
8407 }
8408
8409 typedef struct {
8410   GTask *task;
8411   GBytes *content;
8412   gsize pos;
8413   char *etag;
8414   gboolean failed;
8415 } ReplaceContentsData;
8416
8417 static void
8418 replace_contents_data_free (ReplaceContentsData *data)
8419 {
8420   g_bytes_unref (data->content);
8421   g_free (data->etag);
8422   g_free (data);
8423 }
8424
8425 static void
8426 replace_contents_close_callback (GObject      *obj,
8427                                  GAsyncResult *close_res,
8428                                  gpointer      user_data)
8429 {
8430   GOutputStream *stream = G_OUTPUT_STREAM (obj);
8431   ReplaceContentsData *data = user_data;
8432
8433   /* Ignore errors here, we're only reading anyway */
8434   g_output_stream_close_finish (stream, close_res, NULL);
8435
8436   if (!data->failed)
8437     {
8438       data->etag = g_file_output_stream_get_etag (G_FILE_OUTPUT_STREAM (stream));
8439       g_task_return_boolean (data->task, TRUE);
8440     }
8441   g_object_unref (data->task);
8442 }
8443
8444 static void
8445 replace_contents_write_callback (GObject      *obj,
8446                                  GAsyncResult *read_res,
8447                                  gpointer      user_data)
8448 {
8449   GOutputStream *stream = G_OUTPUT_STREAM (obj);
8450   ReplaceContentsData *data = user_data;
8451   GError *error = NULL;
8452   gssize write_size;
8453
8454   write_size = g_output_stream_write_finish (stream, read_res, &error);
8455
8456   if (write_size <= 0)
8457     {
8458       /* Error or EOF, close the file */
8459       if (write_size < 0)
8460         {
8461           data->failed = TRUE;
8462           g_task_return_error (data->task, error);
8463         }
8464       g_output_stream_close_async (stream, 0,
8465                                    g_task_get_cancellable (data->task),
8466                                    replace_contents_close_callback, data);
8467     }
8468   else if (write_size > 0)
8469     {
8470       const gchar *content;
8471       gsize length;
8472
8473       content = g_bytes_get_data (data->content, &length);
8474       data->pos += write_size;
8475
8476       if (data->pos >= length)
8477         g_output_stream_close_async (stream, 0,
8478                                      g_task_get_cancellable (data->task),
8479                                      replace_contents_close_callback, data);
8480       else
8481         g_output_stream_write_async (stream,
8482                                      content + data->pos,
8483                                      length - data->pos,
8484                                      0,
8485                                      g_task_get_cancellable (data->task),
8486                                      replace_contents_write_callback,
8487                                      data);
8488     }
8489 }
8490
8491 static void
8492 replace_contents_open_callback (GObject      *obj,
8493                                 GAsyncResult *open_res,
8494                                 gpointer      user_data)
8495 {
8496   GFile *file = G_FILE (obj);
8497   GFileOutputStream *stream;
8498   ReplaceContentsData *data = user_data;
8499   GError *error = NULL;
8500
8501   stream = g_file_replace_finish (file, open_res, &error);
8502
8503   if (stream)
8504     {
8505       const gchar *content;
8506       gsize length;
8507
8508       content = g_bytes_get_data (data->content, &length);
8509       g_output_stream_write_async (G_OUTPUT_STREAM (stream),
8510                                    content + data->pos,
8511                                    length - data->pos,
8512                                    0,
8513                                    g_task_get_cancellable (data->task),
8514                                    replace_contents_write_callback,
8515                                    data);
8516       g_object_unref (stream);  /* ownership is transferred to the write_async() call above */
8517     }
8518   else
8519     {
8520       g_task_return_error (data->task, error);
8521       g_object_unref (data->task);
8522     }
8523 }
8524
8525 /**
8526  * g_file_replace_contents_async:
8527  * @file: input #GFile
8528  * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
8529  * @length: the length of @contents in bytes
8530  * @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL
8531  * @make_backup: %TRUE if a backup should be created
8532  * @flags: a set of #GFileCreateFlags
8533  * @cancellable: optional #GCancellable object, %NULL to ignore
8534  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
8535  * @user_data: the data to pass to callback function
8536  *
8537  * Starts an asynchronous replacement of @file with the given
8538  * @contents of @length bytes. @etag will replace the document's
8539  * current entity tag.
8540  *
8541  * When this operation has completed, @callback will be called with
8542  * @user_user data, and the operation can be finalized with
8543  * g_file_replace_contents_finish().
8544  *
8545  * If @cancellable is not %NULL, then the operation can be cancelled by
8546  * triggering the cancellable object from another thread. If the operation
8547  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
8548  *
8549  * If @make_backup is %TRUE, this function will attempt to
8550  * make a backup of @file.
8551  *
8552  * Note that no copy of @contents will be made, so it must stay valid
8553  * until @callback is called. See g_file_replace_contents_bytes_async()
8554  * for a #GBytes version that will automatically hold a reference to the
8555  * contents (without copying) for the duration of the call.
8556  */
8557 void
8558 g_file_replace_contents_async  (GFile               *file,
8559                                 const char          *contents,
8560                                 gsize                length,
8561                                 const char          *etag,
8562                                 gboolean             make_backup,
8563                                 GFileCreateFlags     flags,
8564                                 GCancellable        *cancellable,
8565                                 GAsyncReadyCallback  callback,
8566                                 gpointer             user_data)
8567 {
8568   GBytes *bytes;
8569
8570   bytes = g_bytes_new_static (contents, length);
8571   g_file_replace_contents_bytes_async (file, bytes, etag, make_backup, flags,
8572       cancellable, callback, user_data);
8573   g_bytes_unref (bytes);
8574 }
8575
8576 /**
8577  * g_file_replace_contents_bytes_async:
8578  * @file: input #GFile
8579  * @contents: a #GBytes
8580  * @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL
8581  * @make_backup: %TRUE if a backup should be created
8582  * @flags: a set of #GFileCreateFlags
8583  * @cancellable: optional #GCancellable object, %NULL to ignore
8584  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
8585  * @user_data: the data to pass to callback function
8586  *
8587  * Same as g_file_replace_contents_async() but takes a #GBytes input instead.
8588  * This function will keep a ref on @contents until the operation is done.
8589  * Unlike g_file_replace_contents_async() this allows forgetting about the
8590  * content without waiting for the callback.
8591  *
8592  * When this operation has completed, @callback will be called with
8593  * @user_user data, and the operation can be finalized with
8594  * g_file_replace_contents_finish().
8595  *
8596  * Since: 2.40
8597  */
8598 void
8599 g_file_replace_contents_bytes_async  (GFile               *file,
8600                                       GBytes              *contents,
8601                                       const char          *etag,
8602                                       gboolean             make_backup,
8603                                       GFileCreateFlags     flags,
8604                                       GCancellable        *cancellable,
8605                                       GAsyncReadyCallback  callback,
8606                                       gpointer             user_data)
8607 {
8608   ReplaceContentsData *data;
8609
8610   g_return_if_fail (G_IS_FILE (file));
8611   g_return_if_fail (contents != NULL);
8612
8613   data = g_new0 (ReplaceContentsData, 1);
8614
8615   data->content = g_bytes_ref (contents);
8616
8617   data->task = g_task_new (file, cancellable, callback, user_data);
8618   g_task_set_source_tag (data->task, g_file_replace_contents_bytes_async);
8619   g_task_set_task_data (data->task, data, (GDestroyNotify)replace_contents_data_free);
8620
8621   g_file_replace_async (file,
8622                         etag,
8623                         make_backup,
8624                         flags,
8625                         0,
8626                         g_task_get_cancellable (data->task),
8627                         replace_contents_open_callback,
8628                         data);
8629 }
8630
8631 /**
8632  * g_file_replace_contents_finish:
8633  * @file: input #GFile
8634  * @res: a #GAsyncResult
8635  * @new_etag: (out) (optional) (nullable): a location of a new [entity tag][gfile-etag]
8636  *   for the document. This should be freed with g_free() when it is no
8637  *   longer needed, or %NULL
8638  * @error: a #GError, or %NULL
8639  *
8640  * Finishes an asynchronous replace of the given @file. See
8641  * g_file_replace_contents_async(). Sets @new_etag to the new entity
8642  * tag for the document, if present.
8643  *
8644  * Returns: %TRUE on success, %FALSE on failure.
8645  */
8646 gboolean
8647 g_file_replace_contents_finish (GFile         *file,
8648                                 GAsyncResult  *res,
8649                                 char         **new_etag,
8650                                 GError       **error)
8651 {
8652   GTask *task;
8653   ReplaceContentsData *data;
8654
8655   g_return_val_if_fail (G_IS_FILE (file), FALSE);
8656   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
8657
8658   task = G_TASK (res);
8659
8660   if (!g_task_propagate_boolean (task, error))
8661     return FALSE;
8662
8663   data = g_task_get_task_data (task);
8664
8665   if (new_etag)
8666     {
8667       *new_etag = data->etag;
8668       data->etag = NULL; /* Take ownership */
8669     }
8670
8671   return TRUE;
8672 }
8673
8674 gboolean
8675 g_file_real_measure_disk_usage (GFile                         *file,
8676                                 GFileMeasureFlags              flags,
8677                                 GCancellable                  *cancellable,
8678                                 GFileMeasureProgressCallback   progress_callback,
8679                                 gpointer                       progress_data,
8680                                 guint64                       *disk_usage,
8681                                 guint64                       *num_dirs,
8682                                 guint64                       *num_files,
8683                                 GError                       **error)
8684 {
8685   g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
8686                        "Operation not supported for the current backend.");
8687   return FALSE;
8688 }
8689
8690 typedef struct
8691 {
8692   GFileMeasureFlags             flags;
8693   GFileMeasureProgressCallback  progress_callback;
8694   gpointer                      progress_data;
8695 } MeasureTaskData;
8696
8697 typedef struct
8698 {
8699   guint64 disk_usage;
8700   guint64 num_dirs;
8701   guint64 num_files;
8702 } MeasureResult;
8703
8704 typedef struct
8705 {
8706   GFileMeasureProgressCallback callback;
8707   gpointer                     user_data;
8708   gboolean                     reporting;
8709   guint64                      current_size;
8710   guint64                      num_dirs;
8711   guint64                      num_files;
8712 } MeasureProgress;
8713
8714 static gboolean
8715 measure_disk_usage_invoke_progress (gpointer user_data)
8716 {
8717   MeasureProgress *progress = user_data;
8718
8719   (* progress->callback) (progress->reporting,
8720                           progress->current_size, progress->num_dirs, progress->num_files,
8721                           progress->user_data);
8722
8723   return FALSE;
8724 }
8725
8726 static void
8727 measure_disk_usage_progress (gboolean reporting,
8728                              guint64  current_size,
8729                              guint64  num_dirs,
8730                              guint64  num_files,
8731                              gpointer user_data)
8732 {
8733   MeasureProgress progress;
8734   GTask *task = user_data;
8735   MeasureTaskData *data;
8736
8737   data = g_task_get_task_data (task);
8738
8739   progress.callback = data->progress_callback;
8740   progress.user_data = data->progress_data;
8741   progress.reporting = reporting;
8742   progress.current_size = current_size;
8743   progress.num_dirs = num_dirs;
8744   progress.num_files = num_files;
8745
8746   g_main_context_invoke_full (g_task_get_context (task),
8747                               g_task_get_priority (task),
8748                               measure_disk_usage_invoke_progress,
8749                               g_memdup2 (&progress, sizeof progress),
8750                               g_free);
8751 }
8752
8753 static void
8754 measure_disk_usage_thread (GTask        *task,
8755                            gpointer      source_object,
8756                            gpointer      task_data,
8757                            GCancellable *cancellable)
8758 {
8759   MeasureTaskData *data = task_data;
8760   GError *error = NULL;
8761   MeasureResult result = { 0, };
8762
8763   if (g_file_measure_disk_usage (source_object, data->flags, cancellable,
8764                                  data->progress_callback ? measure_disk_usage_progress : NULL, task,
8765                                  &result.disk_usage, &result.num_dirs, &result.num_files,
8766                                  &error))
8767     g_task_return_pointer (task, g_memdup2 (&result, sizeof result), g_free);
8768   else
8769     g_task_return_error (task, error);
8770 }
8771
8772 static void
8773 g_file_real_measure_disk_usage_async (GFile                        *file,
8774                                       GFileMeasureFlags             flags,
8775                                       gint                          io_priority,
8776                                       GCancellable                 *cancellable,
8777                                       GFileMeasureProgressCallback  progress_callback,
8778                                       gpointer                      progress_data,
8779                                       GAsyncReadyCallback           callback,
8780                                       gpointer                      user_data)
8781 {
8782   MeasureTaskData data;
8783   GTask *task;
8784
8785   data.flags = flags;
8786   data.progress_callback = progress_callback;
8787   data.progress_data = progress_data;
8788
8789   task = g_task_new (file, cancellable, callback, user_data);
8790   g_task_set_source_tag (task, g_file_real_measure_disk_usage_async);
8791   g_task_set_task_data (task, g_memdup2 (&data, sizeof data), g_free);
8792   g_task_set_priority (task, io_priority);
8793
8794   g_task_run_in_thread (task, measure_disk_usage_thread);
8795   g_object_unref (task);
8796 }
8797
8798 static gboolean
8799 g_file_real_measure_disk_usage_finish (GFile         *file,
8800                                        GAsyncResult  *result,
8801                                        guint64       *disk_usage,
8802                                        guint64       *num_dirs,
8803                                        guint64       *num_files,
8804                                        GError       **error)
8805 {
8806   MeasureResult *measure_result;
8807
8808   g_return_val_if_fail (g_task_is_valid (result, file), FALSE);
8809
8810   measure_result = g_task_propagate_pointer (G_TASK (result), error);
8811
8812   if (measure_result == NULL)
8813     return FALSE;
8814
8815   if (disk_usage)
8816     *disk_usage = measure_result->disk_usage;
8817
8818   if (num_dirs)
8819     *num_dirs = measure_result->num_dirs;
8820
8821   if (num_files)
8822     *num_files = measure_result->num_files;
8823
8824   g_free (measure_result);
8825
8826   return TRUE;
8827 }
8828
8829 /**
8830  * g_file_measure_disk_usage:
8831  * @file: a #GFile
8832  * @flags: #GFileMeasureFlags
8833  * @cancellable: (nullable): optional #GCancellable
8834  * @progress_callback: (nullable): a #GFileMeasureProgressCallback
8835  * @progress_data: user_data for @progress_callback
8836  * @disk_usage: (out) (optional): the number of bytes of disk space used
8837  * @num_dirs: (out) (optional): the number of directories encountered
8838  * @num_files: (out) (optional): the number of non-directories encountered
8839  * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer
8840  *
8841  * Recursively measures the disk usage of @file.
8842  *
8843  * This is essentially an analog of the 'du' command, but it also
8844  * reports the number of directories and non-directory files encountered
8845  * (including things like symbolic links).
8846  *
8847  * By default, errors are only reported against the toplevel file
8848  * itself.  Errors found while recursing are silently ignored, unless
8849  * %G_FILE_MEASURE_REPORT_ANY_ERROR is given in @flags.
8850  *
8851  * The returned size, @disk_usage, is in bytes and should be formatted
8852  * with g_format_size() in order to get something reasonable for showing
8853  * in a user interface.
8854  *
8855  * @progress_callback and @progress_data can be given to request
8856  * periodic progress updates while scanning.  See the documentation for
8857  * #GFileMeasureProgressCallback for information about when and how the
8858  * callback will be invoked.
8859  *
8860  * Returns: %TRUE if successful, with the out parameters set.
8861  *   %FALSE otherwise, with @error set.
8862  *
8863  * Since: 2.38
8864  **/
8865 gboolean
8866 g_file_measure_disk_usage (GFile                         *file,
8867                            GFileMeasureFlags              flags,
8868                            GCancellable                  *cancellable,
8869                            GFileMeasureProgressCallback   progress_callback,
8870                            gpointer                       progress_data,
8871                            guint64                       *disk_usage,
8872                            guint64                       *num_dirs,
8873                            guint64                       *num_files,
8874                            GError                       **error)
8875 {
8876   g_return_val_if_fail (G_IS_FILE (file), FALSE);
8877   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
8878   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
8879
8880   return G_FILE_GET_IFACE (file)->measure_disk_usage (file, flags, cancellable,
8881                                                       progress_callback, progress_data,
8882                                                       disk_usage, num_dirs, num_files,
8883                                                       error);
8884 }
8885
8886 /**
8887  * g_file_measure_disk_usage_async:
8888  * @file: a #GFile
8889  * @flags: #GFileMeasureFlags
8890  * @io_priority: the [I/O priority][io-priority] of the request
8891  * @cancellable: (nullable): optional #GCancellable
8892  * @progress_callback: (nullable): a #GFileMeasureProgressCallback
8893  * @progress_data: user_data for @progress_callback
8894  * @callback: (nullable): a #GAsyncReadyCallback to call when complete
8895  * @user_data: the data to pass to callback function
8896  *
8897  * Recursively measures the disk usage of @file.
8898  *
8899  * This is the asynchronous version of g_file_measure_disk_usage().  See
8900  * there for more information.
8901  *
8902  * Since: 2.38
8903  **/
8904 void
8905 g_file_measure_disk_usage_async (GFile                        *file,
8906                                  GFileMeasureFlags             flags,
8907                                  gint                          io_priority,
8908                                  GCancellable                 *cancellable,
8909                                  GFileMeasureProgressCallback  progress_callback,
8910                                  gpointer                      progress_data,
8911                                  GAsyncReadyCallback           callback,
8912                                  gpointer                      user_data)
8913 {
8914   g_return_if_fail (G_IS_FILE (file));
8915   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
8916
8917   G_FILE_GET_IFACE (file)->measure_disk_usage_async (file, flags, io_priority, cancellable,
8918                                                      progress_callback, progress_data,
8919                                                      callback, user_data);
8920 }
8921
8922 /**
8923  * g_file_measure_disk_usage_finish:
8924  * @file: a #GFile
8925  * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
8926  * @disk_usage: (out) (optional): the number of bytes of disk space used
8927  * @num_dirs: (out) (optional): the number of directories encountered
8928  * @num_files: (out) (optional): the number of non-directories encountered
8929  * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer
8930  *
8931  * Collects the results from an earlier call to
8932  * g_file_measure_disk_usage_async().  See g_file_measure_disk_usage() for
8933  * more information.
8934  *
8935  * Returns: %TRUE if successful, with the out parameters set.
8936  *   %FALSE otherwise, with @error set.
8937  *
8938  * Since: 2.38
8939  **/
8940 gboolean
8941 g_file_measure_disk_usage_finish (GFile         *file,
8942                                   GAsyncResult  *result,
8943                                   guint64       *disk_usage,
8944                                   guint64       *num_dirs,
8945                                   guint64       *num_files,
8946                                   GError       **error)
8947 {
8948   g_return_val_if_fail (G_IS_FILE (file), FALSE);
8949   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
8950
8951   return G_FILE_GET_IFACE (file)->measure_disk_usage_finish (file, result, disk_usage, num_dirs, num_files, error);
8952 }
8953
8954 /**
8955  * g_file_start_mountable:
8956  * @file: input #GFile
8957  * @flags: flags affecting the operation
8958  * @start_operation: (nullable): a #GMountOperation, or %NULL to avoid user interaction
8959  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
8960  * @callback: (nullable): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
8961  * @user_data: the data to pass to callback function
8962  *
8963  * Starts a file of type %G_FILE_TYPE_MOUNTABLE.
8964  * Using @start_operation, you can request callbacks when, for instance,
8965  * passwords are needed during authentication.
8966  *
8967  * If @cancellable is not %NULL, then the operation can be cancelled by
8968  * triggering the cancellable object from another thread. If the operation
8969  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
8970  *
8971  * When the operation is finished, @callback will be called.
8972  * You can then call g_file_mount_mountable_finish() to get
8973  * the result of the operation.
8974  *
8975  * Since: 2.22
8976  */
8977 void
8978 g_file_start_mountable (GFile               *file,
8979                         GDriveStartFlags     flags,
8980                         GMountOperation     *start_operation,
8981                         GCancellable        *cancellable,
8982                         GAsyncReadyCallback  callback,
8983                         gpointer             user_data)
8984 {
8985   GFileIface *iface;
8986
8987   g_return_if_fail (G_IS_FILE (file));
8988
8989   iface = G_FILE_GET_IFACE (file);
8990
8991   if (iface->start_mountable == NULL)
8992     {
8993       g_task_report_new_error (file, callback, user_data,
8994                                g_file_start_mountable,
8995                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
8996                                _("Operation not supported"));
8997       return;
8998     }
8999
9000   (* iface->start_mountable) (file,
9001                               flags,
9002                               start_operation,
9003                               cancellable,
9004                               callback,
9005                               user_data);
9006 }
9007
9008 /**
9009  * g_file_start_mountable_finish:
9010  * @file: input #GFile
9011  * @result: a #GAsyncResult
9012  * @error: a #GError, or %NULL
9013  *
9014  * Finishes a start operation. See g_file_start_mountable() for details.
9015  *
9016  * Finish an asynchronous start operation that was started
9017  * with g_file_start_mountable().
9018  *
9019  * Returns: %TRUE if the operation finished successfully. %FALSE
9020  * otherwise.
9021  *
9022  * Since: 2.22
9023  */
9024 gboolean
9025 g_file_start_mountable_finish (GFile         *file,
9026                                GAsyncResult  *result,
9027                                GError       **error)
9028 {
9029   GFileIface *iface;
9030
9031   g_return_val_if_fail (G_IS_FILE (file), FALSE);
9032   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
9033
9034   if (g_async_result_legacy_propagate_error (result, error))
9035     return FALSE;
9036   else if (g_async_result_is_tagged (result, g_file_start_mountable))
9037     return g_task_propagate_boolean (G_TASK (result), error);
9038
9039   iface = G_FILE_GET_IFACE (file);
9040   return (* iface->start_mountable_finish) (file, result, error);
9041 }
9042
9043 /**
9044  * g_file_stop_mountable:
9045  * @file: input #GFile
9046  * @flags: flags affecting the operation
9047  * @mount_operation: (nullable): a #GMountOperation,
9048  *   or %NULL to avoid user interaction.
9049  * @cancellable: (nullable): optional #GCancellable object,
9050  *   %NULL to ignore
9051  * @callback: (nullable): a #GAsyncReadyCallback to call
9052  *   when the request is satisfied, or %NULL
9053  * @user_data: the data to pass to callback function
9054  *
9055  * Stops a file of type %G_FILE_TYPE_MOUNTABLE.
9056  *
9057  * If @cancellable is not %NULL, then the operation can be cancelled by
9058  * triggering the cancellable object from another thread. If the operation
9059  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
9060  *
9061  * When the operation is finished, @callback will be called.
9062  * You can then call g_file_stop_mountable_finish() to get
9063  * the result of the operation.
9064  *
9065  * Since: 2.22
9066  */
9067 void
9068 g_file_stop_mountable (GFile               *file,
9069                        GMountUnmountFlags   flags,
9070                        GMountOperation     *mount_operation,
9071                        GCancellable        *cancellable,
9072                        GAsyncReadyCallback  callback,
9073                        gpointer             user_data)
9074 {
9075   GFileIface *iface;
9076
9077   g_return_if_fail (G_IS_FILE (file));
9078
9079   iface = G_FILE_GET_IFACE (file);
9080
9081   if (iface->stop_mountable == NULL)
9082     {
9083       g_task_report_new_error (file, callback, user_data,
9084                                g_file_stop_mountable,
9085                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
9086                                _("Operation not supported"));
9087       return;
9088     }
9089
9090   (* iface->stop_mountable) (file,
9091                              flags,
9092                              mount_operation,
9093                              cancellable,
9094                              callback,
9095                              user_data);
9096 }
9097
9098 /**
9099  * g_file_stop_mountable_finish:
9100  * @file: input #GFile
9101  * @result: a #GAsyncResult
9102  * @error: a #GError, or %NULL
9103  *
9104  * Finishes a stop operation, see g_file_stop_mountable() for details.
9105  *
9106  * Finish an asynchronous stop operation that was started
9107  * with g_file_stop_mountable().
9108  *
9109  * Returns: %TRUE if the operation finished successfully.
9110  *   %FALSE otherwise.
9111  *
9112  * Since: 2.22
9113  */
9114 gboolean
9115 g_file_stop_mountable_finish (GFile         *file,
9116                               GAsyncResult  *result,
9117                               GError       **error)
9118 {
9119   GFileIface *iface;
9120
9121   g_return_val_if_fail (G_IS_FILE (file), FALSE);
9122   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
9123
9124   if (g_async_result_legacy_propagate_error (result, error))
9125     return FALSE;
9126   else if (g_async_result_is_tagged (result, g_file_stop_mountable))
9127     return g_task_propagate_boolean (G_TASK (result), error);
9128
9129   iface = G_FILE_GET_IFACE (file);
9130   return (* iface->stop_mountable_finish) (file, result, error);
9131 }
9132
9133 /**
9134  * g_file_poll_mountable:
9135  * @file: input #GFile
9136  * @cancellable: optional #GCancellable object, %NULL to ignore
9137  * @callback: (nullable): a #GAsyncReadyCallback to call
9138  *   when the request is satisfied, or %NULL
9139  * @user_data: the data to pass to callback function
9140  *
9141  * Polls a file of type %G_FILE_TYPE_MOUNTABLE.
9142  *
9143  * If @cancellable is not %NULL, then the operation can be cancelled by
9144  * triggering the cancellable object from another thread. If the operation
9145  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
9146  *
9147  * When the operation is finished, @callback will be called.
9148  * You can then call g_file_mount_mountable_finish() to get
9149  * the result of the operation.
9150  *
9151  * Since: 2.22
9152  */
9153 void
9154 g_file_poll_mountable (GFile               *file,
9155                        GCancellable        *cancellable,
9156                        GAsyncReadyCallback  callback,
9157                        gpointer             user_data)
9158 {
9159   GFileIface *iface;
9160
9161   g_return_if_fail (G_IS_FILE (file));
9162
9163   iface = G_FILE_GET_IFACE (file);
9164
9165   if (iface->poll_mountable == NULL)
9166     {
9167       g_task_report_new_error (file, callback, user_data,
9168                                g_file_poll_mountable,
9169                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
9170                                _("Operation not supported"));
9171       return;
9172     }
9173
9174   (* iface->poll_mountable) (file,
9175                              cancellable,
9176                              callback,
9177                              user_data);
9178 }
9179
9180 /**
9181  * g_file_poll_mountable_finish:
9182  * @file: input #GFile
9183  * @result: a #GAsyncResult
9184  * @error: a #GError, or %NULL
9185  *
9186  * Finishes a poll operation. See g_file_poll_mountable() for details.
9187  *
9188  * Finish an asynchronous poll operation that was polled
9189  * with g_file_poll_mountable().
9190  *
9191  * Returns: %TRUE if the operation finished successfully. %FALSE
9192  * otherwise.
9193  *
9194  * Since: 2.22
9195  */
9196 gboolean
9197 g_file_poll_mountable_finish (GFile         *file,
9198                               GAsyncResult  *result,
9199                               GError       **error)
9200 {
9201   GFileIface *iface;
9202
9203   g_return_val_if_fail (G_IS_FILE (file), FALSE);
9204   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
9205
9206   if (g_async_result_legacy_propagate_error (result, error))
9207     return FALSE;
9208   else if (g_async_result_is_tagged (result, g_file_poll_mountable))
9209     return g_task_propagate_boolean (G_TASK (result), error);
9210
9211   iface = G_FILE_GET_IFACE (file);
9212   return (* iface->poll_mountable_finish) (file, result, error);
9213 }
9214
9215 /**
9216  * g_file_supports_thread_contexts:
9217  * @file: a #GFile
9218  *
9219  * Checks if @file supports
9220  * [thread-default contexts][g-main-context-push-thread-default-context].
9221  * If this returns %FALSE, you cannot perform asynchronous operations on
9222  * @file in a thread that has a thread-default context.
9223  *
9224  * Returns: Whether or not @file supports thread-default contexts.
9225  *
9226  * Since: 2.22
9227  */
9228 gboolean
9229 g_file_supports_thread_contexts (GFile *file)
9230 {
9231  GFileIface *iface;
9232
9233  g_return_val_if_fail (G_IS_FILE (file), FALSE);
9234
9235  iface = G_FILE_GET_IFACE (file);
9236  return iface->supports_thread_contexts;
9237 }
9238
9239 /**
9240  * g_file_load_bytes:
9241  * @file: a #GFile
9242  * @cancellable: (nullable): a #GCancellable or %NULL
9243  * @etag_out: (out) (nullable) (optional): a location to place the current
9244  *   entity tag for the file, or %NULL if the entity tag is not needed
9245  * @error: a location for a #GError or %NULL
9246  *
9247  * Loads the contents of @file and returns it as #GBytes.
9248  *
9249  * If @file is a resource:// based URI, the resulting bytes will reference the
9250  * embedded resource instead of a copy. Otherwise, this is equivalent to calling
9251  * g_file_load_contents() and g_bytes_new_take().
9252  *
9253  * For resources, @etag_out will be set to %NULL.
9254  *
9255  * The data contained in the resulting #GBytes is always zero-terminated, but
9256  * this is not included in the #GBytes length. The resulting #GBytes should be
9257  * freed with g_bytes_unref() when no longer in use.
9258  *
9259  * Returns: (transfer full): a #GBytes or %NULL and @error is set
9260  *
9261  * Since: 2.56
9262  */
9263 GBytes *
9264 g_file_load_bytes (GFile         *file,
9265                    GCancellable  *cancellable,
9266                    gchar        **etag_out,
9267                    GError       **error)
9268 {
9269   gchar *contents;
9270   gsize len;
9271
9272   g_return_val_if_fail (G_IS_FILE (file), NULL);
9273   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
9274   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
9275
9276   if (etag_out != NULL)
9277     *etag_out = NULL;
9278
9279   if (g_file_has_uri_scheme (file, "resource"))
9280     {
9281       GBytes *bytes;
9282       gchar *uri, *unescaped;
9283
9284       uri = g_file_get_uri (file);
9285       unescaped = g_uri_unescape_string (uri + strlen ("resource://"), NULL);
9286       g_free (uri);
9287
9288       bytes = g_resources_lookup_data (unescaped, G_RESOURCE_LOOKUP_FLAGS_NONE, error);
9289       g_free (unescaped);
9290
9291       return bytes;
9292     }
9293
9294   /* contents is guaranteed to be \0 terminated */
9295   if (g_file_load_contents (file, cancellable, &contents, &len, etag_out, error))
9296     return g_bytes_new_take (g_steal_pointer (&contents), len);
9297
9298   return NULL;
9299 }
9300
9301 static void
9302 g_file_load_bytes_cb (GObject      *object,
9303                       GAsyncResult *result,
9304                       gpointer      user_data)
9305 {
9306   GFile *file = G_FILE (object);
9307   GTask *task = user_data;
9308   GError *error = NULL;
9309   gchar *etag = NULL;
9310   gchar *contents = NULL;
9311   gsize len = 0;
9312
9313   g_file_load_contents_finish (file, result, &contents, &len, &etag, &error);
9314   g_task_set_task_data (task, g_steal_pointer (&etag), g_free);
9315
9316   if (error != NULL)
9317     g_task_return_error (task, g_steal_pointer (&error));
9318   else
9319     g_task_return_pointer (task,
9320                            g_bytes_new_take (g_steal_pointer (&contents), len),
9321                            (GDestroyNotify)g_bytes_unref);
9322
9323   g_object_unref (task);
9324 }
9325
9326 /**
9327  * g_file_load_bytes_async:
9328  * @file: a #GFile
9329  * @cancellable: (nullable): a #GCancellable or %NULL
9330  * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback
9331  *   to call when the request is satisfied
9332  * @user_data: the data to pass to callback function
9333  *
9334  * Asynchronously loads the contents of @file as #GBytes.
9335  *
9336  * If @file is a resource:// based URI, the resulting bytes will reference the
9337  * embedded resource instead of a copy. Otherwise, this is equivalent to calling
9338  * g_file_load_contents_async() and g_bytes_new_take().
9339  *
9340  * @callback should call g_file_load_bytes_finish() to get the result of this
9341  * asynchronous operation.
9342  *
9343  * See g_file_load_bytes() for more information.
9344  *
9345  * Since: 2.56
9346  */
9347 void
9348 g_file_load_bytes_async (GFile               *file,
9349                          GCancellable        *cancellable,
9350                          GAsyncReadyCallback  callback,
9351                          gpointer             user_data)
9352 {
9353   GError *error = NULL;
9354   GBytes *bytes;
9355   GTask *task;
9356
9357   g_return_if_fail (G_IS_FILE (file));
9358   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
9359
9360   task = g_task_new (file, cancellable, callback, user_data);
9361   g_task_set_source_tag (task, g_file_load_bytes_async);
9362
9363   if (!g_file_has_uri_scheme (file, "resource"))
9364     {
9365       g_file_load_contents_async (file,
9366                                   cancellable,
9367                                   g_file_load_bytes_cb,
9368                                   g_steal_pointer (&task));
9369       return;
9370     }
9371
9372   bytes = g_file_load_bytes (file, cancellable, NULL, &error);
9373
9374   if (bytes == NULL)
9375     g_task_return_error (task, g_steal_pointer (&error));
9376   else
9377     g_task_return_pointer (task,
9378                            g_steal_pointer (&bytes),
9379                            (GDestroyNotify)g_bytes_unref);
9380
9381   g_object_unref (task);
9382 }
9383
9384 /**
9385  * g_file_load_bytes_finish:
9386  * @file: a #GFile
9387  * @result: a #GAsyncResult provided to the callback
9388  * @etag_out: (out) (nullable) (optional): a location to place the current
9389  *   entity tag for the file, or %NULL if the entity tag is not needed
9390  * @error: a location for a #GError, or %NULL
9391  *
9392  * Completes an asynchronous request to g_file_load_bytes_async().
9393  *
9394  * For resources, @etag_out will be set to %NULL.
9395  *
9396  * The data contained in the resulting #GBytes is always zero-terminated, but
9397  * this is not included in the #GBytes length. The resulting #GBytes should be
9398  * freed with g_bytes_unref() when no longer in use.
9399  *
9400  * See g_file_load_bytes() for more information.
9401  *
9402  * Returns: (transfer full): a #GBytes or %NULL and @error is set
9403  *
9404  * Since: 2.56
9405  */
9406 GBytes *
9407 g_file_load_bytes_finish (GFile         *file,
9408                           GAsyncResult  *result,
9409                           gchar        **etag_out,
9410                           GError       **error)
9411 {
9412   GBytes *bytes;
9413
9414   g_return_val_if_fail (G_IS_FILE (file), NULL);
9415   g_return_val_if_fail (G_IS_TASK (result), NULL);
9416   g_return_val_if_fail (g_task_is_valid (G_TASK (result), file), NULL);
9417   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
9418
9419   bytes = g_task_propagate_pointer (G_TASK (result), error);
9420
9421   if (etag_out != NULL)
9422     *etag_out = g_strdup (g_task_get_task_data (G_TASK (result)));
9423
9424   return bytes;
9425 }