gfile.c 290 KB
Newer Older
1 2
/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */

3 4 5 6 7 8 9
/* 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
10
 * version 2.1 of the License, or (at your option) any later version.
11 12 13 14 15 16 17
 *
 * 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
18
 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 20 21 22
 *
 * Author: Alexander Larsson <alexl@redhat.com>
 */

23
#include "config.h"
24

25
#ifdef __linux__
26 27 28 29 30 31 32
#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

33 34 35 36 37 38
#ifdef HAVE_SPLICE
#include <sys/stat.h>
#include <unistd.h>
#include <fcntl.h>
#include <errno.h>
#endif
39

40 41
#include <string.h>
#include <sys/types.h>
42

43
#include "gfile.h"
Colin Walters's avatar
Colin Walters committed
44
#include "glib/gstdio.h"
45 46 47
#ifdef G_OS_UNIX
#include "glib-unix.h"
#endif
48
#include "gvfs.h"
49
#include "gtask.h"
50
#include "gfileattribute-priv.h"
51
#include "gfiledescriptorbased.h"
52
#include "gpollfilemonitor.h"
53 54 55
#include "gappinfo.h"
#include "gfileinputstream.h"
#include "gfileoutputstream.h"
56 57
#include "glocalfileoutputstream.h"
#include "glocalfileiostream.h"
58
#include "glocalfile.h"
59 60 61
#include "gcancellable.h"
#include "gasyncresult.h"
#include "gioerror.h"
62 63
#include "glibintl.h"

64

65 66 67
/**
 * SECTION:gfile
 * @short_description: File and Directory Handling
Matthias Clasen's avatar
Matthias Clasen committed
68
 * @include: gio/gio.h
69
 * @see_also: #GFileInfo, #GFileEnumerator
70 71 72 73 74 75 76 77 78
 *
 * #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:
79 80 81 82 83
 * - 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().
84
 * - g_file_new_build_filename() to create a file from path elements.
85 86 87 88 89 90 91 92 93 94 95 96 97
 *
 * 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
98 99
 * files.
 *
100 101 102 103 104 105
 * 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
106
 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
107 108 109 110 111 112 113 114 115 116 117
 * 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
118
 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
119 120 121 122 123 124 125 126 127 128
 * 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.
129
 *
130 131 132 133 134 135 136 137 138
 * 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:
139 140 141
 * - 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.
142
 *
143 144
 * ## Entity Tags # {#gfile-etag}
 *
145 146
 * One notable feature of #GFiles are entity tags, or "etags" for
 * short. Entity tags are somewhat like a more abstract version of the
147 148
 * traditional mtime, and can be used to quickly determine if the file
 * has been modified from the version on the file system. See the
149 150
 * HTTP 1.1 
 * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
Matthias Clasen's avatar
Matthias Clasen committed
151
 * for HTTP Etag headers, which are a very similar concept.
152
 */
153

