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

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
/* 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 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, write to the
 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, MA 02111-1307, USA.
 *
 * Author: Alexander Larsson <alexl@redhat.com>
 */

25
#include "config.h"
26

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

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

42 43 44 45 46
#include <string.h>
#include <sys/types.h>
#ifdef HAVE_PWD_H
#include <pwd.h>
#endif
47

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

68

69 70 71
/**
 * SECTION:gfile
 * @short_description: File and Directory Handling
Matthias Clasen's avatar
Matthias Clasen committed
72
 * @include: gio/gio.h
73
 * @see_also: #GFileInfo, #GFileEnumerator
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
 *
 * #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:
 * <simplelist>
 * <member>g_file_new_for_path() if you have a path.</member>
 * <member>g_file_new_for_uri() if you have a URI.</member>
 * <member>g_file_new_for_commandline_arg() for a command line argument.</member>
 * <member>g_file_new_tmp() to create a temporary file from a template.</member>
 * <member>g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().</member>
 * </simplelist>
 *
 * 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
103 104
 * files.
 *
105 106 107 108 109 110
 * 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
111
 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
112 113 114 115 116 117 118 119 120 121 122
 * 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
123
 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
124 125 126 127 128 129 130 131 132 133
 * 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.
134 135 136 137
 *
 * Some #GFile operations do not have synchronous analogs, as they may
 * take a very long time to finish, and blocking may leave an application
 * unusable. Notable cases include:
138 139 140 141 142 143
 * <simplelist>
 * <member>g_file_mount_mountable() to mount a mountable file.</member>
 * <member>g_file_unmount_mountable_with_operation() to unmount a mountable file.</member>
 * <member>g_file_eject_mountable_with_operation() to eject a mountable file.</member>
 * </simplelist>
 *
Matthias Clasen's avatar
Matthias Clasen committed
144
 * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
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
Matthias Clasen's avatar
Matthias Clasen committed
147
 * traditional mtime, and can be used to quickly determine if the file has
148
 * been modified from the version on the file system. See the HTTP 1.1
Matthias Clasen's avatar
Matthias Clasen committed
149
 * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink>
Matthias Clasen's avatar
Matthias Clasen committed
150 151
 * for HTTP Etag headers, which are a very similar concept.
 * </para>
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 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263
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);
264
static gboolean           g_file_real_set_attributes_from_info    (GFile                  *file,
265 266 267 268
                                                                   GFileInfo              *info,
                                                                   GFileQueryInfoFlags     flags,
                                                                   GCancellable           *cancellable,
                                                                   GError                **error);
269
static void               g_file_real_set_display_name_async      (GFile                  *file,
270 271 272 273 274
                                                                   const char             *display_name,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
275
static GFile *            g_file_real_set_display_name_finish     (GFile                  *file,
276 277
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
278
static void               g_file_real_set_attributes_async        (GFile                  *file,
279 280 281 282 283 284
                                                                   GFileInfo              *info,
                                                                   GFileQueryInfoFlags     flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
285
static gboolean           g_file_real_set_attributes_finish       (GFile                  *file,
286 287 288
                                                                   GAsyncResult           *res,
                                                                   GFileInfo             **info,
                                                                   GError                **error);
289
static void               g_file_real_find_enclosing_mount_async  (GFile                  *file,
290 291 292 293
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
294
static GMount *           g_file_real_find_enclosing_mount_finish (GFile                  *file,
295 296
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
297
static void               g_file_real_copy_async                  (GFile                  *source,
298 299 300 301 302 303 304 305
                                                                   GFile                  *destination,
                                                                   GFileCopyFlags          flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GFileProgressCallback   progress_callback,
                                                                   gpointer                progress_callback_data,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
306
static gboolean           g_file_real_copy_finish                 (GFile                  *file,
307 308
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
309

310 311
typedef GFileIface GFileInterface;
G_DEFINE_INTERFACE (GFile, g_file, G_TYPE_OBJECT)
312 313

static void
314
g_file_default_init (GFileIface *iface)
315 316 317 318 319 320 321
{
  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;
322 323
  iface->query_filesystem_info_async = g_file_real_query_filesystem_info_async;
  iface->query_filesystem_info_finish = g_file_real_query_filesystem_info_finish;
324 325 326 327 328 329 330 331 332 333
  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;
334 335
  iface->delete_file_async = g_file_real_delete_async;
  iface->delete_file_finish = g_file_real_delete_finish;
336 337
  iface->trash_async = g_file_real_trash_async;
  iface->trash_finish = g_file_real_trash_finish;
338 339 340 341 342 343
  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;
344 345
  iface->find_enclosing_mount_async = g_file_real_find_enclosing_mount_async;
  iface->find_enclosing_mount_finish = g_file_real_find_enclosing_mount_finish;
346
  iface->set_attributes_from_info = g_file_real_set_attributes_from_info;
347 348
  iface->copy_async = g_file_real_copy_async;
  iface->copy_finish = g_file_real_copy_finish;
349 350 351 352 353
}


/**
 * g_file_is_native:
354
 * @file: input #GFile
355
 *
356
 * Checks to see if a file is native to the platform.
357
 *
358 359 360 361
 * A native file s 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.
 *
362 363 364
 * 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.
365
 *
366 367 368 369
 * This call does no blocking I/O.
 *
 * Returns: %TRUE if @file is native
 */
