glib

Function file_set_contents_full

Source 
pub fn file_set_contents_full(
    filename: impl AsRef<Path>,
    contents: &[u8],
    flags: FileSetContentsFlags,
    mode: i32,
) -> Result<(), Error>
Available on crate feature v2_66 only.
Expand description

Writes all of @contents to a file named @filename, with good error checking. If a file called @filename already exists it will be overwritten.

@flags control the properties of the write operation: whether it’s atomic, and what the tradeoff is between returning quickly or being resilient to system crashes.

As this function performs file I/O, it is recommended to not call it anywhere where blocking would cause problems, such as in the main loop of a graphical application. In particular, if @flags has any value other than FileSetContentsFlags::NONE then this function may call fsync().

If FileSetContentsFlags::CONSISTENT is set in @flags, the operation is atomic in the sense that it is first written to a temporary file which is then renamed to the final name.

Notes:

  • On UNIX, if @filename already exists hard links to @filename will break. Also since the file is recreated, existing permissions, access control lists, metadata etc. may be lost. If @filename is a symbolic link, the link itself will be replaced, not the linked file.

  • On UNIX, if @filename already exists and is non-empty, and if the system supports it (via a journalling filesystem or equivalent), and if FileSetContentsFlags::CONSISTENT is set in @flags, the fsync() call (or equivalent) will be used to ensure atomic replacement: @filename will contain either its old contents or @contents, even in the face of system power loss, the disk being unsafely removed, etc.

  • On UNIX, if @filename does not already exist or is empty, there is a possibility that system power loss etc. after calling this function will leave @filename empty or full of NUL bytes, depending on the underlying filesystem, unless FileSetContentsFlags::DURABLE and FileSetContentsFlags::CONSISTENT are set in @flags.

  • On Windows renaming a file will not remove an existing file with the new name, so on Windows there is a race condition between the existing file being removed and the temporary file being renamed.

  • On Windows there is no way to remove a file that is open to some process, or mapped into memory. Thus, this function will fail if @filename already exists and is open.

If the call was successful, it returns true. If the call was not successful, it returns false and sets @error. The error domain is G_FILE_ERROR. Possible error codes are those in the #GFileError enumeration.

Note that the name for the temporary file is constructed by appending up to 7 characters to @filename.

If the file didn’t exist before and is created, it will be given the permissions from @mode. Otherwise, the permissions of the existing file may be changed to @mode depending on @flags, or they may remain unchanged.

§filename

name of a file to write @contents to, in the GLib file name encoding

§contents

string to write to the file

§flags

flags controlling the safety vs speed of the operation

§mode

file mode, as passed to open(); typically this will be 0666

§Returns

true on success, false if an error occurred Writes all of @contents to a file named @filename, with good error checking. If a file called @filename already exists it will be overwritten.

@flags control the properties of the write operation: whether it’s atomic, and what the tradeoff is between returning quickly or being resilient to system crashes.

As this function performs file I/O, it is recommended to not call it anywhere where blocking would cause problems, such as in the main loop of a graphical application. In particular, if @flags has any value other than FileSetContentsFlags::NONE then this function may call fsync().

If FileSetContentsFlags::CONSISTENT is set in @flags, the operation is atomic in the sense that it is first written to a temporary file which is then renamed to the final name.

Notes:

  • On UNIX, if @filename already exists hard links to @filename will break. Also since the file is recreated, existing permissions, access control lists, metadata etc. may be lost. If @filename is a symbolic link, the link itself will be replaced, not the linked file.

  • On UNIX, if @filename already exists and is non-empty, and if the system supports it (via a journalling filesystem or equivalent), and if FileSetContentsFlags::CONSISTENT is set in @flags, the fsync() call (or equivalent) will be used to ensure atomic replacement: @filename will contain either its old contents or @contents, even in the face of system power loss, the disk being unsafely removed, etc.

  • On UNIX, if @filename does not already exist or is empty, there is a possibility that system power loss etc. after calling this function will leave @filename empty or full of NUL bytes, depending on the underlying filesystem, unless FileSetContentsFlags::DURABLE and FileSetContentsFlags::CONSISTENT are set in @flags.

  • On Windows renaming a file will not remove an existing file with the new name, so on Windows there is a race condition between the existing file being removed and the temporary file being renamed.

  • On Windows there is no way to remove a file that is open to some process, or mapped into memory. Thus, this function will fail if @filename already exists and is open.

If the call was successful, it returns true. If the call was not successful, it returns false and sets @error. The error domain is G_FILE_ERROR. Possible error codes are those in the #GFileError enumeration.

Note that the name for the temporary file is constructed by appending up to 7 characters to @filename.

If the file didn’t exist before and is created, it will be given the permissions from @mode. Otherwise, the permissions of the existing file may be changed to @mode depending on @flags, or they may remain unchanged.

§filename

name of a file to write @contents to, in the GLib file name encoding

§contents

string to write to the file

§flags

flags controlling the safety vs speed of the operation

§mode

file mode, as passed to open(); typically this will be 0666

§Returns

true on success, false if an error occurred