154
static void               g_file_real_query_info_async            (GFile                  *file,
155 156 157 158 159 160
                                                                   const char             *attributes,
                                                                   GFileQueryInfoFlags     flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
161
static GFileInfo *        g_file_real_query_info_finish           (GFile                  *file,
162 163
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
164
static void               g_file_real_query_filesystem_info_async (GFile                  *file,
165 166 167 168 169
                                                                   const char             *attributes,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
170
static GFileInfo *        g_file_real_query_filesystem_info_finish (GFile                  *file,
171 172
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
173
static void               g_file_real_enumerate_children_async    (GFile                  *file,
174 175 176 177 178 179
                                                                   const char             *attributes,
                                                                   GFileQueryInfoFlags     flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
180
static GFileEnumerator *  g_file_real_enumerate_children_finish   (GFile                  *file,
181 182
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
183
static void               g_file_real_read_async                  (GFile                  *file,
184 185 186 187
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
188
static GFileInputStream * g_file_real_read_finish                 (GFile                  *file,
189 190
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
191
static void               g_file_real_append_to_async             (GFile                  *file,
192 193 194 195 196
                                                                   GFileCreateFlags        flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
197
static GFileOutputStream *g_file_real_append_to_finish            (GFile                  *file,
198 199
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
200
static void               g_file_real_create_async                (GFile                  *file,
201 202 203 204 205
                                                                   GFileCreateFlags        flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
206
static GFileOutputStream *g_file_real_create_finish               (GFile                  *file,
207 208
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
209
static void               g_file_real_replace_async               (GFile                  *file,
210 211 212 213 214 215 216
                                                                   const char             *etag,
                                                                   gboolean                make_backup,
                                                                   GFileCreateFlags        flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
217
static GFileOutputStream *g_file_real_replace_finish              (GFile                  *file,
218 219
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
220
static void               g_file_real_delete_async                (GFile                  *file,
221 222 223 224
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
225
static gboolean           g_file_real_delete_finish               (GFile                  *file,
226 227
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
228 229 230 231 232 233 234 235
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);
236 237 238 239 240 241 242 243
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);
244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271
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);
272
static gboolean           g_file_real_set_attributes_from_info    (GFile                  *file,
273 274 275 276
                                                                   GFileInfo              *info,
                                                                   GFileQueryInfoFlags     flags,
                                                                   GCancellable           *cancellable,
                                                                   GError                **error);
277
static void               g_file_real_set_display_name_async      (GFile                  *file,
278 279 280 281 282
                                                                   const char             *display_name,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
283
static GFile *            g_file_real_set_display_name_finish     (GFile                  *file,
284 285
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
286
static void               g_file_real_set_attributes_async        (GFile                  *file,
287 288 289 290 291 292
                                                                   GFileInfo              *info,
                                                                   GFileQueryInfoFlags     flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
293
static gboolean           g_file_real_set_attributes_finish       (GFile                  *file,
294 295 296
                                                                   GAsyncResult           *res,
                                                                   GFileInfo             **info,
                                                                   GError                **error);
297
static void               g_file_real_find_enclosing_mount_async  (GFile                  *file,
298 299 300 301
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
302
static GMount *           g_file_real_find_enclosing_mount_finish (GFile                  *file,
303 304
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
305
static void               g_file_real_copy_async                  (GFile                  *source,
306 307 308 309 310 311 312 313
                                                                   GFile                  *destination,
                                                                   GFileCopyFlags          flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GFileProgressCallback   progress_callback,
                                                                   gpointer                progress_callback_data,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
314
static gboolean           g_file_real_copy_finish                 (GFile                  *file,
315 316
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
317

318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341
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);

342 343
typedef GFileIface GFileInterface;
G_DEFINE_INTERFACE (GFile, g_file, G_TYPE_OBJECT)
344 345

static void
346
g_file_default_init (GFileIface *iface)
347 348 349 350 351 352 353
{
  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;
354 355
  iface->query_filesystem_info_async = g_file_real_query_filesystem_info_async;
  iface->query_filesystem_info_finish = g_file_real_query_filesystem_info_finish;
356 357 358 359 360 361 362 363 364 365
  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;
366 367
  iface->delete_file_async = g_file_real_delete_async;
  iface->delete_file_finish = g_file_real_delete_finish;
368 369
  iface->trash_async = g_file_real_trash_async;
  iface->trash_finish = g_file_real_trash_finish;
370 371
  iface->make_directory_async = g_file_real_make_directory_async;
  iface->make_directory_finish = g_file_real_make_directory_finish;
372 373 374 375 376 377
  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;
378 379
  iface->find_enclosing_mount_async = g_file_real_find_enclosing_mount_async;
  iface->find_enclosing_mount_finish = g_file_real_find_enclosing_mount_finish;
380
  iface->set_attributes_from_info = g_file_real_set_attributes_from_info;
381 382
  iface->copy_async = g_file_real_copy_async;
  iface->copy_finish = g_file_real_copy_finish;
383 384 385
  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;
386 387 388 389 390
}


/**
 * g_file_is_native:
391
 * @file: input #GFile
392
 *
393
 * Checks to see if a file is native to the platform.
394
 *
395
 * A native file is one expressed in the platform-native filename format,
396 397 398
 * 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.
 *
399 400 401
 * 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.
402
 *
403 404 405 406
 * This call does no blocking I/O.
 *
 * Returns: %TRUE if @file is native
 */
407 408 409 410 411 412 413 414 415 416 417 418 419 420
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);
}


/**
421 422 423
 * g_file_has_uri_scheme:
 * @file: input #GFile
 * @uri_scheme: a string containing a URI scheme
424
 *
425 426
 * Checks to see if a #GFile has a given URI scheme.
 *
427 428
 * This call does no blocking I/O.
 *
429
 * Returns: %TRUE if #GFile's backend supports the
Matthias Clasen's avatar
Matthias Clasen committed
430 431
 *     given URI scheme, %FALSE if URI scheme is %NULL,
 *     not supported, or #GFile is invalid.
432
 */
433
gboolean
Matthias Clasen's avatar
Matthias Clasen committed
434
g_file_has_uri_scheme (GFile      *file,
435
                       const char *uri_scheme)
436 437
{
  GFileIface *iface;
438

439 440 441 442 443 444 445 446 447 448 449
  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:
450
 * @file: input #GFile
451
 *
452
 * Gets the URI scheme for a #GFile.
453
 * RFC 3986 decodes the scheme as:
454
 * |[
455
 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
456
 * ]|
457
 * Common schemes include "file", "http", "ftp", etc.
458
 *
459 460 461 462
 * This call does no blocking I/O.
 *
 * Returns: a string containing the URI scheme for the given
 *     #GFile. The returned string should be freed with g_free()
463
 *     when no longer needed.
464
 */
465 466 467 468 469 470 471 472 473 474 475 476 477 478 479
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:
480
 * @file: input #GFile
481
 *
482
 * Gets the base name (the last component of the path) for a given #GFile.
483
 *
484
 * If called for the top level of a system (such as the filesystem root
485
 * or a uri like sftp://host/) it will return a single directory separator
486
 * (and on Windows, possibly a drive letter).
487
 *
488
 * The base name is a byte string (not UTF-8). It has no defined encoding
489 490 491 492
 * 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().
493 494 495
 *
 * This call does no blocking I/O.
 *
496 497 498
 * 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.
499
 */
500 501 502 503
char *
g_file_get_basename (GFile *file)
{
  GFileIface *iface;
504

505 506 507 508 509 510 511 512 513
  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:
514
 * @file: input #GFile
515
 *
516 517
 * 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.
518
 *
519 520
 * This call does no blocking I/O.
 *
521 522
 * Returns: (type filename) (nullable): string containing the #GFile's path,
 *     or %NULL if no such path exists. The returned string should be freed
523
 *     with g_free() when no longer needed.
524
 */
525 526 527 528 529 530 531 532 533 534 535 536
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);
}

537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637
/* Original commit introducing this in libgsystem:
 *
 *  fileutil: Handle recent: and trash: URIs
 *
 *  The gs_file_get_path_cached() was rather brittle in its handling
 *  of URIs. It would assert() when a GFile didn't have a backing path
 *  (such as when handling trash: or recent: URIs), and didn't know
 *  how to get the target URI for those items either.
 *
 *  Make sure that we do not assert() when a backing path cannot be
 *  found, and handle recent: and trash: URIs.
 *
 *  https://bugzilla.gnome.org/show_bug.cgi?id=708435
 */
static char *
file_get_target_path (GFile *file)
{
  GFileInfo *info;
  const char *target;
  char *path;

  info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_TARGET_URI, G_FILE_QUERY_INFO_NONE, NULL, NULL);
  if (info == NULL)
    return NULL;
  target = g_file_info_get_attribute_string (info, G_FILE_ATTRIBUTE_STANDARD_TARGET_URI);
  path = g_filename_from_uri (target, NULL, NULL);
  g_object_unref (info);

  return path;
}

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;

      if (g_file_has_uri_scheme (file, "trash") ||
          g_file_has_uri_scheme (file, "recent"))
        new_path = file_get_target_path (file);
      else
        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))
        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);
}

638 639
/**
 * g_file_get_uri:
640
 * @file: input #GFile
641
 *
642
 * Gets the URI for the @file.
643
 *
644 645
 * This call does no blocking I/O.
 *
646
 * Returns: a string containing the #GFile's URI.
647 648 649
 *     The returned string should be freed with g_free()
 *     when no longer needed.
 */
650 651 652 653
char *
g_file_get_uri (GFile *file)
{
  GFileIface *iface;
654

655 656 657 658 659 660 661 662
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

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

/**
Matthias Clasen's avatar
Matthias Clasen committed
663
 * g_file_get_parse_name:
664
 * @file: input #GFile
665
 *
666 667 668 669 670 671
 * 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
672 673
 * full-pathname kind of string in a user interface,
 * like in a location entry.
674
 *
675
 * For local files with names that can safely be converted
676 677
 * to UTF-8 the pathname is used, otherwise the IRI is used
 * (a form of URI that allows UTF-8 characters unescaped).
678
 *
679 680 681 682 683 684
 * 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.
 */
685 686 687 688
char *
g_file_get_parse_name (GFile *file)
{
  GFileIface *iface;
689

690 691 692 693 694 695 696 697 698
  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:
699
 * @file: input #GFile
700
 *
701 702 703
 * 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.
704
 *
705 706 707 708 709
 * 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.
 *
710 711 712 713 714
 * This call does no blocking I/O.
 *
 * Returns: (transfer full): a new #GFile that is a duplicate
 *     of the given #GFile.
 */
715 716 717 718
GFile *
g_file_dup (GFile *file)
{
  GFileIface *iface;
719

720 721 722 723 724 725 726 727 728
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

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

/**
 * g_file_hash:
729
 * @file: (type GFile): #gconstpointer to a #GFile
730
 *
731
 * Creates a hash value for a #GFile.
732
 *
733
 * This call does no blocking I/O.
734 735
 *
 * Virtual: hash
736 737 738
 * 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
739
 *     add to a #GHashTable or similar data structure.
740
 */
741 742 743 744
guint
g_file_hash (gconstpointer file)
{
  GFileIface *iface;
745

746 747 748 749 750 751 752 753 754
  g_return_val_if_fail (G_IS_FILE (file), 0);

  iface = G_FILE_GET_IFACE (file);

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

/**
 * g_file_equal:
755 756 757
 * @file1: the first #GFile
 * @file2: the second #GFile
 *
Benjamin Otte's avatar
Benjamin Otte committed
758
 * Checks if the two given #GFiles refer to the same file.
759
 *
760
 * Note that two #GFiles that differ can still refer to the same
761 762
 * file on the filesystem due to various forms of filename
 * aliasing.
763
 *
764 765
 * This call does no blocking I/O.
 *
766
 * Returns: %TRUE if @file1 and @file2 are equal.
767
 */
768 769
gboolean
g_file_equal (GFile *file1,
770
              GFile *file2)
771 772
{
  GFileIface *iface;
773

774 775
  g_return_val_if_fail (G_IS_FILE (file1), FALSE);
  g_return_val_if_fail (G_IS_FILE (file2), FALSE);
776

777 778 779
  if (file1 == file2)
    return TRUE;

780 781 782 783
  if (G_TYPE_FROM_INSTANCE (file1) != G_TYPE_FROM_INSTANCE (file2))
    return FALSE;

  iface = G_FILE_GET_IFACE (file1);
784

785 786 787 788 789 790
  return (* iface->equal) (file1, file2);
}


/**
 * g_file_get_parent:
791
 * @file: input #GFile
792
 *
793 794
 * Gets the parent directory for the @file.
 * If the @file represents the root directory of the
795
 * file system, then %NULL will be returned.
796
 *
797 798
 * This call does no blocking I/O.
 *
799 800 801
 * 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().
802
 */
803 804 805 806
GFile *
g_file_get_parent (GFile *file)
{
  GFileIface *iface;
807

808 809 810 811 812 813 814
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

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

815 816 817
/**
 * g_file_has_parent:
 * @file: input #GFile
818
 * @parent: (nullable): the parent to check for, or %NULL
819 820 821 822 823
 *
 * 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
824
 * if @file is an immediate child of @parent.
825
 *
826 827
 * Returns: %TRUE if @file is an immediate child of @parent (or any parent in
 *          the case that @parent is %NULL).
828 829
 *
 * Since: 2.24
830
 */
831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857
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;
}

858 859
/**
 * g_file_get_child:
860
 * @file: input #GFile
861
 * @name: (type filename): string containing the child's basename
862
 *
863
 * Gets a child of @file with basename equal to @name.
864 865 866 867
 *
 * 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.
868
 *
869 870
 * This call does no blocking I/O.
 *
871
 * Returns: (transfer full): a #GFile to a child specified by @name.
Matthias Clasen's avatar
Matthias Clasen committed
872
 *     Free the returned object with g_object_unref().
873
 */
874
GFile *
Matthias Clasen's avatar
Matthias Clasen committed
875
g_file_get_child (GFile      *file,
876
                  const char *name)
877 878 879 880 881 882 883 884 885
{
  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:
886 887 888 889 890 891 892 893 894 895 896 897 898 899 900
 * @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.
Matthias Clasen's avatar
Matthias Clasen committed
901
 *     Free the returned object with g_object_unref().
902
 */
903
GFile *
Matthias Clasen's avatar
Matthias Clasen committed
904
g_file_get_child_for_display_name (GFile      *file,
905 906
                                   const char *display_name,
                                   GError **error)
907 908
{
  GFileIface *iface;
909

910 911 912 913 914 915 916 917
  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);
}

918 919
/**
 * g_file_has_prefix:
920 921 922 923 924 925 926 927 928 929
 * @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.
 *
Benjamin Otte's avatar
Benjamin Otte committed
930 931 932
 * A #GFile is not a prefix of itself. If you want to check for
 * equality, use g_file_equal().
 *
933 934 935
 * 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
Matthias Clasen's avatar
Matthias Clasen committed
936
 * of @prefix.
937
 *
938
 * Virtual: prefix_matches
939
 * Returns:  %TRUE if the @files's parent, grandparent, etc is @prefix,
Matthias Clasen's avatar
Matthias Clasen committed
940
 *     %FALSE otherwise.
941
 */
942 943
gboolean
g_file_has_prefix (GFile *file,
944
                   GFile *prefix)
945 946
{
  GFileIface *iface;
947

948 949
  g_return_val_if_fail (G_IS_FILE (file), FALSE);
  g_return_val_if_fail (G_IS_FILE (prefix), FALSE);
950

951
  if (G_TYPE_FROM_INSTANCE (file) != G_TYPE_FROM_INSTANCE (prefix))
952
    return FALSE;
953

954
  iface = G_FILE_GET_IFACE (file);
955

956 957 958
  /* The vtable function differs in arg order since
   * we're using the old contains_file call
   */
959
  return (* iface->prefix_matches) (prefix, file);
960 961 962 963
}

/**
 * g_file_get_relative_path:
964 965
 * @parent: input #GFile
 * @descendant: input #GFile
966
 *
967
 * Gets the path for @descendant relative to @parent.
968
 *
969 970
 * This call does no blocking I/O.
 *
971 972
 * Returns: (type filename) (nullable): string with the relative path from
 *     @descendant to @parent, or %NULL if @descendant doesn't have @parent as
973 974
 *     prefix. The returned string should be freed with g_free() when
 *     no longer needed.
975
 */
976 977
char *
g_file_get_relative_path (GFile *parent,
978
                          GFile *descendant)
979 980
{
  GFileIface *iface;
981

982 983 984 985 986
  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;
987

988 989 990 991 992 993 994
  iface = G_FILE_GET_IFACE (parent);

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

/**
 * g_file_resolve_relative_path:
995
 * @file: input #GFile
996
 * @relative_path: (type filename): a given relative path string
997
 *
998 999
 * Resolves a relative path for @file to an absolute path.
 *
1000 1001 1002 1003
 * 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.
Matthias Clasen's avatar
Matthias Clasen committed
1004
 *     Free the returned object with g_object_unref().
1005
 */
1006
GFile *
Matthias Clasen's avatar
Matthias Clasen committed
1007
g_file_resolve_relative_path (GFile      *file,
1008
                              const char *relative_path)
1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021
{
  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:
1022 1023 1024
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
1025
 * @cancellable: (nullable): optional #GCancellable object,
1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049
 *     %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
1050
 * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
1051 1052 1053 1054 1055
 * 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().
 */
1056
GFileEnumerator *
Matthias Clasen's avatar
Matthias Clasen committed
1057
g_file_enumerate_children (GFile                *file,
1058 1059 1060 1061
                           const char           *attributes,
                           GFileQueryInfoFlags   flags,
                           GCancellable         *cancellable,
                           GError              **error)
1062 1063
{
  GFileIface *iface;
1064

1065 1066 1067 1068
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  if (g_cancellable_set_error_if_cancelled (cancellable, error))
    return NULL;
1069

1070 1071 1072 1073
  iface = G_FILE_GET_IFACE (file);

  if (iface->enumerate_children == NULL)
    {
1074 1075 1076
      g_set_error_literal (error, G_IO_ERROR,
                           G_IO_ERROR_NOT_SUPPORTED,
                           _("Operation not supported"));
1077 1078 1079 1080
      return NULL;
    }

  return (* iface->enumerate_children) (file, attributes, flags,
1081
                                        cancellable, error);
1082 1083 1084 1085
}

/**
 * g_file_enumerate_children_async:
1086 1087 1088
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
1089
 * @io_priority: the [I/O priority][io-priority] of the request
1090
 * @cancellable: (nullable): optional #GCancellable object,
1091 1092
 *     %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call when the
1093 1094
 *     request is satisfied
 * @user_data: (closure): the data to pass to callback function
1095
 *
1096 1097 1098
 * Asynchronously 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.
1099 1100 1101 1102
 *
 * For more details, see g_file_enumerate_children() which is
 * the synchronous version of this call.
 *
1103 1104 1105 1106
 * When the operation is finished, @callback will be called. You can
 * then call g_file_enumerate_children_finish() to get the result of
 * the operation.
 */
1107
void
Matthias Clasen's avatar
Matthias Clasen committed
1108
g_file_enumerate_children_async (GFile               *file,
1109 1110 1111 1112 1113 1114
                                 const char          *attributes,
                                 GFileQueryInfoFlags  flags,
                                 int                  io_priority,
                                 GCancellable        *cancellable,
                                 GAsyncReadyCallback  callback,
                                 gpointer             user_data)
1115 1116 1117 1118 1119 1120 1121
{
  GFileIface *iface;

  g_return_if_fail (G_IS_FILE (file));

  iface = G_FILE_GET_IFACE (file);
  (* iface->enumerate_children_async) (file,
1122 1123 1124 1125 1126 1127
                                       attributes,
                                       flags,
                                       io_priority,
                                       cancellable,
                                       callback,
                                       user_data);
1128 1129 1130 1131
}

/**
 * g_file_enumerate_children_finish:
1132 1133 1134 1135
 * @file: input #GFile
 * @res: a #GAsyncResult
 * @error: a #GError
 *
Matthias Clasen's avatar
Matthias Clasen committed
1136
 * Finishes an async enumerate children operation.
1137
 * See g_file_enumerate_children_async().
Matthias Clasen's avatar
Matthias Clasen committed
1138
 *
1139 1140
 * Returns: (transfer full): a #GFileEnumerator or %NULL
 *     if an error occurred.
1141
 *     Free the returned object with g_object_unref().
1142
 */
1143
GFileEnumerator *
Matthias Clasen's avatar
Matthias Clasen committed
1144
g_file_enumerate_children_finish (GFile         *file,
1145 1146
                                  GAsyncResult  *res,
                                  GError       **error)
1147 1148
{
  GFileIface *iface;
1149

1150 1151 1152
  g_return_val_if_fail (G_IS_FILE (file), NULL);
  g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);

1153 1154
  if (g_async_result_legacy_propagate_error (res, error))
    return NULL;
1155

1156 1157 1158 1159
  iface = G_FILE_GET_IFACE (file);
  return (* iface->enumerate_children_finish) (file, res, error);
}

1160 1161
/**
 * g_file_query_exists:
1162
 * @file: input #GFile
1163
 * @cancellable: (nullable): optional #GCancellable object,
1164
 *     %NULL to ignore
1165 1166 1167 1168
 *
 * Utility function to check if a particular file exists. This is
 * implemented using g_file_query_info() and as such does blocking I/O.
 *
1169
 * 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)
1170
 * and then execute something based on the outcome of that, because the
1171
 * file might have been created or removed in between the operations. The
1172 1173 1174
 * general approach to handling that is to not check, but just do the
 * operation and handle the errors as they come.
 *
1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190
 * As an example of race-free checking, take the case of reading a file,
 * and if it doesn't exist, creating it. There are two racy versions: read
 * it, and on error create it; and: check if it exists, if not create it.
 * These can both result in two processes creating the file (with perhaps
 * a partially written file as the result). The correct approach is to
 * always try to create the file with g_file_create() which will either
 * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
 *
 * However, in many cases an existence check is useful in a user interface,
 * for instance to make a menu item sensitive/insensitive, so that you don't
 * have to fool users that something is possible and then just show an error
 * dialog. If you do this, you should make sure to also handle the errors
 * that can happen due to races when you execute the operation.
 *
 * Returns: %TRUE if the file exists (and can be detected without error),
 *     %FALSE otherwise (or if cancelled).
1191 1192
 */
gboolean
1193 1194
g_file_query_exists (GFile        *file,
                     GCancellable *cancellable)
1195 1196
{
  GFileInfo *info;
1197

1198
  g_return_val_if_fail (G_IS_FILE(file), FALSE);
1199

1200
  info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_TYPE,
1201
                            G_FILE_QUERY_INFO_NONE, cancellable, NULL);
1202 1203 1204 1205 1206
  if (info != NULL)
    {
      g_object_unref (info);
      return TRUE;
    }
1207

1208 1209
  return FALSE;
}
1210

1211 1212
/**
 * g_file_query_file_type:
1213 1214
 * @file: input #GFile
 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
1215
 * @cancellable: (nullable): optional #GCancellable object,
1216
 *     %NULL to ignore
1217 1218 1219 1220
 *
 * Utility function to inspect the #GFileType of a file. This is
 * implemented using g_file_query_info() and as such does blocking I/O.
 *
1221 1222 1223 1224 1225
 * The primary use case of this method is to check if a file is
 * a regular file, directory, or symlink.
 *
 * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN
 *     if the file does not exist
1226 1227 1228 1229
 *
 * Since: 2.18
 */
GFileType
1230 1231 1232
g_file_query_file_type (GFile               *file,
                        GFileQueryInfoFlags  flags,
                        GCancellable        *cancellable)
1233 1234 1235
{
  GFileInfo *info;
  GFileType file_type;
1236

1237
  g_return_val_if_fail (G_IS_FILE(file), G_FILE_TYPE_UNKNOWN);
1238
  info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_TYPE, flags,
1239
                            cancellable, NULL);
1240 1241 1242 1243 1244 1245 1246
  if (info != NULL)
    {
      file_type = g_file_info_get_file_type (info);
      g_object_unref (info);
    }
  else
    file_type = G_FILE_TYPE_UNKNOWN;
1247

1248 1249 1250
  return file_type;
}

1251 1252
/**
 * g_file_query_info:
1253 1254 1255
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
1256
 * @cancellable: (nullable): optional #GCancellable object,
1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278
 *     %NULL to ignore
 * @error: a #GError
 *
 * Gets the requested information about specified @file.
 * The result is a #GFileInfo object that contains key-value
 * attributes (such as the type or size of the file).
 *
 * 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.
1279 1280
 *
 * For symlinks, normally the information about the target of the
1281 1282 1283 1284 1285
 * symlink is returned, rather than information about the symlink
 * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
 * in @flags the information about the symlink itself will be returned.
 * Also, for symlinks that point to non-existing files the information
 * about the symlink itself will be returned.
1286
 *
1287 1288 1289
 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
 * returned. Other errors are possible too, and depend on what kind of
 * filesystem the file is on.
1290
 *
1291 1292 1293
 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
 *     on error. Free the returned object with g_object_unref().
 */
1294
GFileInfo *
Matthias Clasen's avatar
Matthias Clasen committed
1295
g_file_query_info (GFile                *file,
1296 1297 1298 1299
                   const char           *attributes,
                   GFileQueryInfoFlags   flags,
                   GCancellable         *cancellable,
                   GError              **error)
1300 1301
{
  GFileIface *iface;
1302

1303 1304 1305 1306
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  if (g_cancellable_set_error_if_cancelled (cancellable, error))
    return NULL;
1307

1308 1309 1310 1311
  iface = G_FILE_GET_IFACE (file);

  if (iface->query_info == NULL)
    {
1312 1313 1314
      g_set_error_literal (error, G_IO_ERROR,
                           G_IO_ERROR_NOT_SUPPORTED,
                           _("Operation not supported"));
1315 1316
      return NULL;
    }
1317

1318 1319 1320 1321 1322
  return (* iface->query_info) (file, attributes, flags, cancellable, error);
}

/**
 * g_file_query_info_async:
1323 1324 1325
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
1326
 * @io_priority: the [I/O priority][io-priority] of the request
1327
 * @cancellable: (nullable): optional #GCancellable object,
1328 1329 1330
 *     %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call when the
 *     request is satisfied
1331
 * @user_data: (closure): the data to pass to callback function
1332
 *
1333 1334 1335 1336 1337 1338 1339 1340 1341 1342
 * Asynchronously gets the requested information about specified @file.
 * The result is a #GFileInfo object that contains key-value attributes
 * (such as type or size for the file).
 *
 * For more details, see g_file_query_info() which is the synchronous
 * version of this call.
 *
 * When the operation is finished, @callback will be called. You can
 * then call g_file_query_info_finish() to get the result of the operation.
 */
1343
void
Matthias Clasen's avatar
Matthias Clasen committed
1344
g_file_query_info_async (GFile               *file,
1345 1346 1347 1348 1349 1350
                         const char          *attributes,
                         GFileQueryInfoFlags  flags,
                         int                  io_priority,
                         GCancellable        *cancellable,
                         GAsyncReadyCallback  callback,
                         gpointer             user_data)
1351 1352
{
  GFileIface *iface;
1353

1354 1355 1356 1357
  g_return_if_fail (G_IS_FILE (file));

  iface = G_FILE_GET_IFACE (file);
  (* iface->query_info_async) (file,
1358 1359 1360 1361 1362 1363
                               attributes,
                               flags,
                               io_priority,
                               cancellable,
                               callback,
                               user_data);
1364 1365 1366 1367
}

/**
 * g_file_query_info_finish:
1368 1369 1370 1371 1372
 * @file: input #GFile
 * @res: a #GAsyncResult
 * @error: a #GError
 *
 * Finishes an asynchronous file info query.
1373
 * See g_file_query_info_async().
1374 1375 1376 1377 1378
 *
 * Returns: (transfer full): #GFileInfo for given @file
 *     or %NULL on error. Free the returned object with
 *     g_object_unref().
 */
1379
GFileInfo *
Matthias Clasen's avatar
Matthias Clasen committed
1380
g_file_query_info_finish (GFile         *file,
1381 1382
                          GAsyncResult  *res,
                          GError       **error)
1383 1384 1385 1386 1387 1388
{
  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);
  g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);

1389 1390
  if (g_async_result_legacy_propagate_error (res, error))
    return NULL;
1391

1392 1393 1394 1395 1396 1397
  iface = G_FILE_GET_IFACE (file);
  return (* iface->query_info_finish) (file, res, error);
}

/**
 * g_file_query_filesystem_info:
1398 1399
 * @file: input #GFile
 * @attributes:  an attribute query string
1400
 * @cancellable: (nullable): optional #GCancellable object,
1401 1402 1403
 *     %NULL to ignore
 * @error: a #GError
 *
1404 1405
 * Similar to g_file_query_info(), but obtains information
 * about the filesystem the @file is on, rather than the file itself.
1406
 * For instance the amount of space available and the type of
1407 1408
 * the filesystem.
 *
1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428
 * The @attributes value is a string that specifies the 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 "filesystem::*" means all attributes
 * in the filesystem namespace. The standard namespace for filesystem
 * attributes is "filesystem". Common attributes of interest are
 * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
 * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
 * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
 *
 * 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. Other errors are possible too, and depend on what
 * kind of filesystem the file is on.
1429
 *
1430
 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
1431
 *     Free the returned object with g_object_unref().
1432
 */
1433
GFileInfo *
Matthias Clasen's avatar
Matthias Clasen committed
1434
g_file_query_filesystem_info (GFile         *file,
1435 1436 1437
                              const char    *attributes,
                              GCancellable  *cancellable,
                              GError       **error)
1438 1439
{
  GFileIface *iface;
1440

1441 1442 1443 1444
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  if (g_cancellable_set_error_if_cancelled (cancellable, error))
    return NULL;
1445

1446 1447 1448 1449
  iface = G_FILE_GET_IFACE (file);

  if (iface->query_filesystem_info == NULL)
    {
1450 1451 1452
      g_set_error_literal (error, G_IO_ERROR,
                           G_IO_ERROR_NOT_SUPPORTED,
                           _("Operation not supported"));
1453 1454
      return NULL;
    }
1455

1456 1457 1458
  return (* iface->query_filesystem_info) (file, attributes, cancellable, error);
}

1459 1460
/**
 * g_file_query_filesystem_info_async:
1461 1462
 * @file: input #GFile
 * @attributes: an attribute query string
1463
 * @io_priority: the [I/O priority][io-priority] of the request
1464
 * @cancellable: (nullable): optional #GCancellable object,
1465 1466 1467
 *     %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call
 *     when the request is satisfied
1468
 * @user_data: (closure): the data to pass to callback function
1469
 *
1470 1471 1472 1473
 * Asynchronously gets the requested information about the filesystem
 * that the specified @file is on. The result is a #GFileInfo object
 * that contains key-value attributes (such as type or size for the
 * file).
1474
 *
1475 1476 1477 1478 1479 1480
 * For more details, see g_file_query_filesystem_info() which is the
 * synchronous version of this call.
 *
 * When the operation is finished, @callback will be called. You can
 * then call g_file_query_info_finish() to get the result of the
 * operation.
1481
 */
1482 1483 1484 1485 1486 1487 1488 1489 1490
void
g_file_query_filesystem_info_async (GFile               *file,
                                    const char          *attributes,
                                    int                  io_priority,
                                    GCancellable        *cancellable,
                                    GAsyncReadyCallback  callback,
                                    gpointer             user_data)
{
  GFileIface *iface;
1491

1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504
  g_return_if_fail (G_IS_FILE (file));

  iface = G_FILE_GET_IFACE (file);
  (* iface->query_filesystem_info_async) (file,
                                          attributes,
                                          io_priority,
                                          cancellable,
                                          callback,
                                          user_data);
}

/**
 * g_file_query_filesystem_info_finish:
1505 1506 1507 1508 1509 1510 1511 1512 1513
 * @file: input #GFile
 * @res: a #GAsyncResult
 * @error: a #GError
 *
 * Finishes an asynchronous filesystem info query.
 * See g_file_query_filesystem_info_async().
 *
 * Returns: (transfer full): #GFileInfo for given @file
 *     or %NULL on error.
1514
 *     Free the returned object with g_object_unref().
1515
 */
1516