/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */

/* GIO - GLib Input, Output and Streaming Library

 * 

 * Copyright (C) 2006-2007 Red Hat, Inc.

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Lesser General Public

 * License as published by the Free Software Foundation; either

 * version 2.1 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General

 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.

 *

 * Author: Alexander Larsson <alexl@redhat.com>

 */

#include "config.h"

#ifdef __linux__

#include <sys/ioctl.h>

#include <errno.h>

/* See linux.git/fs/btrfs/ioctl.h */

#define BTRFS_IOCTL_MAGIC 0x94

#define BTRFS_IOC_CLONE _IOW(BTRFS_IOCTL_MAGIC, 9, int)

#endif

#ifdef HAVE_SPLICE

#include <sys/stat.h>

#include <unistd.h>

#include <fcntl.h>

#include <errno.h>

/*

 * We duplicate the following Linux kernel header defines here so we can still

 * run at full speed on modern kernels in cases where an old toolchain was used

 * to build GLib. This is often done deliberately to allow shipping binaries

 * that need to run on a wide range of systems.

 */

#ifndef F_SETPIPE_SZ

#define F_SETPIPE_SZ 1031

#endif

#ifndef F_GETPIPE_SZ

#define F_GETPIPE_SZ 1032

#endif

#endif

#include <string.h>

#include <sys/types.h>

#include "gfile.h"

#include "glib/gstdio.h"

#ifdef G_OS_UNIX

#include "glib-unix.h"

#endif

#include "gvfs.h"

#include "gtask.h"

#include "gfileattribute-priv.h"

#include "gfiledescriptorbased.h"

#include "gpollfilemonitor.h"

#include "gappinfo.h"

#include "gfileinputstream.h"

#include "gfileoutputstream.h"

#include "glocalfileoutputstream.h"

#include "glocalfileiostream.h"

#include "glocalfile.h"

#include "gcancellable.h"

#include "gasyncresult.h"

#include "gioerror.h"

#include "glibintl.h"

/**

 * SECTION:gfile

 * @short_description: File and Directory Handling

 * @include: gio/gio.h

 * @see_also: #GFileInfo, #GFileEnumerator

 *

 * #GFile is a high level abstraction for manipulating files on a

 * virtual file system. #GFiles are lightweight, immutable objects

 * that do no I/O upon creation. It is necessary to understand that

 * #GFile objects do not represent files, merely an identifier for a

 * file. All file content I/O is implemented as streaming operations

 * (see #GInputStream and #GOutputStream).

 *

 * To construct a #GFile, you can use:

 * - g_file_new_for_path() if you have a path.

 * - g_file_new_for_uri() if you have a URI.

 * - g_file_new_for_commandline_arg() for a command line argument.

 * - g_file_new_tmp() to create a temporary file from a template.

 * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().

 * - g_file_new_build_filename() to create a file from path elements.

 *

 * One way to think of a #GFile is as an abstraction of a pathname. For

 * normal files the system pathname is what is stored internally, but as

 * #GFiles are extensible it could also be something else that corresponds

 * to a pathname in a userspace implementation of a filesystem.

 *

 * #GFiles make up hierarchies of directories and files that correspond to

 * the files on a filesystem. You can move through the file system with

 * #GFile using g_file_get_parent() to get an identifier for the parent

 * directory, g_file_get_child() to get a child within a directory,

 * g_file_resolve_relative_path() to resolve a relative path between two

 * #GFiles. There can be multiple hierarchies, so you may not end up at

 * the same root if you repeatedly call g_file_get_parent() on two different

 * files.

 *

 * All #GFiles have a basename (get with g_file_get_basename()). These names

 * are byte strings that are used to identify the file on the filesystem

 * (relative to its parent directory) and there is no guarantees that they

 * have any particular charset encoding or even make any sense at all. If

 * you want to use filenames in a user interface you should use the display

 * name that you can get by requesting the

 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().

 * This is guaranteed to be in UTF-8 and can be used in a user interface.

 * But always store the real basename or the #GFile to use to actually

 * access the file, because there is no way to go from a display name to

 * the actual name.

 *

 * Using #GFile as an identifier has the same weaknesses as using a path

 * in that there may be multiple aliases for the same file. For instance,

 * hard or soft links may cause two different #GFiles to refer to the same

 * file. Other possible causes for aliases are: case insensitive filesystems,

 * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to

 * check if two #GFiles point to the same file you can query for the

 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial

 * canonicalization of pathnames passed in, so that trivial differences in

 * the path string used at creation (duplicated slashes, slash at end of

 * path, "." or ".." path segments, etc) does not create different #GFiles.

 *

 * Many #GFile operations have both synchronous and asynchronous versions

 * to suit your application. Asynchronous versions of synchronous functions

 * simply have _async() appended to their function names. The asynchronous

 * I/O functions call a #GAsyncReadyCallback which is then used to finalize

 * the operation, producing a GAsyncResult which is then passed to the

 * function's matching _finish() operation.

 *

 * It is highly recommended to use asynchronous calls when running within a

 * shared main loop, such as in the main thread of an application. This avoids

 * I/O operations blocking other sources on the main loop from being dispatched.

 * Synchronous I/O operations should be performed from worker threads. See the

 * [introduction to asynchronous programming section][async-programming] for

 * more.

 *

 * Some #GFile operations almost always take a noticeable amount of time, and

 * so do not have synchronous analogs. Notable cases include:

 * - g_file_mount_mountable() to mount a mountable file.

 * - g_file_unmount_mountable_with_operation() to unmount a mountable file.

 * - g_file_eject_mountable_with_operation() to eject a mountable file.

 *

 * ## Entity Tags # {#gfile-etag}

 *

 * One notable feature of #GFiles are entity tags, or "etags" for

 * short. Entity tags are somewhat like a more abstract version of the

 * traditional mtime, and can be used to quickly determine if the file

 * has been modified from the version on the file system. See the

 * HTTP 1.1 

 * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)

 * for HTTP Etag headers, which are a very similar concept.

 */

