GLib.file_set_contents_full
Description: Reference for GLib.file_set_contents_full

### Function

# GLibfile_set_contents_full

since: 2.66

#### Declaration [src]

    gboolean
    g_file_set_contents_full (
      const gchar* filename,
      const gchar* contents,
      gssize length,
      GFileSetContentsFlags flags,
      int mode,
      GError** error
    )

#### Description [src]

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 `G_FILE_SET_CONTENTS_NONE` then this function may call `fsync()`.

If `G_FILE_SET_CONTENTS_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 `G_FILE_SET_CONTENTS_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 `G_FILE_SET_CONTENTS_DURABLE` and `G_FILE_SET_CONTENTS_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.

Available since: 2.66

#### Parameters

`filename`

  Type: `const gchar*`

  Name of a file to write `contents` to, in the GLib file name encoding.

  The data is owned by the caller of the function.
  The value is a platform-native string, using the preferred OS encoding on Unix and UTF-8 on Windows.

`contents`

  Type: An array of `guint8`

  String to write to the file.

  The length of the array is specified in the `length` argument.
  The data is owned by the caller of the function.

`length`

  Type: `gssize`

  Length of `contents`, or -1 if `contents` is a nul-terminated string.

`flags`

  Type: `GFileSetContentsFlags`

  Flags controlling the safety vs speed of the operation.

`mode`

  Type: `int`

  File mode, as passed to `open()`; typically this will be `0666`.

`error`

  Type: `GError **`

  The return location for a recoverable error.

  The argument can be `NULL`.
  If the return location is not `NULL`, then you must initialize it to a `NULL` `GError*`.
  The argument will be left initialized to `NULL` by the function if there are no errors.
  In case of error, the argument will be set to a newly allocated `GError`; the caller will take ownership of the data, and be responsible for freeing it.

#### Return value

Type: `gboolean`

`TRUE` on success, `FALSE` if an error occurred.