File
#GFile is a high level abstraction for manipulating files on a virtual file system. #GFiles are lightweight, immutable objects that do no I/O upon creation. It is necessary to understand that #GFile objects do not represent files, merely an identifier for a file. All file content I/O is implemented as streaming operations (see #GInputStream and #GOutputStream).
To construct a #GFile, you can use:
g_file_new_for_path() if you have a path.
g_file_new_for_uri() if you have a URI.
g_file_new_for_commandline_arg() for a command line argument.
g_file_new_tmp() to create a temporary file from a template.
g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
g_file_new_build_filename() to create a file from path elements.
One way to think of a #GFile is as an abstraction of a pathname. For normal files the system pathname is what is stored internally, but as #GFiles are extensible it could also be something else that corresponds to a pathname in a userspace implementation of a filesystem.
#GFiles make up hierarchies of directories and files that correspond to the files on a filesystem. You can move through the file system with #GFile using g_file_get_parent() to get an identifier for the parent directory, g_file_get_child() to get a child within a directory, g_file_resolve_relative_path() to resolve a relative path between two #GFiles. There can be multiple hierarchies, so you may not end up at the same root if you repeatedly call g_file_get_parent() on two different files.
All #GFiles have a basename (get with g_file_get_basename()). These names are byte strings that are used to identify the file on the filesystem (relative to its parent directory) and there is no guarantees that they have any particular charset encoding or even make any sense at all. If you want to use filenames in a user interface you should use the display name that you can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). This is guaranteed to be in UTF-8 and can be used in a user interface. But always store the real basename or the #GFile to use to actually access the file, because there is no way to go from a display name to the actual name.
Using #GFile as an identifier has the same weaknesses as using a path in that there may be multiple aliases for the same file. For instance, hard or soft links may cause two different #GFiles to refer to the same file. Other possible causes for aliases are: case insensitive filesystems, short and long names on FAT/NTFS, or bind mounts in Linux. If you want to check if two #GFiles point to the same file you can query for the %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial canonicalization of pathnames passed in, so that trivial differences in the path string used at creation (duplicated slashes, slash at end of path, "." or ".." path segments, etc) does not create different #GFiles.
Many #GFile operations have both synchronous and asynchronous versions to suit your application. Asynchronous versions of synchronous functions simply have _async() appended to their function names. The asynchronous I/O functions call a #GAsyncReadyCallback which is then used to finalize the operation, producing a GAsyncResult which is then passed to the function's matching _finish() operation.
It is highly recommended to use asynchronous calls when running within a shared main loop, such as in the main thread of an application. This avoids I/O operations blocking other sources on the main loop from being dispatched. Synchronous I/O operations should be performed from worker threads. See the async-programming for more.
Some #GFile operations almost always take a noticeable amount of time, and so do not have synchronous analogs. Notable cases include:
g_file_mount_mountable() to mount a mountable file.
g_file_unmount_mountable_with_operation() to unmount a mountable file.
g_file_eject_mountable_with_operation() to eject a mountable file.
Entity Tags # {#gfile-etag}
One notable feature of #GFiles are entity tags, or "etags" for short. Entity tags are somewhat like a more abstract version of the traditional mtime, and can be used to quickly determine if the file has been modified from the version on the file system. See the HTTP 1.1 specification for HTTP Etag headers, which are a very similar concept.
Skipped during bindings generation
parameter
callback: AsyncReadyCallbackparameter
etag_out: etag_out: Out parameter is not supportedparameter
etag_out: etag_out: Out parameter is not supportedparameter
contents: contents: Out parameter is not supportedparameter
contents: contents: Out parameter is not supportedparameter
contents: contents: Out parameter is not supportedparameter
disk_usage: disk_usage: Out parameter is not supportedparameter
callback: AsyncReadyCallbackparameter
contents: guint8parameter
contents: guint8parameter
new_etag: new_etag: Out parameter is not supportedparameter
value_p: gpointerparameter
info: info: Out parameter is not supportedparameter
iostream: iostream: Out parameter is not supported
Functions
Gets an output stream for appending data to the file. If the file doesn't already exist it is created.
Asynchronously opens @file for appending.
Finishes an asynchronous file append operation started with g_file_append_to_async().
Prepares the file attribute query string for copying to @file.
Copies the file @source to the location specified by @destination. Can not handle recursive copies of directories.
Copies the file attributes from @source to @destination.
Finishes copying the file started with g_file_copy_async().
Creates a new file and returns an output stream for writing to it. The file must not already exist.
Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist.
Finishes an asynchronous file create operation started with g_file_create_async().
Creates a new file and returns a stream for reading and writing to it. The file must not already exist.
Asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist.
Finishes an asynchronous file create operation started with g_file_create_readwrite_async().
Deletes a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink().
Asynchronously delete a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink().
Finishes deleting a file started with g_file_delete_async().
Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called with
Finishes an asynchronous eject operation started by g_file_eject_mountable().
Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called with
Finishes an asynchronous eject operation started by g_file_eject_mountable_with_operation().
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.
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.
Finishes an async enumerate children operation. See g_file_enumerate_children_async().
Gets a #GMount for the #GFile.
Asynchronously gets the mount for the file.
Finishes an asynchronous find mount request. See g_file_find_enclosing_mount_async().
Gets the base name (the last component of the path) for a given #GFile.
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.
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().
Gets the path for @descendant relative to @parent.
Gets the URI scheme for a #GFile. RFC 3986 decodes the scheme as: |[ URI = scheme ":" hier-part "#" fragment ]| Common schemes include "file", "http", "ftp", etc.
Checks to see if a #GFile has a given URI scheme.
Asynchronously loads the contents of @file as #GBytes.
Starts an asynchronous load of the @file's contents.
Creates a directory. Note that this will only create a child directory of the immediate parent directory of the path or URI given by the #GFile. To recursively create directories, see g_file_make_directory_with_parents(). This function will fail if the parent directory does not exist, setting
Asynchronously creates a directory.
Finishes an asynchronous directory creation, started with g_file_make_directory_async().
Creates a directory and any parent directories that may not exist similar to 'mkdir -p'. If the file system does not support creating directories, this function will fail, setting @error to %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists, this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike the similar g_mkdir_with_parents().
Creates a symbolic link named @file which contains the string
Obtains a file or directory monitor for the given file, depending on the type of the file.
Obtains a directory monitor for the given file. This may fail if directory monitoring is not supported.
Obtains a file monitor for the given file. If no file notification mechanism exists, then regular polling of the file is used.
Starts a @mount_operation, mounting the volume that contains the file @location.
Finishes a mount operation started by g_file_mount_enclosing_volume().
Mounts a file of type G_FILE_TYPE_MOUNTABLE. Using @mount_operation, you can request callbacks when, for instance, passwords are needed during authentication.
Finishes a mount operation. See g_file_mount_mountable() for details.
Tries to move the file or directory @source to the location specified by @destination. If native move operations are supported then this is used, otherwise a copy + delete fallback is used. The native implementation may support moving directories (for instance on moves inside the same filesystem), but the fallback code does not.
Finishes an asynchronous file movement, started with g_file_move_async().
Opens an existing file for reading and writing. The result is a #GFileIOStream that can be used to read and write the contents of the file.
Asynchronously opens @file for reading and writing.
Finishes an asynchronous file read operation started with g_file_open_readwrite_async().
Polls a file of type %G_FILE_TYPE_MOUNTABLE.
Finishes a poll operation. See g_file_poll_mountable() for details.
Returns the #GAppInfo that is registered as the default application to handle the file specified by @file.
Async version of g_file_query_default_handler().
Finishes a g_file_query_default_handler_async() operation.
Utility function to check if a particular file exists. This is implemented using g_file_query_info() and as such does blocking I/O.
Similar to g_file_query_info(), but obtains information about the filesystem the @file is on, rather than the file itself. For instance the amount of space available and the type of the filesystem.
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).
Finishes an asynchronous filesystem info query. See g_file_query_filesystem_info_async().
Utility function to inspect the #GFileType of a file. This is implemented using g_file_query_info() and as such does blocking I/O.
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).
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).
Finishes an asynchronous file info query. See g_file_query_info_async().
Obtain the list of settable attributes for the file.
Obtain the list of attribute namespaces where new attributes can be created by a user. An example of this is extended attributes (in the "xattr" namespace).
Opens a file for reading. The result is a #GFileInputStream that can be used to read the contents of the file.
Asynchronously opens @file for reading.
Finishes an asynchronous file read operation started with g_file_read_async().
Returns an output stream for overwriting the file, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created.
Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first.
Same as g_file_replace_contents_async() but takes a #GBytes input instead. This function will keep a ref on @contents until the operation is done. Unlike g_file_replace_contents_async() this allows forgetting about the content without waiting for the callback.
Finishes an asynchronous file replace operation started with g_file_replace_async().
Returns an output stream for overwriting the file in readwrite mode, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created.
Asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first.
Finishes an asynchronous file replace operation started with g_file_replace_readwrite_async().
Resolves a relative path for @file to an absolute path.
Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. If @attribute is of a different type, this operation will fail, returning false.
Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. If @attribute is of a different type, this operation will fail.
Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. If @attribute is of a different type, this operation will fail.
Asynchronously sets the attributes of @file with @info.
Tries to set all attributes in the #GFileInfo on the target values, not stopping on the first error.
Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. If @attribute is of a different type, this operation will fail.
Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. If @attribute is of a different type, this operation will fail.
Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. If @attribute is of a different type, this operation will fail.
Renames @file to the specified display name.
Asynchronously sets the display name for a given #GFile.
Finishes setting a display name started with g_file_set_display_name_async().
Starts a file of type %G_FILE_TYPE_MOUNTABLE. Using @start_operation, you can request callbacks when, for instance, passwords are needed during authentication.
Finishes a start operation. See g_file_start_mountable() for details.
Stops a file of type %G_FILE_TYPE_MOUNTABLE.
Finishes a stop operation, see g_file_stop_mountable() for details.
Checks if @file supports g-main-context-push-thread-default-context. If this returns false, you cannot perform asynchronous operations on
Sends @file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. Not all file systems support trashing, so this call can return the %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the x-gvfs-notrash unix mount option can be used to disable g_file_trash() support for certain mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case.
Asynchronously sends @file to the Trash location, if possible.
Finishes an asynchronous file trashing operation, started with g_file_trash_async().
Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
Finishes an unmount operation, see g_file_unmount_mountable() for details.
Unmounts a file of type %G_FILE_TYPE_MOUNTABLE.
Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details.