static void               g_file_real_query_info_async            (GFile                  *file,

                                                                   const char             *attributes,

                                                                   GFileQueryInfoFlags     flags,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GFileInfo *        g_file_real_query_info_finish           (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_query_filesystem_info_async (GFile                  *file,

                                                                   const char             *attributes,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GFileInfo *        g_file_real_query_filesystem_info_finish (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_enumerate_children_async    (GFile                  *file,

                                                                   const char             *attributes,

                                                                   GFileQueryInfoFlags     flags,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GFileEnumerator *  g_file_real_enumerate_children_finish   (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_read_async                  (GFile                  *file,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GFileInputStream * g_file_real_read_finish                 (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_append_to_async             (GFile                  *file,

                                                                   GFileCreateFlags        flags,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GFileOutputStream *g_file_real_append_to_finish            (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_create_async                (GFile                  *file,

                                                                   GFileCreateFlags        flags,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GFileOutputStream *g_file_real_create_finish               (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_replace_async               (GFile                  *file,

                                                                   const char             *etag,

                                                                   gboolean                make_backup,

                                                                   GFileCreateFlags        flags,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GFileOutputStream *g_file_real_replace_finish              (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_delete_async                (GFile                  *file,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static gboolean           g_file_real_delete_finish               (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_trash_async                 (GFile                  *file,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static gboolean           g_file_real_trash_finish                (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_make_directory_async        (GFile                  *file,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static gboolean           g_file_real_make_directory_finish       (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_open_readwrite_async        (GFile                  *file,

                                                                   int                  io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GFileIOStream *    g_file_real_open_readwrite_finish       (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_create_readwrite_async      (GFile                  *file,

                                                                   GFileCreateFlags        flags,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GFileIOStream *    g_file_real_create_readwrite_finish     (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_replace_readwrite_async     (GFile                  *file,

                                                                   const char             *etag,

                                                                   gboolean                make_backup,

                                                                   GFileCreateFlags        flags,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GFileIOStream *    g_file_real_replace_readwrite_finish    (GFile                  *file,

                                                                  GAsyncResult            *res,

                                                                  GError                 **error);

static gboolean           g_file_real_set_attributes_from_info    (GFile                  *file,

                                                                   GFileInfo              *info,

                                                                   GFileQueryInfoFlags     flags,

                                                                   GCancellable           *cancellable,

                                                                   GError                **error);

static void               g_file_real_set_display_name_async      (GFile                  *file,

                                                                   const char             *display_name,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GFile *            g_file_real_set_display_name_finish     (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_set_attributes_async        (GFile                  *file,

                                                                   GFileInfo              *info,

                                                                   GFileQueryInfoFlags     flags,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static gboolean           g_file_real_set_attributes_finish       (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GFileInfo             **info,

                                                                   GError                **error);

static void               g_file_real_find_enclosing_mount_async  (GFile                  *file,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static GMount *           g_file_real_find_enclosing_mount_finish (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static void               g_file_real_copy_async                  (GFile                  *source,

                                                                   GFile                  *destination,

                                                                   GFileCopyFlags          flags,

                                                                   int                     io_priority,

                                                                   GCancellable           *cancellable,

                                                                   GFileProgressCallback   progress_callback,

                                                                   gpointer                progress_callback_data,

                                                                   GAsyncReadyCallback     callback,

                                                                   gpointer                user_data);

static gboolean           g_file_real_copy_finish                 (GFile                  *file,

                                                                   GAsyncResult           *res,

                                                                   GError                **error);

static gboolean           g_file_real_measure_disk_usage          (GFile                         *file,

                                                                   GFileMeasureFlags              flags,

                                                                   GCancellable                  *cancellable,

                                                                   GFileMeasureProgressCallback   progress_callback,

                                                                   gpointer                       progress_data,

                                                                   guint64                       *disk_usage,

                                                                   guint64                       *num_dirs,

                                                                   guint64                       *num_files,

                                                                   GError                       **error);

static void               g_file_real_measure_disk_usage_async    (GFile                         *file,

                                                                   GFileMeasureFlags              flags,

                                                                   gint                           io_priority,

                                                                   GCancellable                  *cancellable,

                                                                   GFileMeasureProgressCallback   progress_callback,

                                                                   gpointer                       progress_data,

                                                                   GAsyncReadyCallback            callback,

                                                                   gpointer                       user_data);

static gboolean           g_file_real_measure_disk_usage_finish   (GFile                         *file,

                                                                   GAsyncResult                  *result,

                                                                   guint64                       *disk_usage,

                                                                   guint64                       *num_dirs,

                                                                   guint64                       *num_files,

                                                                   GError                       **error);

typedef GFileIface GFileInterface;

G_DEFINE_INTERFACE (GFile, g_file, G_TYPE_OBJECT)

static void

g_file_default_init (GFileIface *iface)

{

  iface->enumerate_children_async = g_file_real_enumerate_children_async;

  iface->enumerate_children_finish = g_file_real_enumerate_children_finish;

  iface->set_display_name_async = g_file_real_set_display_name_async;

  iface->set_display_name_finish = g_file_real_set_display_name_finish;

  iface->query_info_async = g_file_real_query_info_async;

  iface->query_info_finish = g_file_real_query_info_finish;

  iface->query_filesystem_info_async = g_file_real_query_filesystem_info_async;

  iface->query_filesystem_info_finish = g_file_real_query_filesystem_info_finish;

  iface->set_attributes_async = g_file_real_set_attributes_async;

  iface->set_attributes_finish = g_file_real_set_attributes_finish;

  iface->read_async = g_file_real_read_async;

  iface->read_finish = g_file_real_read_finish;

  iface->append_to_async = g_file_real_append_to_async;

  iface->append_to_finish = g_file_real_append_to_finish;

  iface->create_async = g_file_real_create_async;

  iface->create_finish = g_file_real_create_finish;

  iface->replace_async = g_file_real_replace_async;

  iface->replace_finish = g_file_real_replace_finish;

  iface->delete_file_async = g_file_real_delete_async;

  iface->delete_file_finish = g_file_real_delete_finish;

  iface->trash_async = g_file_real_trash_async;

  iface->trash_finish = g_file_real_trash_finish;

  iface->make_directory_async = g_file_real_make_directory_async;

  iface->make_directory_finish = g_file_real_make_directory_finish;

  iface->open_readwrite_async = g_file_real_open_readwrite_async;

  iface->open_readwrite_finish = g_file_real_open_readwrite_finish;

  iface->create_readwrite_async = g_file_real_create_readwrite_async;

  iface->create_readwrite_finish = g_file_real_create_readwrite_finish;

  iface->replace_readwrite_async = g_file_real_replace_readwrite_async;

  iface->replace_readwrite_finish = g_file_real_replace_readwrite_finish;

  iface->find_enclosing_mount_async = g_file_real_find_enclosing_mount_async;

  iface->find_enclosing_mount_finish = g_file_real_find_enclosing_mount_finish;

  iface->set_attributes_from_info = g_file_real_set_attributes_from_info;

  iface->copy_async = g_file_real_copy_async;

  iface->copy_finish = g_file_real_copy_finish;

  iface->measure_disk_usage = g_file_real_measure_disk_usage;

  iface->measure_disk_usage_async = g_file_real_measure_disk_usage_async;

  iface->measure_disk_usage_finish = g_file_real_measure_disk_usage_finish;

}

/**

 * g_file_is_native:

 * @file: input #GFile

 *

 * Checks to see if a file is native to the platform.

 *

 * A native file is one expressed in the platform-native filename format,

 * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,

 * as it might be on a locally mounted remote filesystem.

 *

 * On some systems non-native files may be available using the native

 * filesystem via a userspace filesystem (FUSE), in these cases this call

 * will return %FALSE, but g_file_get_path() will still return a native path.

 *

 * This call does no blocking I/O.

 *

 * Returns: %TRUE if @file is native

 */

gboolean

g_file_is_native (GFile *file)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), FALSE);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->is_native) (file);

}

/**

 * g_file_has_uri_scheme:

 * @file: input #GFile

 * @uri_scheme: a string containing a URI scheme

 *

 * Checks to see if a #GFile has a given URI scheme.

 *

 * This call does no blocking I/O.

 *

 * Returns: %TRUE if #GFile's backend supports the

 *     given URI scheme, %FALSE if URI scheme is %NULL,

 *     not supported, or #GFile is invalid.

 */

gboolean

g_file_has_uri_scheme (GFile      *file,

                       const char *uri_scheme)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), FALSE);

  g_return_val_if_fail (uri_scheme != NULL, FALSE);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->has_uri_scheme) (file, uri_scheme);

}

/**

 * g_file_get_uri_scheme:

 * @file: input #GFile

 *

 * Gets the URI scheme for a #GFile.

 * RFC 3986 decodes the scheme as:

 * |[

 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

 * ]|

 * Common schemes include "file", "http", "ftp", etc.

 *

 * The scheme can be different from the one used to construct the #GFile,

 * in that it might be replaced with one that is logically equivalent to the #GFile.

 *

 * This call does no blocking I/O.

 *

 * Returns: (nullable): a string containing the URI scheme for the given

 *     #GFile or %NULL if the #GFile was constructed with an invalid URI. The

 *     returned string should be freed with g_free() when no longer needed.

 */

char *

g_file_get_uri_scheme (GFile *file)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_uri_scheme) (file);

}

/**

 * g_file_get_basename: (virtual get_basename)

 * @file: input #GFile

 *

 * Gets the base name (the last component of the path) for a given #GFile.

 *

 * If called for the top level of a system (such as the filesystem root

 * or a uri like sftp://host/) it will return a single directory separator

 * (and on Windows, possibly a drive letter).

 *

 * The base name is a byte string (not UTF-8). It has no defined encoding

 * or rules other than it may not contain zero bytes.  If you want to use

 * filenames in a user interface you should use the display name that you

 * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME

 * attribute with g_file_query_info().

 *

 * This call does no blocking I/O.

 *

 * Returns: (type filename) (nullable): string containing the #GFile's

 *     base name, or %NULL if given #GFile is invalid. The returned string

 *     should be freed with g_free() when no longer needed.

 */

char *

g_file_get_basename (GFile *file)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_basename) (file);

}

/**

 * g_file_get_path: (virtual get_path)

 * @file: input #GFile

 *

 * Gets the local pathname for #GFile, if one exists. If non-%NULL, this is

 * guaranteed to be an absolute, canonical path. It might contain symlinks.

 *

 * This call does no blocking I/O.

 *

 * Returns: (type filename) (nullable): string containing the #GFile's path,

 *     or %NULL if no such path exists. The returned string should be freed

 *     with g_free() when no longer needed.

 */

char *

g_file_get_path (GFile *file)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_path) (file);

}

static const char *

file_peek_path_generic (GFile *file)

{

  const char *path;

  static GQuark _file_path_quark = 0;

  if (G_UNLIKELY (_file_path_quark) == 0)

    _file_path_quark = g_quark_from_static_string ("gio-file-path");

  /* We need to be careful about threading, as two threads calling

   * g_file_peek_path() on the same file could race: both would see

   * (g_object_get_qdata(…) == NULL) to begin with, both would generate and add

   * the path, but the second thread to add it would end up freeing the path

   * set by the first thread. The first thread would still return the pointer

   * to that freed path, though, resulting an a read-after-free. Handle that

   * with a compare-and-swap loop. The g_object_*_qdata() functions are atomic. */

  while (TRUE)

    {

      gchar *new_path = NULL;

      path = g_object_get_qdata ((GObject*)file, _file_path_quark);

      if (path != NULL)

        break;

      new_path = g_file_get_path (file);

      if (new_path == NULL)

        return NULL;

      /* By passing NULL here, we ensure we never replace existing data: */

      if (g_object_replace_qdata ((GObject *) file, _file_path_quark,

                                  NULL, (gpointer) new_path,

                                  (GDestroyNotify) g_free, NULL))

        {

          path = new_path;

          break;

        }

      else

        g_free (new_path);

    }

  return path;

}

/**

 * g_file_peek_path:

 * @file: input #GFile

 *

 * Exactly like g_file_get_path(), but caches the result via

 * g_object_set_qdata_full().  This is useful for example in C

 * applications which mix `g_file_*` APIs with native ones.  It

 * also avoids an extra duplicated string when possible, so will be

 * generally more efficient.

 *

 * This call does no blocking I/O.

 *

 * Returns: (type filename) (nullable): string containing the #GFile's path,

 *     or %NULL if no such path exists. The returned string is owned by @file.

 * Since: 2.56

 */

const char *

g_file_peek_path (GFile *file)

{

  if (G_IS_LOCAL_FILE (file))

    return _g_local_file_get_filename ((GLocalFile *) file);

  return file_peek_path_generic (file);

}

/**

 * g_file_get_uri:

 * @file: input #GFile

 *

 * Gets the URI for the @file.

 *

 * This call does no blocking I/O.

 *

 * Returns: a string containing the #GFile's URI. If the #GFile was constructed

 *     with an invalid URI, an invalid URI is returned.

 *     The returned string should be freed with g_free()

 *     when no longer needed.

 */

char *

g_file_get_uri (GFile *file)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_uri) (file);

}

/**

 * g_file_get_parse_name:

 * @file: input #GFile

 *

 * Gets the parse name of the @file.

 * A parse name is a UTF-8 string that describes the

 * file such that one can get the #GFile back using

 * g_file_parse_name().

 *

 * This is generally used to show the #GFile as a nice

 * full-pathname kind of string in a user interface,

 * like in a location entry.

 *

 * For local files with names that can safely be converted

 * to UTF-8 the pathname is used, otherwise the IRI is used

 * (a form of URI that allows UTF-8 characters unescaped).

 *

 * This call does no blocking I/O.

 *

 * Returns: a string containing the #GFile's parse name.

 *     The returned string should be freed with g_free()

 *     when no longer needed.

 */

char *

g_file_get_parse_name (GFile *file)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_parse_name) (file);

}

/**

 * g_file_dup:

 * @file: input #GFile

 *

 * Duplicates a #GFile handle. This operation does not duplicate

 * the actual file or directory represented by the #GFile; see

 * g_file_copy() if attempting to copy a file.

 *

 * g_file_dup() is useful when a second handle is needed to the same underlying

 * file, for use in a separate thread (#GFile is not thread-safe). For use

 * within the same thread, use g_object_ref() to increment the existing object’s

 * reference count.

 *

 * This call does no blocking I/O.

 *

 * Returns: (transfer full): a new #GFile that is a duplicate

 *     of the given #GFile.

 */

GFile *

g_file_dup (GFile *file)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->dup) (file);

}

/**

 * g_file_hash:

 * @file: (type GFile): #gconstpointer to a #GFile

 *

 * Creates a hash value for a #GFile.

 *

 * This call does no blocking I/O.

 *

 * Virtual: hash

 * Returns: 0 if @file is not a valid #GFile, otherwise an

 *     integer that can be used as hash value for the #GFile.

 *     This function is intended for easily hashing a #GFile to

 *     add to a #GHashTable or similar data structure.

 */

guint

g_file_hash (gconstpointer file)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), 0);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->hash) ((GFile *)file);

}

/**

 * g_file_equal:

 * @file1: the first #GFile

 * @file2: the second #GFile

 *

 * Checks if the two given #GFiles refer to the same file.

 *

 * Note that two #GFiles that differ can still refer to the same

 * file on the filesystem due to various forms of filename

 * aliasing.

 *

 * This call does no blocking I/O.

 *

 * Returns: %TRUE if @file1 and @file2 are equal.

 */

gboolean

g_file_equal (GFile *file1,

              GFile *file2)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file1), FALSE);

  g_return_val_if_fail (G_IS_FILE (file2), FALSE);

  if (file1 == file2)

    return TRUE;

  if (G_TYPE_FROM_INSTANCE (file1) != G_TYPE_FROM_INSTANCE (file2))

    return FALSE;

  iface = G_FILE_GET_IFACE (file1);

  return (* iface->equal) (file1, file2);

}

/**

 * g_file_get_parent:

 * @file: input #GFile

 *

 * Gets the parent directory for the @file.

 * If the @file represents the root directory of the

 * file system, then %NULL will be returned.

 *

 * This call does no blocking I/O.

 *

 * Returns: (nullable) (transfer full): a #GFile structure to the

 *     parent of the given #GFile or %NULL if there is no parent. Free

 *     the returned object with g_object_unref().

 */

GFile *

g_file_get_parent (GFile *file)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_parent) (file);

}

/**

 * g_file_has_parent:

 * @file: input #GFile

 * @parent: (nullable): the parent to check for, or %NULL

 *

 * Checks if @file has a parent, and optionally, if it is @parent.

 *

 * If @parent is %NULL then this function returns %TRUE if @file has any

 * parent at all.  If @parent is non-%NULL then %TRUE is only returned

 * if @file is an immediate child of @parent.

 *

 * Returns: %TRUE if @file is an immediate child of @parent (or any parent in

 *          the case that @parent is %NULL).

 *

 * Since: 2.24

 */

gboolean

g_file_has_parent (GFile *file,

                   GFile *parent)

{

  GFile *actual_parent;

  gboolean result;

  g_return_val_if_fail (G_IS_FILE (file), FALSE);

  g_return_val_if_fail (parent == NULL || G_IS_FILE (parent), FALSE);

  actual_parent = g_file_get_parent (file);

  if (actual_parent != NULL)

    {

      if (parent != NULL)

        result = g_file_equal (parent, actual_parent);

      else

        result = TRUE;

      g_object_unref (actual_parent);

    }

  else

    result = FALSE;

  return result;

}

/**

 * g_file_get_child:

 * @file: input #GFile

 * @name: (type filename): string containing the child's basename

 *

 * Gets a child of @file with basename equal to @name.

 *

 * Note that the file with that specific name might not exist, but

 * you can still have a #GFile that points to it. You can use this

 * for instance to create that file.

 *

 * This call does no blocking I/O.

 *

 * Returns: (transfer full): a #GFile to a child specified by @name.

 *     Free the returned object with g_object_unref().

 */

GFile *

g_file_get_child (GFile      *file,

                  const char *name)

{

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  g_return_val_if_fail (name != NULL, NULL);

  return g_file_resolve_relative_path (file, name);

}

/**

 * g_file_get_child_for_display_name:

 * @file: input #GFile

 * @display_name: string to a possible child

 * @error: return location for an error

 *

 * Gets the child of @file for a given @display_name (i.e. a UTF-8

 * version of the name). If this function fails, it returns %NULL

 * and @error will be set. This is very useful when constructing a

 * #GFile for a new file and the user entered the filename in the

 * user interface, for instance when you select a directory and

 * type a filename in the file selector.

 *

 * This call does no blocking I/O.

 *

 * Returns: (transfer full): a #GFile to the specified child, or

 *     %NULL if the display name couldn't be converted.

 *     Free the returned object with g_object_unref().

 */

GFile *

g_file_get_child_for_display_name (GFile      *file,

                                   const char *display_name,

                                   GError **error)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  g_return_val_if_fail (display_name != NULL, NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_child_for_display_name) (file, display_name, error);

}

