X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gio%2Fgfile.c;h=3e2607c8dee2bfd12413dbdc4d61793e5cd4f946;hb=2a53b4d0e2c98a14aedf31e38f0ad1fb2e8fe26f;hp=568ed3532eef03b398e2485e4e87602e05812f7e;hpb=c4e9135352c9dc5cef4f6c51432cd4763f849bc4;p=platform%2Fupstream%2Fglib.git diff --git a/gio/gfile.c b/gio/gfile.c index 568ed35..3e2607c 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -15,9 +15,7 @@ * 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. + * Public License along with this library; if not, see . * * Author: Alexander Larsson */ @@ -78,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 @@ -133,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} * - * entity tag * 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 + * traditional mtime, and can be used to quickly determine if the file + * has been modified from the version on the file system. See the + * HTTP 1.1 + * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) * for HTTP Etag headers, which are a very similar concept. - * - **/ + */ static void g_file_real_query_info_async (GFile *file, const char *attributes, @@ -449,9 +444,9 @@ g_file_has_uri_scheme (GFile *file, * * Gets the URI scheme for a #GFile. * RFC 3986 decodes the scheme as: - * + * |[ * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * + * ]| * Common schemes include "file", "http", "ftp", etc. * * This call does no blocking I/O. @@ -491,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 * @@ -515,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) @@ -646,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 @@ -655,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, @@ -666,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; @@ -685,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) @@ -816,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 @@ -854,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, @@ -972,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 @@ -1210,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 @@ -1348,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 @@ -1471,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 @@ -1700,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 @@ -1728,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 @@ -1905,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 @@ -1960,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 @@ -2029,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 @@ -2101,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 @@ -2172,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 @@ -2251,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 @@ -2324,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 @@ -2399,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 @@ -2633,7 +2622,7 @@ build_attribute_list_for_copy (GFile *file, { gboolean ret = FALSE; GFileAttributeInfoList *attributes = NULL, *namespaces = NULL; - GString *s; + GString *s = NULL; gboolean first; int i; gboolean copy_all_attributes; @@ -3268,7 +3257,7 @@ file_copy_fallback (GFile *source, info, G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS, cancellable, - error); + NULL); } g_clear_object (&info); @@ -3405,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 @@ -3419,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. @@ -3569,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 @@ -3594,6 +3585,8 @@ g_file_move (GFile *source, g_propagate_error (error, my_error); return FALSE; } + else + g_clear_error (&my_error); } } @@ -3666,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 @@ -3916,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 @@ -4026,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 @@ -4145,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 @@ -4475,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 @@ -6462,6 +6450,15 @@ new_for_cmdline_arg (const gchar *arg, * This operation never fails, but the returned object might not * support any I/O operation if @arg points to a malformed path. * + * Note that on Windows, this function expects its argument to be in + * UTF-8 -- not the system code page. This means that you + * should not use this function with string from argv as it is passed + * to main(). g_win32_get_command_line() will return a UTF-8 version of + * the commandline. #GApplication also uses UTF-8 but + * g_application_command_line_create_file_for_arg() may be more useful + * for you there. It is also always possible to use this function with + * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME. + * * Returns: (transfer full): a new #GFile. * Free the returned object with g_object_unref(). */ @@ -7085,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 @@ -7290,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 @@ -7311,6 +7308,11 @@ replace_contents_open_callback (GObject *obj, * * If @make_backup is %TRUE, this function will attempt to * make a backup of @file. + * + * Note that no copy of @content will be made, so it must stay valid + * until @callback is called. See g_file_replace_contents_bytes_async() + * for a #GBytes version that will automatically hold a reference to the + * contents (without copying) for the duration of the call. */ void g_file_replace_contents_async (GFile *file, @@ -7335,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 @@ -7389,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 @@ -7515,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, @@ -7596,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 @@ -7643,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 @@ -7671,9 +7672,9 @@ g_file_measure_disk_usage_async (GFile *file, g_return_if_fail (G_IS_FILE (file)); g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable)); - return G_FILE_GET_IFACE (file)->measure_disk_usage_async (file, flags, io_priority, cancellable, - progress_callback, progress_data, - callback, user_data); + G_FILE_GET_IFACE (file)->measure_disk_usage_async (file, flags, io_priority, cancellable, + progress_callback, progress_data, + callback, user_data); } /** @@ -7973,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. *