X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gio%2Fgfile.c;h=3e2607c8dee2bfd12413dbdc4d61793e5cd4f946;hb=2a53b4d0e2c98a14aedf31e38f0ad1fb2e8fe26f;hp=c24bf3854556b6583dc19494d57650ff1ad2644b;hpb=8bdc089ca46f20d08487d5c1b41610459a9b4b51;p=platform%2Fupstream%2Fglib.git
diff --git a/gio/gfile.c b/gio/gfile.c
index c24bf38..3e2607c 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -76,13 +76,11 @@
* (see #GInputStream and #GOutputStream).
*
* To construct a #GFile, you can use:
- *
- * g_file_new_for_path() if you have a path.
- * g_file_new_for_uri() if you have a URI.
- * g_file_new_for_commandline_arg() for a command line argument.
- * g_file_new_tmp() to create a temporary file from a template.
- * g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
- *
+ * - g_file_new_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().
*
* 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
@@ -131,21 +129,20 @@
* 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:
- *
- * 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.
- *
+ * - g_file_mount_mountable() to mount a mountable file.
+ * - g_file_unmount_mountable_with_operation() to unmount a mountable file.
+ * - g_file_eject_mountable_with_operation() to eject a mountable file.
+ *
+ * ## Entity Tags # {#gfile-etag}
*
- *
* One notable feature of #GFiles are entity tags, or "etags" for
* short. Entity tags are somewhat like a more abstract version of the
* traditional mtime, and can be used to quickly determine if the file
* has been modified from the version on the file system. See the
- * HTTP 1.1 specification
+ * HTTP 1.1
+ * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
* for HTTP Etag headers, which are a very similar concept.
- *
- **/
+ */
static void g_file_real_query_info_async (GFile *file,
const char *attributes,
@@ -489,8 +486,8 @@ g_file_get_uri_scheme (GFile *file)
*
* 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
+ * Returns: (nullable): string containing the #GFile's base name, or
+ * %NULL if given #GFile is invalid. The returned string should be
* freed with g_free() when no longer needed.
*/
char *
@@ -513,9 +510,9 @@ g_file_get_basename (GFile *file)
*
* 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
- * freed with g_free() when no longer needed.
+ * Returns: (nullable): string containing the #GFile's path, or %NULL
+ * if no such path exists. The returned string should be freed
+ * with g_free() when no longer needed.
*/
char *
g_file_get_path (GFile *file)
@@ -644,7 +641,7 @@ g_file_hash (gconstpointer file)
* @file1: the first #GFile
* @file2: the second #GFile
*
- * Checks equality of two given #GFiles.
+ * Checks if the two given #GFiles refer to the same file.
*
* Note that two #GFiles that differ can still refer to the same
* file on the filesystem due to various forms of filename
@@ -653,7 +650,6 @@ g_file_hash (gconstpointer file)
* This call does no blocking I/O.
*
* Returns: %TRUE if @file1 and @file2 are equal.
- * %FALSE if either is not a #GFile.
*/
gboolean
g_file_equal (GFile *file1,
@@ -664,6 +660,9 @@ g_file_equal (GFile *file1,
g_return_val_if_fail (G_IS_FILE (file1), FALSE);
g_return_val_if_fail (G_IS_FILE (file2), FALSE);
+ if (file1 == file2)
+ return TRUE;
+
if (G_TYPE_FROM_INSTANCE (file1) != G_TYPE_FROM_INSTANCE (file2))
return FALSE;
@@ -683,9 +682,9 @@ g_file_equal (GFile *file1,
*
* 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().
+ * Returns: (nullable) (transfer full): a #GFile structure to the
+ * parent of the given #GFile or %NULL if there is no parent. Free
+ * the returned object with g_object_unref().
*/
GFile *
g_file_get_parent (GFile *file)
@@ -814,6 +813,9 @@ g_file_get_child_for_display_name (GFile *file,
* so a path like /foo is not considered a prefix of /foobar, only
* of /foo/bar.
*
+ * A #GFile is not a prefix of itself. If you want to check for
+ * equality, use g_file_equal().
+ *
* This call does no I/O, as it works purely on names. As such it can
* sometimes return %FALSE even if @file is inside a @prefix (from a
* filesystem point of view), because the prefix of @file is an alias
@@ -852,10 +854,10 @@ g_file_has_prefix (GFile *file,
*
* 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.
+ * Returns: (nullable): string with the relative path from @descendant
+ * to @parent, or %NULL if @descendant doesn't have @parent as
+ * prefix. The returned string should be freed with g_free() when
+ * no longer needed.
*/
char *
g_file_get_relative_path (GFile *parent,
@@ -970,8 +972,7 @@ g_file_enumerate_children (GFile *file,
* @file: input #GFile
* @attributes: an attribute query string
* @flags: a set of #GFileQueryInfoFlags
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call when the
@@ -1208,8 +1209,7 @@ g_file_query_info (GFile *file,
* @file: input #GFile
* @attributes: an attribute query string
* @flags: a set of #GFileQueryInfoFlags
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call when the
@@ -1346,8 +1346,7 @@ g_file_query_filesystem_info (GFile *file,
* g_file_query_filesystem_info_async:
* @file: input #GFile
* @attributes: an attribute query string
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call
@@ -1469,8 +1468,7 @@ g_file_find_enclosing_mount (GFile *file,
/**
* g_file_find_enclosing_mount_async:
* @file: a #GFile
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call
@@ -1698,7 +1696,7 @@ g_file_create (GFile *file,
/**
* g_file_replace:
* @file: input #GFile
- * @etag: (allow-none): an optional entity tag
+ * @etag: (allow-none): an optional [entity tag][gfile-etag]
* for the current #GFile, or #NULL to ignore
* @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags
@@ -1726,14 +1724,14 @@ g_file_create (GFile *file,
* operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
* returned.
*
- * If you pass in a non-%NULL @etag value, then this value is
- * compared to the current entity tag of the file, and if they differ
- * an %G_IO_ERROR_WRONG_ETAG error is returned. This generally means
- * that the file has been changed since you last read it. You can get
- * the new etag from g_file_output_stream_get_etag() after you've
- * finished writing and closed the #GFileOutputStream. When you load
- * a new file you can use g_file_input_stream_query_info() to get
- * the etag of the file.
+ * If you pass in a non-%NULL @etag value and @file already exists, then
+ * this value is compared to the current entity tag of the file, and if
+ * they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This
+ * generally means that the file has been changed since you last read
+ * it. You can get the new etag from g_file_output_stream_get_etag()
+ * after you've finished writing and closed the #GFileOutputStream. When
+ * you load a new file you can use g_file_input_stream_query_info() to
+ * get the etag of the file.
*
* If @make_backup is %TRUE, this function will attempt to make a
* backup of the current file before overwriting it. If this fails
@@ -1903,7 +1901,7 @@ g_file_create_readwrite (GFile *file,
/**
* g_file_replace_readwrite:
* @file: a #GFile
- * @etag: (allow-none): an optional entity tag
+ * @etag: (allow-none): an optional [entity tag][gfile-etag]
* for the current #GFile, or #NULL to ignore
* @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags
@@ -1958,8 +1956,7 @@ g_file_replace_readwrite (GFile *file,
/**
* g_file_read_async:
* @file: input #GFile
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call
@@ -2027,8 +2024,7 @@ g_file_read_finish (GFile *file,
* g_file_append_to_async:
* @file: input #GFile
* @flags: a set of #GFileCreateFlags
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call
@@ -2099,8 +2095,7 @@ g_file_append_to_finish (GFile *file,
* g_file_create_async:
* @file: input #GFile
* @flags: a set of #GFileCreateFlags
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call
@@ -2170,12 +2165,11 @@ g_file_create_finish (GFile *file,
/**
* g_file_replace_async:
* @file: input #GFile
- * @etag: (allow-none): an entity tag
- * for the current #GFile, or NULL to ignore
+ * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
+ * or %NULL to ignore
* @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call
@@ -2249,8 +2243,7 @@ g_file_replace_finish (GFile *file,
/**
* g_file_open_readwrite_async
* @file: input #GFile
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call
@@ -2322,8 +2315,7 @@ g_file_open_readwrite_finish (GFile *file,
* g_file_create_readwrite_async:
* @file: input #GFile
* @flags: a set of #GFileCreateFlags
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call
@@ -2397,12 +2389,11 @@ g_file_create_readwrite_finish (GFile *file,
/**
* g_file_replace_readwrite_async:
* @file: input #GFile
- * @etag: (allow-none): an entity tag
- * for the current #GFile, or NULL to ignore
+ * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
+ * or %NULL to ignore
* @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call
@@ -3266,7 +3257,7 @@ file_copy_fallback (GFile *source,
info,
G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
cancellable,
- error);
+ NULL);
}
g_clear_object (&info);
@@ -3403,8 +3394,7 @@ g_file_copy (GFile *source,
* @source: input #GFile
* @destination: destination #GFile
* @flags: set of #GFileCopyFlags
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @progress_callback: (allow-none): function to callback with progress
@@ -3417,8 +3407,9 @@ g_file_copy (GFile *source,
* asynchronously. For details of the behaviour, see g_file_copy().
*
* If @progress_callback is not %NULL, then that function that will be called
- * just like in g_file_copy(), however the callback will run in the main loop,
- * not in the thread that is doing the I/O operation.
+ * just like in g_file_copy(). The callback will run in the default main context
+ * of the thread calling g_file_copy_async() â the same context as @callback is
+ * run in.
*
* When the operation is finished, @callback will be called. You can then call
* g_file_copy_finish() to get the result of the operation.
@@ -3567,6 +3558,8 @@ g_file_move (GFile *source,
g_propagate_error (error, my_error);
return FALSE;
}
+ else
+ g_clear_error (&my_error);
}
/* If the types are different, and the destination method failed
@@ -3592,6 +3585,8 @@ g_file_move (GFile *source,
g_propagate_error (error, my_error);
return FALSE;
}
+ else
+ g_clear_error (&my_error);
}
}
@@ -3664,8 +3659,7 @@ g_file_make_directory (GFile *file,
/**
* g_file_make_directory_async:
* @file: input #GFile
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: a #GAsyncReadyCallback to call
@@ -3914,8 +3908,7 @@ g_file_delete (GFile *file,
/**
* g_file_delete_async:
* @file: input #GFile
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: a #GAsyncReadyCallback to call
@@ -4024,8 +4017,7 @@ g_file_trash (GFile *file,
/**
* g_file_trash_async:
* @file: input #GFile
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: a #GAsyncReadyCallback to call
@@ -4143,8 +4135,7 @@ g_file_set_display_name (GFile *file,
* g_file_set_display_name_async:
* @file: input #GFile
* @display_name: a string
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback to call
@@ -4473,8 +4464,7 @@ g_file_real_set_attributes_from_info (GFile *file,
* @file: input #GFile
* @info: a #GFileInfo
* @flags: a #GFileQueryInfoFlags
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object,
* %NULL to ignore
* @callback: (scope async): a #GAsyncReadyCallback
@@ -7092,11 +7082,11 @@ g_file_load_contents_finish (GFile *file,
* @file: input #GFile
* @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
* @length: the length of @contents in bytes
- * @etag: (allow-none): the old entity tag
- * for the document, or %NULL
+ * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document,
+ * or %NULL
* @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags
- * @new_etag: (allow-none) (out): a location to a new entity tag
+ * @new_etag: (allow-none) (out): a location to a new [entity tag][gfile-etag]
* for the document. This should be freed with g_free() when no longer
* needed, or %NULL
* @cancellable: optional #GCancellable object, %NULL to ignore
@@ -7297,7 +7287,7 @@ replace_contents_open_callback (GObject *obj,
* @file: input #GFile
* @contents: (element-type guint8) (array length=length): string of contents to replace the file with
* @length: the length of @contents in bytes
- * @etag: (allow-none): a new entity tag for the @file, or %NULL
+ * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
* @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags
* @cancellable: optional #GCancellable object, %NULL to ignore
@@ -7347,7 +7337,7 @@ g_file_replace_contents_async (GFile *file,
* g_file_replace_contents_bytes_async:
* @file: input #GFile
* @contents: a #GBytes
- * @etag: (allow-none): a new entity tag for the @file, or %NULL
+ * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
* @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags
* @cancellable: optional #GCancellable object, %NULL to ignore
@@ -7401,7 +7391,7 @@ g_file_replace_contents_bytes_async (GFile *file,
* g_file_replace_contents_finish:
* @file: input #GFile
* @res: a #GAsyncResult
- * @new_etag: (out) (allow-none): a location of a new entity tag
+ * @new_etag: (out) (allow-none): a location of a new [entity tag][gfile-etag]
* for the document. This should be freed with g_free() when it is no
* longer needed, or %NULL
* @error: a #GError, or %NULL
@@ -7527,7 +7517,7 @@ measure_disk_usage_thread (GTask *task,
{
MeasureTaskData *data = task_data;
GError *error = NULL;
- MeasureResult result;
+ MeasureResult result = { 0, };
if (g_file_measure_disk_usage (source_object, data->flags, cancellable,
data->progress_callback ? measure_disk_usage_progress : NULL, task,
@@ -7608,9 +7598,9 @@ g_file_real_measure_disk_usage_finish (GFile *file,
*
* Recursively measures the disk usage of @file.
*
- * This is essentially an analog of the 'du' command,
- * but it also reports the number of directories and non-directory files
- * encountered (including things like symbolic links).
+ * This is essentially an analog of the 'du' command, but it also
+ * reports the number of directories and non-directory files encountered
+ * (including things like symbolic links).
*
* By default, errors are only reported against the toplevel file
* itself. Errors found while recursing are silently ignored, unless
@@ -7655,8 +7645,7 @@ g_file_measure_disk_usage (GFile *file,
* g_file_measure_disk_usage_async:
* @file: a #GFile
* @flags: #GFileMeasureFlags
- * @io_priority: the I/O priority
- * of the request
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable
* @progress_callback: (allow-none): a #GFileMeasureProgressCallback
* @progress_data: user_data for @progress_callback
@@ -7985,11 +7974,10 @@ g_file_poll_mountable_finish (GFile *file,
* g_file_supports_thread_contexts:
* @file: a #GFile
*
- * Checks if @file supports thread-default
- * contexts. If this returns %FALSE, you cannot perform
- * asynchronous operations on @file in a thread that has a
- * thread-default context.
+ * Checks if @file supports
+ * [thread-default contexts][g-main-context-push-thread-default-context].
+ * If this returns %FALSE, you cannot perform asynchronous operations on
+ * @file in a thread that has a thread-default context.
*
* Returns: Whether or not @file supports thread-default contexts.
*