/**

 * g_file_has_prefix:

 * @file: input #GFile

 * @prefix: input #GFile

 *

 * Checks whether @file has the prefix specified by @prefix.

 *

 * In other words, if the names of initial elements of @file's

 * pathname match @prefix. Only full pathname elements are matched,

 * so a path like /foo is not considered a prefix of /foobar, only

 * of /foo/bar.

 *

 * A #GFile is not a prefix of itself. If you want to check for

 * equality, use g_file_equal().

 *

 * This call does no I/O, as it works purely on names. As such it can

 * sometimes return %FALSE even if @file is inside a @prefix (from a

 * filesystem point of view), because the prefix of @file is an alias

 * of @prefix.

 *

 * Virtual: prefix_matches

 * Returns:  %TRUE if the @file's parent, grandparent, etc is @prefix,

 *     %FALSE otherwise.

 */

gboolean

g_file_has_prefix (GFile *file,

                   GFile *prefix)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), FALSE);

  g_return_val_if_fail (G_IS_FILE (prefix), FALSE);

  if (G_TYPE_FROM_INSTANCE (file) != G_TYPE_FROM_INSTANCE (prefix))

    return FALSE;

  iface = G_FILE_GET_IFACE (file);

  /* The vtable function differs in arg order since

   * we're using the old contains_file call

   */

  return (* iface->prefix_matches) (prefix, file);

}

