gfileutils: document non-atomicity of g_file_set_contents()

This function only calls fsync() if @target exists and is non-empty. If
not, it doesn't provide the "old contents or new contents" guarantee
that one might expect. This has been the case since
d20a188b12, and is justified either as a
performance optimization or by asserting that this function only
guarantees to not destroy existing data (implicitly defining
non-existence or emptiness as not data).

In addition, explicitly spell out that whether it's atomic in the
non-empty case is system-dependent. If the system administrator has
configured some funky filesystem options, they may be out of luck on the
atomicity front.

https://gitlab.gnome.org/GNOME/glib/issues/1302

glib/gfileutils.c

@@ -1173,6 +1173,17 @@ write_to_temp_file (const gchar  *contents,
  *   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), 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.
+ *
  * - 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.