Function
GLibfile_set_contents_full
since: 2.66
Declaration
gboolean
g_file_set_contents_full (
const gchar* filename,
const gchar* contents,
gssize length,
GFileSetContentsFlags flags,
int mode,
GError** error
)
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
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
filenamealready exists hard links tofilenamewill break. Also since the file is recreated, existing permissions, access control lists, metadata etc. may be lost. Iffilenameis a symbolic link, the link itself will be replaced, not the linked file. -
On UNIX, if
filenamealready exists and is non-empty, and if the system supports it (via a journalling filesystem or equivalent), and ifG_FILE_SET_CONTENTS_CONSISTENTis set inflags, thefsync()call (or equivalent) will be used to ensure atomic replacement:filenamewill contain either its old contents orcontents, even in the face of system power loss, the disk being unsafely removed, etc. -
On UNIX, if
filenamedoes not already exist or is empty, there is a possibility that system power loss etc. after calling this function will leavefilenameempty or full of NUL bytes, depending on the underlying filesystem, unlessG_FILE_SET_CONTENTS_DURABLEandG_FILE_SET_CONTENTS_CONSISTENTare set inflags. -
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
filenamealready 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
contentsto, in the GLib file name encoding.The data is owned by the caller of the function. The value is a file system path, using the OS encoding. contents-
Type: An array of
guint8String to write to the file.
The length of the array is specified in the lengthargument.The data is owned by the caller of the function. length-
Type:
gssizeLength of
contents, or -1 ifcontentsis a nul-terminated string. flags-
Type:
GFileSetContentsFlagsFlags controlling the safety vs speed of the operation.
mode-
Type:
intFile mode, as passed to
open(); typically this will be0666 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 aNULLGError*.The argument will be left initialized to NULLby 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.