/**

 * g_file_get_relative_path: (virtual get_relative_path)

 * @parent: input #GFile

 * @descendant: input #GFile

 *

 * Gets the path for @descendant relative to @parent.

 *

 * This call does no blocking I/O.

 *

 * Returns: (type filename) (nullable): string with the relative path from

 *     @descendant to @parent, or %NULL if @descendant doesn't have @parent as

 *     prefix. The returned string should be freed with g_free() when

 *     no longer needed.

 */

char *

g_file_get_relative_path (GFile *parent,

                          GFile *descendant)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (parent), NULL);

  g_return_val_if_fail (G_IS_FILE (descendant), NULL);

  if (G_TYPE_FROM_INSTANCE (parent) != G_TYPE_FROM_INSTANCE (descendant))

    return NULL;

  iface = G_FILE_GET_IFACE (parent);

  return (* iface->get_relative_path) (parent, descendant);

}

/**

 * g_file_resolve_relative_path:

 * @file: input #GFile

 * @relative_path: (type filename): a given relative path string

 *

 * Resolves a relative path for @file to an absolute path.

 *

 * This call does no blocking I/O.

 *

 * Returns: (transfer full): #GFile to the resolved path.

 *     %NULL if @relative_path is %NULL or if @file is invalid.

 *     Free the returned object with g_object_unref().

 */