370 371 372 373 374 375 376 377 378 379 380 381 382 383
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);
}


/**
384 385 386
 * g_file_has_uri_scheme:
 * @file: input #GFile
 * @uri_scheme: a string containing a URI scheme
387
 *
388 389
 * Checks to see if a #GFile has a given URI scheme.
 *
390 391
 * This call does no blocking I/O.
 *
392
 * Returns: %TRUE if #GFile's backend supports the
Matthias Clasen's avatar
Matthias Clasen committed
393 394
 *     given URI scheme, %FALSE if URI scheme is %NULL,
 *     not supported, or #GFile is invalid.
395
 */
396
gboolean
Matthias Clasen's avatar
Matthias Clasen committed
397
g_file_has_uri_scheme (GFile      *file,
398
                       const char *uri_scheme)
399 400
{
  GFileIface *iface;
401

402 403 404 405 406 407 408 409 410 411 412
  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:
413
 * @file: input #GFile
414
 *
415
 * Gets the URI scheme for a #GFile.
416
 * RFC 3986 decodes the scheme as:
417
 * <programlisting>
418
 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
419
 * </programlisting>
420
 * Common schemes include "file", "http", "ftp", etc.
421
 *
422 423 424 425
 * 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()
426
 *     when no longer needed.
427
 */
428 429 430 431 432 433 434 435 436 437 438 439 440 441 442
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:
443
 * @file: input #GFile
444
 *
445
 * Gets the base name (the last component of the path) for a given #GFile.
446
 *
447
 * If called for the top level of a system (such as the filesystem root
448
 * or a uri like sftp://host/) it will return a single directory separator
449
 * (and on Windows, possibly a drive letter).
450
 *
451
 * The base name is a byte string (not UTF-8). It has no defined encoding
452 453 454 455
 * 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().
456 457 458 459 460
 *
 * This call does no blocking I/O.
 *
 * Returns: string containing the #GFile's base name, or %NULL
 *     if given #GFile is invalid. The returned string should be
461
 *     freed with g_free() when no longer needed.
462
 */
463 464 465 466
char *
g_file_get_basename (GFile *file)
{
  GFileIface *iface;
467

468 469 470 471 472 473 474 475 476
  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:
477
 * @file: input #GFile
478
 *
479
 * Gets the local pathname for #GFile, if one exists.
480
 *
481 482 483 484
 * This call does no blocking I/O.
 *
 * Returns: string containing the #GFile's path, or %NULL if
 *     no such path exists. The returned string should be
485
 *     freed with g_free() when no longer needed.
486
 */
487 488 489 490 491 492 493 494 495 496 497 498 499 500
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);
}

/**
 * g_file_get_uri:
501
 * @file: input #GFile
502
 *
503
 * Gets the URI for the @file.
504
 *
505 506
 * This call does no blocking I/O.
 *
507
 * Returns: a string containing the #GFile's URI.
508 509 510
 *     The returned string should be freed with g_free()
 *     when no longer needed.
 */
511 512 513 514
char *
g_file_get_uri (GFile *file)
{
  GFileIface *iface;
515

516 517 518 519 520 521 522 523
  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
524
 * g_file_get_parse_name:
525
 * @file: input #GFile
526
 *
527 528 529 530 531 532
 * 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
533 534
 * full-pathname kind of string in a user interface,
 * like in a location entry.
535
 *
536
 * For local files with names that can safely be converted
537 538
 * to UTF-8 the pathname is used, otherwise the IRI is used
 * (a form of URI that allows UTF-8 characters unescaped).
539
 *
540 541 542 543 544 545
 * 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.
 */
546 547 548 549
char *
g_file_get_parse_name (GFile *file)
{
  GFileIface *iface;
550

551 552 553 554 555 556 557 558 559
  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:
560
 * @file: input #GFile
561
 *
562 563 564
 * 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.
565
 *
566 567 568 569 570
 * This call does no blocking I/O.
 *
 * Returns: (transfer full): a new #GFile that is a duplicate
 *     of the given #GFile.
 */
571 572 573 574
GFile *
g_file_dup (GFile *file)
{
  GFileIface *iface;
575

576 577 578 579 580 581 582 583 584
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

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

/**
 * g_file_hash:
585
 * @file: (type GFile): #gconstpointer to a #GFile
586
 *
587
 * Creates a hash value for a #GFile.
588
 *
589
 * This call does no blocking I/O.
590 591
 *
 * Virtual: hash
592 593 594
 * 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
595
 *     add to a #GHashTable or similar data structure.
596
 */
597 598 599 600
guint
g_file_hash (gconstpointer file)
{
  GFileIface *iface;
601

602 603 604 605 606 607 608 609 610
  g_return_val_if_fail (G_IS_FILE (file), 0);

  iface = G_FILE_GET_IFACE (file);

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

/**
 * g_file_equal:
611 612 613 614
 * @file1: the first #GFile
 * @file2: the second #GFile
 *
 * Checks equality of two given #GFiles.
615
 *
616
 * Note that two #GFiles that differ can still refer to the same
617 618
 * file on the filesystem due to various forms of filename
 * aliasing.
619
 *
620 621
 * This call does no blocking I/O.
 *
622
 * Returns: %TRUE if @file1 and @file2 are equal.
623
 *     %FALSE if either is not a #GFile.
624
 */
625 626
gboolean
g_file_equal (GFile *file1,
627
              GFile *file2)
628 629
{
  GFileIface *iface;
630

631 632
  g_return_val_if_fail (G_IS_FILE (file1), FALSE);
  g_return_val_if_fail (G_IS_FILE (file2), FALSE);
633

634 635 636 637
  if (G_TYPE_FROM_INSTANCE (file1) != G_TYPE_FROM_INSTANCE (file2))
    return FALSE;

  iface = G_FILE_GET_IFACE (file1);
638

639 640 641 642 643 644
  return (* iface->equal) (file1, file2);
}


/**
 * g_file_get_parent:
645
 * @file: input #GFile
646
 *
647 648
 * Gets the parent directory for the @file.
 * If the @file represents the root directory of the
649
 * file system, then %NULL will be returned.
650
 *
651 652 653 654 655 656
 * This call does no blocking I/O.
 *
 * Returns: (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().
 */
657 658 659 660
GFile *
g_file_get_parent (GFile *file)
{
  GFileIface *iface;
661

662 663 664 665 666 667 668
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

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

669 670 671
/**
 * g_file_has_parent:
 * @file: input #GFile
672
 * @parent: (allow-none): the parent to check for, or %NULL
673 674 675 676 677 678 679 680 681 682 683
 *
 * 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 a child of @parent.
 *
 * Returns: %TRUE if @file is a child of @parent (or any parent in the
 *          case that @parent is %NULL).
 *
 * Since: 2.24
684
 */
685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711
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;
}

712 713
/**
 * g_file_get_child:
714 715
 * @file: input #GFile
 * @name: string containing the child's basename
716
 *
717
 * Gets a child of @file with basename equal to @name.
718 719 720 721
 *
 * 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.
722
 *
723 724
 * This call does no blocking I/O.
 *
725
 * Returns: (transfer full): a #GFile to a child specified by @name.
Matthias Clasen's avatar
Matthias Clasen committed
726
 *     Free the returned object with g_object_unref().
727
 */
728
GFile *
Matthias Clasen's avatar
Matthias Clasen committed
729
g_file_get_child (GFile      *file,
730
                  const char *name)
731 732 733 734 735 736 737 738 739
{
  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:
740 741 742 743 744 745 746 747 748 749 750 751 752 753 754
 * @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
755
 *     Free the returned object with g_object_unref().
756
 */
757
GFile *
Matthias Clasen's avatar
Matthias Clasen committed
758
g_file_get_child_for_display_name (GFile      *file,
759 760
                                   const char *display_name,
                                   GError **error)
761 762
{
  GFileIface *iface;
763

764 765 766 767 768 769 770 771
  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);
}

772 773
/**
 * g_file_has_prefix:
774 775 776 777 778 779 780 781 782 783 784 785 786
 * @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.
 *
 * 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
787
 * of @prefix.
788
 *
789
 * Virtual: prefix_matches
790
 * Returns:  %TRUE if the @files's parent, grandparent, etc is @prefix,
Matthias Clasen's avatar
Matthias Clasen committed
791
 *     %FALSE otherwise.
792
 */
793 794
gboolean
g_file_has_prefix (GFile *file,
795
                   GFile *prefix)
796 797
{
  GFileIface *iface;
798

799 800
  g_return_val_if_fail (G_IS_FILE (file), FALSE);
  g_return_val_if_fail (G_IS_FILE (prefix), FALSE);
801

802
  if (G_TYPE_FROM_INSTANCE (file) != G_TYPE_FROM_INSTANCE (prefix))
803
    return FALSE;
804

805
  iface = G_FILE_GET_IFACE (file);
806

807 808 809
  /* The vtable function differs in arg order since
   * we're using the old contains_file call
   */
810
  return (* iface->prefix_matches) (prefix, file);
811 812 813 814
}

/**
 * g_file_get_relative_path:
815 816
 * @parent: input #GFile
 * @descendant: input #GFile
817
 *
818
 * Gets the path for @descendant relative to @parent.
819
 *
820 821 822 823 824 825 826
 * This call does no blocking I/O.
 *
 * Returns: 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.
 */
827 828
char *
g_file_get_relative_path (GFile *parent,
829
                          GFile *descendant)
830 831
{
  GFileIface *iface;
832

833 834 835 836 837
  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;
838

839 840 841 842 843 844 845
  iface = G_FILE_GET_IFACE (parent);

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

/**
 * g_file_resolve_relative_path:
846 847
 * @file: input #GFile
 * @relative_path: a given relative path string
848
 *
849 850
 * Resolves a relative path for @file to an absolute path.
 *
851 852 853 854
 * 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
855
 *     Free the returned object with g_object_unref().
856
 */
857
GFile *
Matthias Clasen's avatar
Matthias Clasen committed
858
g_file_resolve_relative_path (GFile      *file,
859
                              const char *relative_path)
860 861 862 863 864 865 866 867 868 869 870 871 872
{
  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:
873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
 * @cancellable: (allow-none): 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
901
 * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
902 903 904 905 906
 * 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().
 */
907
GFileEnumerator *
Matthias Clasen's avatar
Matthias Clasen committed
908
g_file_enumerate_children (GFile                *file,
909 910 911 912
                           const char           *attributes,
                           GFileQueryInfoFlags   flags,
                           GCancellable         *cancellable,
                           GError              **error)
913 914
{
  GFileIface *iface;
915

916 917 918 919
  g_return_val_if_fail (G_IS_FILE (file), NULL);

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

921 922 923 924
  iface = G_FILE_GET_IFACE (file);

  if (iface->enumerate_children == NULL)
    {
925 926 927
      g_set_error_literal (error, G_IO_ERROR,
                           G_IO_ERROR_NOT_SUPPORTED,
                           _("Operation not supported"));
928 929 930 931
      return NULL;
    }

  return (* iface->enumerate_children) (file, attributes, flags,
932
                                        cancellable, error);
933 934 935 936
}

/**
 * g_file_enumerate_children_async:
937 938 939 940 941 942 943 944
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
 * @io_priority: the <link linkend="io-priority">I/O priority</link>
 *     of the request
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call when the
945 946
 *     request is satisfied
 * @user_data: (closure): the data to pass to callback function
947
 *
948 949 950
 * 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.
951 952 953 954
 *
 * For more details, see g_file_enumerate_children() which is
 * the synchronous version of this call.
 *
955 956 957 958
 * 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.
 */
959
void
Matthias Clasen's avatar
Matthias Clasen committed
960
g_file_enumerate_children_async (GFile               *file,
961 962 963 964 965 966
                                 const char          *attributes,
                                 GFileQueryInfoFlags  flags,
                                 int                  io_priority,
                                 GCancellable        *cancellable,
                                 GAsyncReadyCallback  callback,
                                 gpointer             user_data)
967 968 969 970 971 972 973
{
  GFileIface *iface;

  g_return_if_fail (G_IS_FILE (file));

  iface = G_FILE_GET_IFACE (file);
  (* iface->enumerate_children_async) (file,
974 975 976 977 978 979
                                       attributes,
                                       flags,
                                       io_priority,
                                       cancellable,
                                       callback,
                                       user_data);
980 981 982 983
}

/**
 * g_file_enumerate_children_finish:
984 985 986 987
 * @file: input #GFile
 * @res: a #GAsyncResult
 * @error: a #GError
 *
Matthias Clasen's avatar
Matthias Clasen committed
988
 * Finishes an async enumerate children operation.
989
 * See g_file_enumerate_children_async().
Matthias Clasen's avatar
Matthias Clasen committed
990
 *
991 992
 * Returns: (transfer full): a #GFileEnumerator or %NULL
 *     if an error occurred.
993
 *     Free the returned object with g_object_unref().
994
 */
995
GFileEnumerator *
Matthias Clasen's avatar
Matthias Clasen committed
996
g_file_enumerate_children_finish (GFile         *file,
997 998
                                  GAsyncResult  *res,
                                  GError       **error)
999 1000
{
  GFileIface *iface;
1001

1002 1003 1004
  g_return_val_if_fail (G_IS_FILE (file), NULL);
  g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);

1005 1006
  if (g_async_result_legacy_propagate_error (res, error))
    return NULL;
1007

1008 1009 1010 1011
  iface = G_FILE_GET_IFACE (file);
  return (* iface->enumerate_children_finish) (file, res, error);
}

1012 1013
/**
 * g_file_query_exists:
1014 1015 1016
 * @file: input #GFile
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
1017 1018 1019 1020
 *
 * Utility function to check if a particular file exists. This is
 * implemented using g_file_query_info() and as such does blocking I/O.
 *
1021
 * Note that in many cases it is racy to first check for file existence
1022
 * and then execute something based on the outcome of that, because the
1023
 * file might have been created or removed in between the operations. The
1024 1025 1026
 * general approach to handling that is to not check, but just do the
 * operation and handle the errors as they come.
 *
1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042
 * 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).
1043 1044
 */
gboolean
1045 1046
g_file_query_exists (GFile        *file,
                     GCancellable *cancellable)
1047 1048
{
  GFileInfo *info;
1049

1050
  g_return_val_if_fail (G_IS_FILE(file), FALSE);
1051

1052
  info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_TYPE,
1053
                            G_FILE_QUERY_INFO_NONE, cancellable, NULL);
1054 1055 1056 1057 1058
  if (info != NULL)
    {
      g_object_unref (info);
      return TRUE;
    }
1059

1060 1061
  return FALSE;
}
1062

1063 1064
/**
 * g_file_query_file_type:
1065 1066 1067 1068
 * @file: input #GFile
 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
1069 1070 1071 1072
 *
 * Utility function to inspect the #GFileType of a file. This is
 * implemented using g_file_query_info() and as such does blocking I/O.
 *
1073 1074 1075 1076 1077
 * 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
1078 1079 1080 1081
 *
 * Since: 2.18
 */
GFileType
1082 1083 1084
g_file_query_file_type (GFile               *file,
                        GFileQueryInfoFlags  flags,
                        GCancellable        *cancellable)
1085 1086 1087
{
  GFileInfo *info;
  GFileType file_type;
1088

1089
  g_return_val_if_fail (G_IS_FILE(file), G_FILE_TYPE_UNKNOWN);
1090
  info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_TYPE, flags,
1091
                            cancellable, NULL);
1092 1093 1094 1095 1096 1097 1098
  if (info != NULL)
    {
      file_type = g_file_info_get_file_type (info);
      g_object_unref (info);
    }
  else
    file_type = G_FILE_TYPE_UNKNOWN;
1099

1100 1101 1102
  return file_type;
}

1103 1104
/**
 * g_file_query_info:
1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %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.
1131 1132
 *
 * For symlinks, normally the information about the target of the
1133 1134 1135 1136 1137
 * 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.
1138
 *
1139 1140 1141
 * 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.
1142
 *
1143 1144 1145
 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
 *     on error. Free the returned object with g_object_unref().
 */
1146
GFileInfo *
Matthias Clasen's avatar
Matthias Clasen committed
1147
g_file_query_info (GFile                *file,
1148 1149 1150 1151
                   const char           *attributes,
                   GFileQueryInfoFlags   flags,
                   GCancellable         *cancellable,
                   GError              **error)
1152 1153
{
  GFileIface *iface;
1154

1155 1156 1157 1158
  g_return_val_if_fail (G_IS_FILE (file), NULL);

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

1160 1161 1162 1163
  iface = G_FILE_GET_IFACE (file);

  if (iface->query_info == NULL)
    {
1164 1165 1166
      g_set_error_literal (error, G_IO_ERROR,
                           G_IO_ERROR_NOT_SUPPORTED,
                           _("Operation not supported"));
1167 1168
      return NULL;
    }
1169

1170 1171 1172 1173 1174
  return (* iface->query_info) (file, attributes, flags, cancellable, error);
}

/**
 * g_file_query_info_async:
1175 1176 1177 1178 1179 1180 1181 1182 1183
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
 * @io_priority: the <link linkend="io-priority">I/O priority</link>
 *     of the request
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call when the
 *     request is satisfied
1184
 * @user_data: (closure): the data to pass to callback function
1185
 *
1186 1187 1188 1189 1190 1191 1192 1193 1194 1195
 * 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.
 */
1196
void
Matthias Clasen's avatar
Matthias Clasen committed
1197
g_file_query_info_async (GFile               *file,
1198 1199 1200 1201 1202 1203
                         const char          *attributes,
                         GFileQueryInfoFlags  flags,
                         int                  io_priority,
                         GCancellable        *cancellable,
                         GAsyncReadyCallback  callback,
                         gpointer             user_data)
1204 1205
{
  GFileIface *iface;
1206

1207 1208 1209 1210
  g_return_if_fail (G_IS_FILE (file));

  iface = G_FILE_GET_IFACE (file);
  (* iface->query_info_async) (file,
1211 1212 1213 1214 1215 1216
                               attributes,
                               flags,
                               io_priority,
                               cancellable,
                               callback,
                               user_data);
1217 1218 1219 1220
}

/**
 * g_file_query_info_finish:
1221 1222 1223 1224 1225
 * @file: input #GFile
 * @res: a #GAsyncResult
 * @error: a #GError
 *
 * Finishes an asynchronous file info query.
1226
 * See g_file_query_info_async().
1227 1228 1229 1230 1231
 *
 * Returns: (transfer full): #GFileInfo for given @file
 *     or %NULL on error. Free the returned object with
 *     g_object_unref().
 */
1232
GFileInfo *
Matthias Clasen's avatar
Matthias Clasen committed
1233
g_file_query_info_finish (GFile         *file,
1234 1235
                          GAsyncResult  *res,
                          GError       **error)
1236 1237 1238 1239 1240 1241
{
  GFileIface *iface;

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

1242 1243
  if (g_async_result_legacy_propagate_error (res, error))
    return NULL;
1244

1245 1246 1247 1248 1249 1250
  iface = G_FILE_GET_IFACE (file);
  return (* iface->query_info_finish) (file, res, error);
}

/**
 * g_file_query_filesystem_info:
1251 1252 1253 1254 1255 1256
 * @file: input #GFile
 * @attributes:  an attribute query string
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @error: a #GError
 *
1257 1258
 * Similar to g_file_query_info(), but obtains information
 * about the filesystem the @file is on, rather than the file itself.
1259
 * For instance the amount of space available and the type of
1260 1261
 * the filesystem.
 *
1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281
 * 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.
1282
 *
1283
 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
1284
 *     Free the returned object with g_object_unref().
1285
 */
1286
GFileInfo *
Matthias Clasen's avatar
Matthias Clasen committed
1287
g_file_query_filesystem_info (GFile         *file,
1288 1289 1290
                              const char    *attributes,
                              GCancellable  *cancellable,
                              GError       **error)
1291 1292
{
  GFileIface *iface;
1293

1294 1295 1296 1297
  g_return_val_if_fail (G_IS_FILE (file), NULL);

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

1299 1300 1301 1302
  iface = G_FILE_GET_IFACE (file);

  if (iface->query_filesystem_info == NULL)
    {
1303 1304 1305
      g_set_error_literal (error, G_IO_ERROR,
                           G_IO_ERROR_NOT_SUPPORTED,
                           _("Operation not supported"));
1306 1307
      return NULL;
    }
1308

1309 1310 1311
  return (* iface->query_filesystem_info) (file, attributes, cancellable, error);
}

1312 1313
/**
 * g_file_query_filesystem_info_async:
1314 1315 1316 1317 1318 1319 1320 1321
 * @file: input #GFile
 * @attributes: an attribute query string
 * @io_priority: the <link linkend="io-priority">I/O priority</link>
 *     of the request
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call
 *     when the request is satisfied
1322
 * @user_data: (closure): the data to pass to callback function
1323
 *
1324 1325 1326 1327
 * 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).
1328
 *
1329 1330 1331 1332 1333 1334
 * 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.
1335
 */
1336 1337 1338 1339 1340 1341 1342 1343 1344
void
g_file_query_filesystem_info_async (GFile               *file,
                                    const char          *attributes,
                                    int                  io_priority,
                                    GCancellable        *cancellable,
                                    GAsyncReadyCallback  callback,
                                    gpointer             user_data)
{
  GFileIface *iface;
1345

1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358
  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:
1359 1360 1361 1362 1363 1364 1365 1366 1367
 * @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.
1368
 *     Free the returned object with g_object_unref().
1369
 */
1370 1371 1372 1373 1374 1375 1376 1377 1378 1379
GFileInfo *
g_file_query_filesystem_info_finish (GFile         *file,
                                     GAsyncResult  *res,
                                     GError       **error)
{
  GFileIface *iface;

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

1380 1381
  if (g_async_result_legacy_propagate_error (res, error))
    return NULL;
1382

1383 1384 1385 1386
  iface = G_FILE_GET_IFACE (file);
  return (* iface->query_filesystem_info_finish) (file, res, error);
}

1387
/**
1388
 * g_file_find_enclosing_mount:
1389 1390 1391 1392
 * @file: input #GFile
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @error: a #GError
1393
 *
1394 1395 1396 1397 1398
 * Gets a #GMount for the #GFile.
 *
 * If the #GFileIface for @file does not have a mount (e.g.
 * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
 * and %NULL will be returned.
1399
 *
1400 1401
 * If @cancellable is not %NULL, then the operation can be cancelled by
 * triggering the cancellable object from another thread. If the operation
1402 1403 1404 1405
 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
 *
 * Returns: (transfer full): a #GMount where the @file is located
 *     or %NULL on error.
1406
 *     Free the returned object with g_object_unref().
1407
 */
1408 1409
GMount *
g_file_find_enclosing_mount (GFile         *file,
1410 1411
                             GCancellable  *cancellable,
                             GError       **error)
1412 1413 1414 1415
{
  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);
1416

1417 1418 1419 1420
  if (g_cancellable_set_error_if_cancelled (cancellable, error))
    return NULL;

  iface = G_FILE_GET_IFACE (file);
1421
  if (iface->find_enclosing_mount == NULL)
1422
    {
1423

1424
      g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND,
1425 1426 1427 1428 1429
                           /* Translators: This is an error message when
                            * trying to find the enclosing (user visible)
                            * mount of a file, but none exists.
                            */
                           _("Containing mount does not exist"));
1430 1431
      return NULL;
    }
1432

1433
  return (* iface->find_enclosing_mount) (file, cancellable, error);
1434
}
1435

Matthias Clasen's avatar
Matthias Clasen committed
1436 1437 1438
/**
 * g_file_find_enclosing_mount_async:
 * @file: a #GFile
1439 1440 1441 1442 1443 1444
 * @io_priority: the <link linkend="io-priority">I/O priority</link>
 *     of the request
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call
 *     when the request is satisfied
1445
 * @user_data: (closure): the data to pass to callback function
Matthias Clasen's avatar
Matthias Clasen committed
1446 1447 1448 1449 1450 1451
 *
 * Asynchronously gets the mount for the file.
 *
 * For more details, see g_file_find_enclosing_mount() which is
 * the synchronous version of this call.
 *
1452 1453 1454
 * When the operation is finished, @callback will be called.
 * You can then call g_file_find_enclosing_mount_finish() to
 * get the result of the operation.
Matthias Clasen's avatar
Matthias Clasen committed
1455
 */
1456 1457
void
g_file_find_enclosing_mount_async (GFile              *file,
1458 1459 1460 1461
                                   int                   io_priority,
                                   GCancellable         *cancellable,
                                   GAsyncReadyCallback   callback,
                                   gpointer              user_data)
1462 1463 1464 1465 1466 1467 1468
{
  GFileIface *iface;

  g_return_if_fail (G_IS_FILE (file));

  iface = G_FILE_GET_IFACE (file);
  (* iface->find_enclosing_mount_async) (file,
1469 1470 1471 1472
                                         io_priority,
                                         cancellable,
                                         callback,
                                         user_data);
1473 1474
}

Matthias Clasen's avatar
Matthias Clasen committed
1475 1476 1477 1478 1479
/**
 * g_file_find_enclosing_mount_finish:
 * @file: a #GFile
 * @res: a #GAsyncResult
 * @error: a #GError
1480 1481
 *
 * Finishes an asynchronous find mount request.
Matthias Clasen's avatar
Matthias Clasen committed
1482
 * See g_file_find_enclosing_mount_async().
1483
 *
1484
 * Returns: (transfer full): #GMount for given @file or %NULL on error.
1485
 *     Free the returned object with g_object_unref().
1486
 */
1487
GMount *
Matthias Clasen's avatar
Matthias Clasen committed
1488
g_file_find_enclosing_mount_finish (GFile         *file,
1489 1490
                                    GAsyncResult  *res,
                                    GError       **error)
1491 1492
{
  GFileIface *iface;
1493

1494 1495 1496
  g_return_val_if_fail (G_IS_FILE (file), NULL);
  g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);

1497 1498
  if (g_async_result_legacy_propagate_error (res, error))
    return NULL;
1499

1500 1501 1502 1503 1504
  iface = G_FILE_GET_IFACE (file);
  return (* iface->find_enclosing_mount_finish) (file, res, error);
}


1505 1506
/**
 * g_file_read:
1507
 * @file: #GFile to read