Create  Edit  FrontPage  Index  Search  Changes  History  RSS  Login

GLib::File

module GLib::File

GLib::File is a high level abstraction for manipulating files on a virtual file system. GLib::File objects are lightweight, immutable objects that do no I/O upon creation. It is necessary to understand that GLib::File objects do not represent files, merely an identifier for a file. All file content I/O is implemented as streaming operations (see GLib::InputStream and GLib::OutputStream).

To construct a GLib::File, use:

One way to think of a GLib::File is as an abstraction of a pathname. For normal files the system pathname is what is stored internally, but as GLib::File objects are extensible it could also be something else that corresponds to a pathname in a userspace implementation of a filesystem.

GLib::File objects make up hierarchies of directories and files that correspond to the files on a filesystem. You can move through the file system with GLib::File using Glib::File#parent to get an identifier for the parent directory, GLib::File#child to get a child within a directory, GLib::File#resolve_relative_path to resolve a relative path between two GLib::Files?. There can be multiple hierarchies, so you may not end up at the same root if you repeatedly call GLib::File#parent on two different files.

All GLib::File objects have a basename (retrieve it with GLib::File#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 GLib::FileAttribute::STANDARD_DISPLAY_NAME attribute with GLib::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 GLib::File to use to actually access the file, because there is no way to go from a display name to the actual name.

Using GLib::File 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 GLib::File objects 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 GLib::File objects point to the same file you can query for the GLib::FileAttribute::ID_FILE attribute. Note that GLib::File 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 GLib::Files?.

Many GLib::File 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 block that is then used to finalize the operation, producing a GLib::AsyncResult that is then passed to the function’s matching “_finish” method.

Some GLib::File 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: GLib::File#mount_mountable to mount a mountable file. GLib::File#unmount_mountable_with_operation to unmount a mountable file. GLib::File#eject_mountable_with_operation to eject a mountable file.

One notable feature of GLib::Files? 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.

Module Functions

GLib::File.new_for_commandline_arg(arg)
Creates a GLib::File with the given argument from the command line. The value of arg can be either a URI, an absolute path or a relative path resolved relative to the current working directory. This operation never fails, but the returned object might not support any I/O operation if arg points to a malformed path.
  • arg: A command line String
  • Returns: A new GLib::File
GLib::File.new_for_path(path)
Constructs a GLib::File for a given path. This operation never fails, but the returned object might not support any I/O operation if path is malformed.
  • path: A String containing a relative or absolute path. The String must be encoded in the glib filename encoding
  • Returns: A new GLib::File for the given path
GLib::File.new_for_uri(uri)
Constructs a GLib::File for a given URI. This operation never fails, but the returned object might not support any I/O operation if uri is malformed or if the uri type is not supported.
  • uri: A UTF-8 String containing a URI
  • Returns: A GLib::File for the given uri
GLib::File.parse_name(parse_name)
Constructs a GLib::File with the given parse_name (that is, something given by GLib::File#parse_name). This operation never fails, but the returned object might not support any I/O operation if the parse_name cannot be parsed.
  • parse_name: A file name or path to be parsed
  • Returns: A new GLib::File

Instance Methods

==(other)

Checks equality of two given GLib::Files?. Note that two GLib::Files? that differ can still refer to the same file on the filesystem due to various forms of filename aliasing.

This method does no blocking I/O.

  • other: The GLib::File to compare against
  • Returns: true if self and other are equal
append_to(flags = GLib::File::CREATE_NONE, cancellable = nil)

Gets an output stream for appending data to the file. If the file doesn't already exist it is created.

By default files created are generally readable by everyone, but if you pass GLib::File::CREATE_PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target filesystem.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

Some file systems don't allow all file names, and may raise an GLib::IO::InvalidFilenameError error. If the file is a directory GLib::IO::IsDirectoryError will be raised. Other errors are possible too, and depend on what kind of filesystem the file is on.

append_to_async(flags = GLib::File::CREATE_NONE, io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously open for appending.

For more details, see GLib::File#append_to which is the synchronous version of this call.

When the operation is finished a GLib::AsyncResult will be yielded. Call GLib::File#append_to_finish to get the result of the operation.

append_to_finish(result)

Finishes an asynchronous file append operation started with GLib::File#append_to_async.

A GLib::IO::Error is raised if an error occurred during opening.

attributes_from_info=(info)
Same as GLib::File#set_attributes_from_info.
basename

Gets the base name (the last component of the path) of the file.

If called for the top level of a system (such as the filesystem root or a uri like sftp://host/) it will return a single directory separator (and on Windows, possibly a drive letter).

The base name is a byte String (*not* UTF-8). It has no defined encoding 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 GLib::FileAttribute::STANDARD_DISPLAY_NAME attribute with GLib::File#query_info.

This method does no blocking I/O.

copy(destination, flags = GLib::File::COPY_NONE, cancellable = nil){ |current_num_bytes, total_num_bytes| }

Copies the file to the location specified by destination. Can not handle recursive copies of directories.

If the flag GLib::File::COPY_OVERWRITE is specified an already existing destination file is overwritten.

If the flag GLib::File::COPY_NOFOLLOW_SYMLINKS is specified, then symlinks will be copied as symlinks, otherwise the target of the source symlink will be copied.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

The operation can be monitored by passing in a block. It is guaranteed that this block will be called after all data has been transferred with the total number of bytes copied during the operation.

If the file does not exist then the G::IO::NotFoundError error is raised, independent on the status of the destination.

If GLib::File::COPY_OVERWRITE is not specified and the target exists, then the error GLib::IO::ExistsError is returned.

If trying to overwrite a file over a directory the GLib::IO::IsDirectoryError error is raised. If trying to overwrite a directory with a directory the GLib::IO::WouldMergeError error is raised.

If the source is a directory and the target does not exist, or GLib::File::COPY_OVERWRITE is specified and the target is a file, then the GLib::IO::WouldRecurseError error is raised.

If you are interested in copying the GLib::File object itself (not the on-disk file), see GLib::File#dup.

copy_async(destination, flags = GLib::File::COPY_NONE, io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |*progress_or_result| }

Copies the file to the location specified by destination asynchronously. For details of the behavior, see GLib::File#copy.

The block receives progress information in the same way that GLib::File#copy does. The block will also be called upon completion with a GLib::AsyncResult. Thus, the block should deal with progress if it has received two arguments and completion if it has received one argument. Call GLib::File#copy_finish to get the result of the operation.

Note that the block will be called from the main loop when progress is being reported, not in the thread that is doing the I/O operation.

copy_finish(result)

Finishes copying the file started with GLib::File#copy_async.

A GLib::IO::Error is raised if an error occurred during copying.

copy_attributes(destination, flags = GLib::File::COPY_NONE, cancellable = nil)

Copies the file attributes from file to destination.

Normally only the file attributes that are copied in a normal file copy operation are copied, which does not include, for example, include owner). However, if GLib::File::COPY_ALL_METADATA is specified in flags, then all the metadata that is possible to copy is copied. This is useful when implementing move by copy + delete source.

A GLib::IO::Error is raised if an error occurred during copying.

create(flags = GLib::File::CREATE_NONE, cancellable = nil)

Creates a new file and returns an output stream for writing to it. The file must not already exist.

By default, files created are generally readable by everyone, but if you pass GLib::File::CREATE_PRIVATE in flags, the file will be made readable only to the current user, to the level that is supported on the target filesystem.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

If a file or directory with this name already exists, GLib::IO::ExistsError will be raised. Some file systems don’t allow all file names, and may raise a GLib::IO::InvalidFilenameError error, and if the name is too long, GLib::IO::FilenameTooLongError will be raised. Other errors are possible too, and depend on what kind of filesystem the file is on.

create_async(flags = GLib::File::CREATE_NONE, io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist.

For more details, see GLib::File#create which is the synchronous version of this call.

When the operation is finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#create_finish to get the result of the operation.

create_finish(result)

Finishes an asynchronous file create operation started with GLib::File#create_async.

A GLib::IO::Error is raised if an error occurred during creation.

create_readwrite(flags = GLib::File::CREATE_NONE, cancellable = nil)

Creates a new file and returns a stream for reading and writing to it. The file must not already exist.

By default files created are generally readable by everyone, but if you pass GLib::File::CREATE_PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target filesystem.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

If a file or directory with this name already exists, GLib::IO::ExistsError will be raised. Some file systems don’t allow all file names, and may raise a GLib::IO::InvalidFilenameError error, and if the name is too long, GLib::IO::FilenameTooLongError will be raised. Other errors may be raised as well, depend on what kind of filesystem the file is on.

Note that in many non-local file cases read and write streams aren’t supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

Since 2.22

create_readwrite_async(flags = GLib::File::CREATE_NONE, io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist.

For more details, see GLib::File#create_readwrite, which is the synchronous version of this call.

When the operation is finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#create_readwrite_finish to get the result of the operation.

Since 2.22

create_readwrite_finish(result)

Finishes an asynchronous file create operation started with GLib::File#create_readwrite_async.

A GLib::IO::Error is raised if an error occurred during creation.

Since 2.22

delete(cancellable = nil)

Deletes a file. If the file is a directory, it will only be deleted if it’s empty.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: true if the file was deleted. false otherwise
display_name=(display_name)
Same as GLib::File::set_display_name.
  • display_name: A String containing the new display name
  • Returns: display_name
dup

Duplicates a GLib::File. This operation does not duplicate the actual file or directory represented by the GLib::File; see GLib::File#copy if attempting to copy a file.

This method does no blocking I/O.

each(attributes = 'standard::*', flags = GLib::File::QUERY_INFO_NONE, cancellable = nil)
Same as GLib::File#enumerate_children.
each_async(num_files, attributes = 'standard::*', flags = GLib::File::QUERY_INFO_NONE, io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }
Calls GLib::File#enumerate_children_async, then GLib::File#enumerate_children_finish, and finally GLib::FileEnumerator#each_async.
  • Returns: self
eject_mountable_with_operation(flags = GLib::Mount::UNMOUNT_NONE, mount_operation = nil, cancellable = nil){ |result| }

Starts an asynchronous eject on a mountable.

When this operation has completed, a GLib::AsyncResult will be yielded, and the operation can be finalized with GLib::File#eject_mountable_with_operation_finish.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

Since 2.22

eject_mountable_with_operation_finish(result)

Finishes an asynchronous eject operation started by GLib::File#eject_mountable_with_operation.

A GLib::IO::Error is raised if an error occurred during ejection.

Since 2.22

enumerate_children(attributes = 'standard::*', flags = GLib::File::QUERY_INFO_NONE, cancellable = nil){ |info| }

Gets the requested information about the files in a directory.

If a block is not given, then the result is a GLib::FileEnumerator object that will yield GLib::FileInfo objects for all the files in the directory.

If a block is given, then all the GLib::FileInfo object will be passed to this block.

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 GLib::FileAttribute::STANDARD_NAME.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

If the file does not exist, GLib::IO::NotFoundError will be raised. If the file is not a directory, GLib::IO::NotDirError will be raised. Other errors may be raised as well.

enumerate_children_async(attributes = 'standard::*', flags = GLib::File::QUERY_INFO_NONE, io_priority = Glib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously gets the requested information about the files in a directory. The result is a GLib::FileEnumerator object that will give out GLib::FileInfo objects for all the files in the directory.

For more details, see GLib::File#enumerate_children which is the synchronous version of this call.

When the operation is finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#enumerate_children_finish to get the result of the operation.

enumerate_children_finish(result)
Finishes an async enumerate children operation. See GLib::File#enumerate_children_async.
exists?(cancellable = nil)
Same as GLib::File#query_exists?.
find_enclosing_mount(cancellable = nil)

Gets a GLib::Mount for the GLib::File.

If the file doesn’t have a mount (for example, possibly a remote share), a GLib::IO::NotFoundError will be raised.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

find_enclosing_mount_async(io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously gets the mount for the file.

For more details, see GLib::File#find_enclosing_mount which is the synchronous version of this call.

When the operation is finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#find_enclosing_mount_finish to get the result of the operation.

find_enclosing_mount_finish(result)
Finishes an asynchronous find mount request. See GLib::File#find_enclosing_mount_async.
get_child(name)

Gets a child of file with basename equal to name.

Note that the file with that specific name might not exist, but you can still have a GLib::File that points to it. You can use this for instance to create that file.

This method does no blocking I/O.

  • name: String containing the child’s basename
  • Returns: A GLib::File to a child specified by name
get_child_for_display_name(display_name)

Gets the child of file for a given display_name (that is, a UTF-8 version of the name).

A GLib::IO::Error is raised if the display_name can’t be converted.

This method 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 method does no blocking i/o.

  • display_name: String to a possible child
  • Returns: A GLib::File to the specified child
get_relative_path(descendant)

Gets the path for descendant relative to this file.

This method does no blocking I/O.

  • descendant: Input GLib::File
  • Returns: String with the relative path from descendant to parent, or nil if descendant doesn’t have parent as prefix
has_parent?(parent)

Checks if file has a parent, and optionally, if it is parent.

If parent is nil then this function returns true if file has any parent at all. If parent is non-nil then true is only returned if file is a child of parent.

Since 2.24

  • parent: The parent to check for, or nil
  • Returns: true if file is a child of parent (or any parent in the case that parent is nil)
has_prefix?(prefix)

Checks whether file has the prefix specified by prefix. In other word, if the names of inital elements of files 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 of prefix.

  • prefix: Input GLib::File
  • Returns: true if the files’s parent, grandparent, etc. is prefix
has_uri_scheme?(uri_scheme)

Checks to see if a GLib::File has a given URI scheme.

This method does no blocking I/O.

  • uri_scheme: A String containing a URI scheme
  • Returns: true if GLib::Filegs? backend supports the given URI scheme, false if URI scheme is nil, not supported, or the GLib::File is invalid
hash

Creates a hash value for a GLib::File.

This method does no blocking I/O.

  • Returns: 0 if file is not a valid GLib::File, otherwise an integer that can be used as hash value for the GLib::File
load_contents(cancellable = nil)

Loads the content of the file into memory.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: The file's contents as a String and the current entity tag for the file
load_contents_async(cancellable = nil){ |result| }

Starts an asynchronous load of the file's contents.

For more details, see GLib::File#load_contents which is the synchronous version of this call.

When the load operation has completed, a GLib::AsyncResult will be yielded. To finish the operation, call GLib::File#load_contents_finish with this GLib::AsyncResult.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

load_contents_finish(result)
Finishes an asynchronous load of the file's contents.
  • result: A GLib::AsyncResult
  • Returns: The file's contents as a String and the current entity tag for the file
load_partial_contents_async(cancellable = nil, use_read_more_callback = false){ |data_or_result| }

Reads the partial contents of a file.

If use_read_more_callback is true, then every once in a while the block will, if passed, be called with the currently read data as a String. If the block’s value is false, then the loading is considered to be done.

When loading is done, a GLib::AsyncResult will be yielded. To finish the operation, call GLib::File#load_partial_contents_finish with this GLib::AsyncResult.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • use_read_more_callback: Whether to use the block as a “read more callback”
  • data_or_result: A String containing the data read so far, or a GLib::AsyncResult, when done reading
  • Returns: self
load_partial_contents_finish(result)
Finishes an asynchronous partial load operation that was started with GLib::File#load_partial_contents_async.
  • result: A GLib::AsyncResult
  • Returns: The file's contents as a String and the current entity tag for the file
make_directory(cancellable = nil)

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 GLib::File. To recursively create directories, see GLib::File#make_directory_with_parents.

This function will raise a GLib::IO::NotFoundError if the parent directory doesn’t exist. If the file system doesn’t support creating directories, this function will raise a GLib::IO::NotSupportedError.

For a local GLib::File the newly created directory will have the default (current) ownership and permissions of the current process.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

make_directory_with_parents(cancellable = nil)

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 raise a GLib::IO::NotSupportedError.

For a local GLib::File the newly created directories will have the default (current) ownership and permissions of the current process.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

Since 2.18

make_symbolic_link(symlink_value, cancellable = nil)

Creates a symbolic link of this file that contains the String symlink_value.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if the symbolic link can’t be created.

  • symlink_value: A String with the path for the target of the new symlink
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: true
monitor(flags = GLib::File::MONITOR_NONE, cancellable = nil)

Obtains a file or directory monitor for the given file, depending on the type of the file.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if this file can’t be monitored.

Since 2.18

monitor_directory(flags = GLib::File::MONITOR_NONE, cancellable = nil)

Obtains a directory monitor for the given file.

This method may fail if directory monitoring is not supported.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if this file can’t be monitored.

monitor_file(flags = GLib::File::MONITOR_NONE, cancellable = nil)

Obtains a file monitor for the given file. If no file notification mechanism exists, then regular polling of the file is used.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if this file can’t be monitored.

mount_enclosing_volume(flags = GLib::Mount::MOUNT_NONE, mount_operation = nil, cancellable = nil){ |result| }

Starts a mount_operation, mounting the volume that contains this file.

When this operation has completed, a GLib::AsyncResult will be yield, and the operation can be finalized with GLib::File#mount_enclosing_volume_finish.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

mount_enclosing_volume_finish(result)

Finishes a mount operation started by GLib::File#mount_enclosing_volume.

A GLib::IO::Error is raised if the volume that contains this file can’t be mounted.

mount_mountable(flags = GLib::Mount::MOUNT_NONE, mount_operation = nil, cancellable = nil){ |result| }

Mounts a file of type GLib::File::TYPE_MOUNTABLE.

Using mount_operation, you can request callbacks when, for instance, passwords are needed during authentication.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#mount_mountable_finish to get the result of the operation.

mount_mountable_finish(result)

Finishes a mount operation. See GLib::File#mount_mountable for details.

Finish an asynchronous mount operation that was started with GLib::File#mount_mountable.

A GLib::IO::Error is raised if this file can’t be mounted.

move(destination, flags = GLib::File::COPY_NONE, cancellable = nil){ |current_num_bytes, total_num_bytes| }

Tries to move this file or directory 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.

If the flag GLib::File::COPY_OVERWRITE is specified an already existing destination file is overwritten.

If the flag GLib::File::COPY_NOFOLLOW_SYMLINKS is specified then symlinks will be copied as symlinks, otherwise the target of the source symlink will be copied.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

The operation can be monitored by passing in a block. It is guaranteed that this block will be called after all data has been transferred with the total number of bytes copied during the operation.

If the file doesn’t exist then GLib::IO::NotFoundError is raised, independent on the status of the destination.

If GLib::File::COPY_OVERWRITE is not specified and the target exists, then GLib::IO::ExistsError is raised.

If trying to overwrite a file over a directory the GLib::IO::IsDirectoryError error is raised. If trying to overwrite a directory with a directory the GLib::IO::WouldMergeError error is raised.

If the source is a directory and the target does not exist, or GLib::File::COPY_OVERWRITE is specified and the target is a file, then the GLib::IO::WouldRecurseError error may be raised (if the native move operation isn’t available).

  • destination: GLib::File pointing to the destination location
  • flags: Set of GLib::File::CopyFlags
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • current_num_bytes: Number of bytes moved so far
  • total_num_bytes: Number of bytes to move
  • Returns: self
native?

Checks to see if file is native to the platform.

A native file s one expressed in the platform-native filename format, for example, “C:\Windows” or “/usr/bin/”. This doesn’t mean the file is local, as it might be on a locally mounted remote filesystem.

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 GLib::File#path will still return a native path.

This method does no blocking I/O.

  • Returns: true if file is native
open_readwrite(cancellable = nil)

Opens an existing file for reading and writing. The result is a GLib::FileIOStream that can be used to read and write the contents of the file.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

If the file does not exist, GLib::IO::NotFoundError will be raised. If the file is a directory, GLib::IO::IsDirectoryError will be raised. Other errors are possible too, and depend on what kind of filesystem the file is on. Note that in many non-local file cases read and write streams aren’t supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

Since 2.22

open_readwrite_async(io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously opens file for reading and writing.

For more details, see GLib::File#open_readwrite which is the synchronous version of this call.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#open_readwrite_finish to get the result of the operation.

Since 2.22

open_readwrite_finish(result)

Finishes an asynchronous file read operation started with GLib::File#open_readwrite_async.

A GLib::IO::Error is raised if this file can’t be opened.

Since 2.22

parent

Gets the parent directory for the file.

If the file represents the root directory of the file system, then nil will be returned.

This method does no blocking I/O.

parse_name

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 GLib::File back using GLib::File#parse_name.

This is generally used to show the GFile as a nice full-pathname kind of String in a user interface, like in a location entry.

For local files with names that can safely be converted to UTF-8 the pathname is used, otherwise the IRI is used (a form of URI that allows UTF-8 characters unescaped).

This method does no blocking I/O.

  • Returns: A String containing the GLib::File’s parse name
path

Gets the local pathname for GLib::File, if one exists.

This method does no blocking I/O.

  • Returns: A String containing the GLib::File’s path, or nil if no such path exists
poll_mountable(cancellable = nil){ |result| }

Polls a file of type GLib::File::TYPE_MOUNTABLE.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#mount_mountable_finish to get the result of the operation.

Since 2.22

poll_mountable_finish(result)

Finishes a poll operation. See GLib::File#poll_mountable for details.

Finish an asynchronous poll operation that was polled with GLib::File#poll_mountable.

A GLib::IO::Error is raised if this file can’t be polled.

Since 2.22

query_default_handler(cancellable = nil)

Returns the GLib::AppInfo that is registered as the default application to handle this file.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if a handler couldn’t be found

query_exists?(cancellable = nil)

Utility function to check if a particular file exists. This is implemented using GLib::File#query_info and as such does blocking I/O.

Note that in many cases it is racy to first check for file existence and then execute something based on the outcome of that, because the file might have been created or removed in between the operations. The general approach to handling that is to not check, but just do the operation and handle the errors as they come.

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 GLib::File#create which will either atomically create the file or fail with a GLib::IO::ExistsError 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 and 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.

  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: true if the file exists
query_file_type(flags = GLib::File::QUERY_INFO_NONE, cancellable = nil)

Utility function to inspect the GLib::FileType of a file. This is implemented using GLib::File#query_info and as such does blocking I/O.

The primary use case of this method is to check if a file is a regular file, directory, or symlink.

Since 2.18

query_filesystem_info(attributes = 'fs::*', cancellable = nil)

Similar to GLib::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.

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 'fs::*' means all attributes in the fs namespace. The standard namespace for filesystem attributes is 'fs'. Common attributes of interest are GLib::FileAttribute::FILESYSTEM_SIZE (the total size of the filesystem in bytes), GLib::FileAttribute::FILESYSTEM_FREE (number of bytes available), and GLib::FileAttribute::FILESYSTEM_TYPE (type of the filesystem).

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

If the file does not exist, GLib::IO::NotFoundError will be raised. Other errors are possible too, and depend on what kind of filesystem the file is on.

query_filesystem_info_async(attributes = 'fs::*', io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously gets the requested information about the filesystem that the specified file is on. The result is a GLib::FileInfo object that contains key-value attributes (such as type or size for the file).

For more details, see GLib::File#query_filesystem_info which is the synchronous version of this call.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#query_info_finish to get the result of the operation.

  • attributes: An attribute query String
  • io_priority: The I/O priority of the request
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • result: A GLib::AsyncResult
  • Returns: self
query_filesystem_info_finish(result)

Finishes an asynchronous filesystem info query. See GLib::File#query_filesystem_info_async.

A GLib::IO::Error is raised if the filesystem info couldn’t be read.

query_info(attributes = 'standard::*', flags = GLib::File::QUERY_INFO_NONE, cancellable = nil)

Gets the requested information about this file. The result is a GLib::FileInfo 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’s 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 GLib::FileAttribute::STANDARD_NAME.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

For symlinks, normally the information about the target of the symlink is returned, rather than information about the symlink itself. However if you pass GLib::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.

If the file does not exist, GLib::IO::NotFoundError will be raised. Other errors are possible too, and depend on what kind of filesystem the file is on.

query_info_async(attributes = 'standard::*', flags = GLib::File::QUERY_INFO_NONE, io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously gets the requested information about specified file. The result is a GLib::FileInfo object that contains key-value attributes (such as type or size for the file).

For more details, see GLib::File#query_info which is the synchronous version of this call.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#query_info_finish to get the result of the operation.

query_info_finish(result)

Finishes an asynchronous file info query. See GLib::File#query_info_async.

A GLib::IO::Error is raised if the information couldn’t be retrieved.

query_settable_attributes(cancellable = nil)

Obtain the list of settable attributes for the file.

Returns the type and full attribute name of all the attributes that can be set on this file. This doesn’t mean setting it will always succeed though, you might get an access failure, or some specific file may not support a specific attribute.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

query_writable_namespaces(cancellable = nil)

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).

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

read(cancellable = nil)

Opens a file for reading. The result is a GLib::FileInputStream that can be used to read the contents of the file.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

If the file doesn’t exist, GLib::IO::NotFoundError will be raised. If the file is a directory, GLib::IO::IsDirectoryError will be raised. Other errors are possible too, and depend on what kind of filesystem the file is on.

read_async(io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously opens file for reading.

For more details, see GLib::File#read, which is the synchronous version of this call.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#read_finish to get the result of the operation.

read_finish(result)

Finishes an asynchronous file read operation started with GLib::File#read_async.

A GLib::IO::Error is raised if this file can’t be opened for reading.

replace(etag = nil, make_backup = false, flags = GLib::File::CREATE_NONE, cancellable = nil)

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.

This will try to replace the file in the safest way possible so that any errors during the writing will not affect an already existing copy of the file. For instance, for local files it may write to a temporary file and then atomically rename over the destination when the stream is closed.

By default files created are generally readable by everyone, but if you pass GLib::File::CREATE_PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target filesystem.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

If you pass in a non-nil etag value, then this value is compared to the current entity tag of the file, and if they differ an GLib::IO::WrongEtagError error is returned. This generally means that the file has been changed since you last read it. You can get the new etag from GLib::FileOutputStream#etag after you’ve finished writing and closed the GLib::FileOutputStream. When you load a new file you can use GLib::FileInputStream#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 a GLib::IO::CantCreateBackupError error will be returned. If you want to replace anyway, try again with make_backup set to false.

If the file is a directory, GLib::IO::IsDirectoryError will be raised, and if the file is some other form of non-regular file then a GLib::IO::NotRegularFileError error will be returned. Some file systems don’t allow all file names, and may return an GLib::IO::InvalidFilenameError error, and if the name is to long GLib::IO::FilenameTooLongError will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

replace_async(etag = nil, make_backup = false, flags = GLib::File::CREATE_NONE, io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first.

For more details, see GLib::File#replace which is the synchronous version of this call.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#replace_finish to get the result of the operation.

replace_finish(result)

Finishes an asynchronous file replace operation started with GLib::File#replace_async.

A GLib::IO::Error is raised if the file couldn’t be replaced.

replace_contents(contents, etag = nil, make_backup = false, flags = GLib::File::CREATE_NONE, cancellable = nil)

Replaces the contents of this file with contents. If etag is specified (not nil), any existing file must have that etag, or GLib::IO::WrongEtagError will be raised.

If make_backup is true, this function will attempt to make a backup of this file.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

The returned new etag can be used to verify that the file hasn’t changed the next time it is saved over.

  • contents: A String containing the new contents for this file
  • etag: The old entity tag for the document, or nil
  • make_backup: true if a backup should be created
  • flags: A set of GLib::File::CreateFlags
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: The new entity tag
replace_contents_async(contents, etag = nil, make_backup = false, flags = GLib::File::CREATE_NONE, cancellable = nil){ |result| }

Starts an asynchronous replacement of this file with the given contents. If etag is specified (not nil), any existing file must have that etag, or GLib::IO::WrongEtagError will be raised.

When this operation has completed, a GLib::AsyncResult will be yielded, and the operation can be finalized with GLib::File#replace_contents_finish.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

If make_backup is true, this function will attempt to make a backup of this file.

  • contents: A String containing the new contents for this file
  • etag: The old entity tag for the document, or nil
  • make_backup: true if a backup should be created
  • flags: A set of GLib::File::CreateFlags
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • result: A GLib::AsyncResult
  • Returns: self
replace_contents_finish(result)
Finishes an asynchronous replace of this file. See GLib::File#replace_contents_async. Returns the new entity tag for the document.
replace_readwrite(etag = nil, make_backup = false, flags = GLib::File::CREATE_NONE, cancellable = nil)

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.

For details about the behaviour, see GLib::File#replace which does the same thing but returns an output stream only.

Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

A GLib::IO::Error is raised if this file can’t be opened.

Since 2.22

replace_readwrite_async(etag = nil, make_backup = false, flags = GLib::File::CREATE_NONE, io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first.

For more details, see GLib::File#replace_readwrite which is the synchronous version of this call.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#replace_readwrite_finish to get the result of the operation.

Since 2.22

replace_readwrite_finish(result)

Finishes an asynchronous file replace operation started with GLib::File#replace_readwrite_async.

A GLib::IO::Error is raised if this file couldn’t be opened.

Since 2.22

resolve_relative_path(relative_path)

Resolves a path relative to this file to an absolute path.

This method does no blocking I/O.

  • relative_path: A given relative path String
  • Returns: GLib::File to the resolved path; nil if relative_path is nil or if this file is invalid
set_attribute(attribute, type, value, flags = GLib::File::QUERY_INFO_NONE, cancellable = nil)

Sets an attribute in the file with attribute name attribute to value.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if the attribute couldn’t be set.

set_attribute_byte_string(attribute, value, flags = GLib::File::QUERY_INFO_NONE, cancellable = nil)

Sets attribute of type GLib::FileAttribute::TYPE_BYTE_STRING to value. If attribute is of a different type, this operation will fail, returning false.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if the attribute couldn’t be set.

  • attribute: A String containing the attribute’s name
  • value: A String containing the attribute’s new value
  • flags: A GLib::File::QueryInfoFlags
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: self
set_attribute_int32(attribute, value, flags = GLib::File::QUERY_NONE, cancellable = nil)

Sets attribute of type GLib::FileAttribute::TYPE_INT32 to value. If attribute is of a different type, this operation will fail.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if the attribute couldn’t be set.

  • attribute: A String containing the attribute’s name
  • value: A Fixnum containing the attribute’s new value
  • flags: A GLib::File::QueryInfoFlags
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: self
set_attribute_int64(attribute, value, flags = GLib::File::QUERY_NONE, cancellable = nil)

Sets attribute of type GLib::FileAttribute::TYPE_INT64 to value. If attribute is of a different type, this operation will fail.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if the attribute couldn’t be set.

  • attribute: A String containing the attribute’s name
  • value: A Fixnum or Bignum containing the attribute’s new value
  • flags: A GLib::File::QueryInfoFlags
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: self
set_attribute_string(attribute, value, flags = GLib::File::QUERY_NONE, cancellable = nil)

Sets attribute of type GLib::FileAttribute::TYPE_STRING to value. If attribute is of a different type, this operation will fail.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if the attribute couldn’t be set.

  • attribute: A String containing the attribute’s name
  • value: A String containing the attribute’s new value
  • flags: GLib::File::QueryInfoFlags
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: self
set_attribute_uint32(attribute, value, flags = GLib::File::QUERY_NONE, cancellable = nil)

Sets attribute of type GLib::FileAttribute::TYPE_UINT32 to value. If attribute is of a different type, this operation will fail.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if the attribute couldn’t be set.

  • attribute: A String containing the attribute’s name
  • value: A Fixnum or Bignum containing the attribute’s new value
  • flags: A GLib::File::QueryInfoFlags
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: self
set_attribute_uint64(attribute, value, flags = GLib::File::QUERY_NONE, cancellable = nil)

Sets attribute of type GLib::FileAttribute::TYPE_UINT32 to value. If attribute is of a different type, this operation will fail.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if the attribute couldn’t be set.

  • attribute: A String containing the attribute's name
  • value: A Fixnum or Bignum containing the attribute’s new value
  • flags: A GLib::File::QueryInfoFlags
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: self
set_attributes_async(info, flags = GLib::File::QUERY_NONE, io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously sets the attributes of file with info.

For more details, see GLib::File#set_attributes_from_info, which is the synchronous version of this call.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#set_attributes_finish to get the result of the operation.

set_attributes_finish(result)

Finishes setting an attribute started in Glib::File#set_attributes_async.

A GLib::IO::Error is raised if the attributes couldn’t be set correctly.

set_attributes_from_info(info, flags = Glib::FILE::QUERY_NONE, cancellable = nil)

Tries to set all attributes in the GLib::FileInfo on the target values, not stopping on the first error.

If there is any error during this operation then raises the first error. Errors on particular fields are flagged by setting the “status” field in the attribute value to GLib::FileAttribute::STATUS_ERROR_SETTING, which means you can also detect further errors.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

set_display_name(display_name, cancellable = nil)

Renames this file to the specified display name.

The display name is converted from UTF-8 to the correct encoding for the target filesystem if possible and this file is renamed to this.

If you want to implement a rename operation in the user interface the edit name (GLib::FileAttribute::STANDARD_EDIT_NAME) should be used as the initial value in the rename widget, and then the result after editing should be passed to GLib::File#set_display_name.

On success, the resulting converted filename is returned.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

A GLib::IO::Error is raised if the display name can’t be set.

  • display_name: A String
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: A GLib::File specifying what file was renamed to
set_display_name_async(display_name, io_priority = GLib::PRIORITY_DEFAULT, cancellable = nil){ |result| }

Asynchronously sets the display name for a given GLib::File.

For more details, see GLib::File#set_display_name, which is the synchronous version of this call.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call Glib::File#set_display_name_finish to get the result of the operation.

  • display_name: A String
  • io_priority: The I/O priority of the request
  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • result: A GLib::AsyncResult
  • Returns: self
set_display_name_finish(result)

Finishes setting a display name started with GLib::File#set_display_name_async.

A GLib::IO::Error is raised if the display name couldn’t be set.

start_mountable(flags = GLib::Drive::START_NONE, start_operation = nil, cancellable = nil){ |result| }

Starts a file of type GLib::File::TYPE_MOUNTABLE. Using start_operation, you can request callbacks when, for instance, passwords are needed during authentication.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#mount_mountable_finish to get the result of the operation.

Since 2.22

start_mountable_finish(result)

Finishes a start operation. See GLib::File#start_mountable for details.

Finish an asynchronous start operation that was started with GLib::File#start_mountable.

A GLib::IO::Error is raised if this file couldn’t be started.

Since 2.22

stop_mountable(flags = GLib::Mount::UNMOUNT_NONE, mount_operation = nil, cancellable = nil){ |result| }

Stops a file of type Glib::File::TYPE_MOUNTABLE.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#stop_mountable_finish to get the result of the operation.

Since 2.22

stop_mountable_finish(result)

Finishes an stop operation, see GLib::File#stop_mountable for details.

Finish an asynchronous stop operation that was started with GLib::File#stop_mountable.

A GLib::IO::Error is raised if this file couldn’t be stopped.

Since 2.22

supports_thread_contexts?

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.

Since 2.22

  • Returns: Whether or not file supports thread-default contexts
trash(cancellable = nil)

Sends this 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 method can raise GLib::IO::NotSupportedError.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

  • cancellable: Optional GLib::Cancellable object, nil to ignore
  • Returns: true on successful trash, false otherwise
unmount_mountable_with_operation(flags = GLib::Mount::UNMOUNT_NONE, mount_operation = nil, cancellable = nil){ |result| }

Unmounts a file of type Glib::File::TYPE_MOUNTABLE.

If cancellable is not nil, then the operation can be cancelled by triggering the cancellable object from another thread. GLib::IO::CancelledError will be raised if the operation is cancelled.

When the operation has finished, a GLib::AsyncResult will be yielded. You can then call GLib::File#unmount_mountable_with_operation_finish to get the result of the operation.

Since 2.22

unmount_mountable_with_operation_finish(result)

Finishes an unmount operation, see GLib::File#unmount_mountable_with_operation for details.

Finish an asynchronous unmount operation that was started with GLib::File#unmount_mountable_with_operation.

A GLib::IO::Error is raised if this mountable couldn’t be unmounted.

Since 2.22

uri

Gets the URI to this file.

This method does no blocking I/O.

  • Returns: A String containing the GLib::File’s URI
uri_scheme

Gets the URI scheme for a GLib::File.

RFC 3986 decodes the scheme as:

URI = scheme ':' hier-part [ '?' query ] [ '#' fragment ]

Common schemes include “file”, “http”, “ftp”, etc.

This method does no blocking I/O.

  • Returns: A String containing the URI scheme for the GLib::File

Constants

COPY_ALL_METADATA
Copy all file metadata instead of just default set used for copy (see GLib::FileInfo)
COPY_BACKUP
Make a backup of any existing files
COPY_NOFOLLOW_SYMLINKS
Don’t follow symlinks
COPY_NONE
No flags set
COPY_NO_FALLBACK_FOR_MOVE
Don’t use copy and delete fallback if native move isn’t supported
COPY_OVERWRITE
Overwrite any existing files
COPY_TARGET_DEFAULT_PERMS
Leaves target file with default permissions, instead of setting the source file permissions
CREATE_NONE
No flags set
CREATE_PRIVATE
Create a file that can only be accessed by the current user
CREATE_REPLACE_DESTINATION

Replace the destination as if it didn’t exist before. Don’t try to keep any old permissions, replace instead of following links. This is generally useful if you’re doing a “copy over” rather than a “save new version of” replace operation. You can think of it as “unlink destination” before writing to it, although the implementation may not be exactly like that.

Since 2.20

MONITOR_NONE
No flags set
MONITOR_SEND_MOVED
Watch for mount events
MONITOR_WATCH_MOUNTS
Pair DELETED and CREATED events caused by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED event instead. (Nota bene: not supported on all backends; the default behaviour – without specifying this flag – is to send single DELETED and CREATED events.)
TYPE_UNKNOWN
The file’s type is unknown
TYPE_REGULAR
The file handle represents a regular file
TYPE_DIRECTORY
The file handle represents a directory
TYPE_SYMBOLIC_LINK
The file handle represents a symbolic link (Unix systems)
TYPE_SPECIAL
The file is a “special” file, such as a socket, fifo, block device, or character device
TYPE_SHORTCUT
The file is a shortcut (Windows systems)
TYPE_MOUNTABLE
The file is a mountable location
QUERY_INFO_NOFOLLOW_SYMLINKS
Don’t follow symlinks
QUERY_INFO_NONE
No flags set