GFile *

g_file_resolve_relative_path (GFile      *file,

                              const char *relative_path)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  g_return_val_if_fail (relative_path != NULL, NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->resolve_relative_path) (file, relative_path);

}

/**

 * g_file_enumerate_children:

 * @file: input #GFile

 * @attributes: an attribute query string

 * @flags: a set of #GFileQueryInfoFlags

 * @cancellable: (nullable): optional #GCancellable object,

 *     %NULL to ignore

 * @error: #GError for error reporting

 *

 * Gets the requested information about the files in a directory.

 * The result is a #GFileEnumerator object that will give out

 * #GFileInfo objects for all the files in the directory.

 *

 * The @attributes value is a string that specifies the file

 * attributes that should be gathered. It is not an error if

 * it's not possible to read a particular requested attribute

 * from a file - it just won't be set. @attributes should

 * be a comma-separated list of attributes or attribute wildcards.

 * The wildcard "*" means all attributes, and a wildcard like

 * "standard::*" means all attributes in the standard namespace.

 * An example attribute query be "standard::*,owner::user".

 * The standard attributes are available as defines, like

 * #G_FILE_ATTRIBUTE_STANDARD_NAME.

 *

 * If @cancellable is not %NULL, then the operation can be cancelled

 * by triggering the cancellable object from another thread. If the

 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be

 * returned.

 *

 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will

 * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY

 * error will be returned. Other errors are possible too.

 *

 * Returns: (transfer full): A #GFileEnumerator if successful,

 *     %NULL on error. Free the returned object with g_object_unref().

 */

GFileEnumerator *

g_file_enumerate_children (GFile                *file,

                           const char           *attributes,

                           GFileQueryInfoFlags   flags,

                           GCancellable         *cancellable,

                           GError              **error)

{

  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  if (g_cancellable_set_error_if_cancelled (cancellable, error))

    return NULL;

  iface = G_FILE_GET_IFACE (file);