Functions
g_file_get_contents ()
gboolean
g_file_get_contents (const gchar *filename,
gchar **contents,
gsize *length,
GError **error);
Reads an entire file into allocated memory, with good error
checking.
If the call was successful, it returns TRUE and sets contents
to the file
contents and length
to the length of the file contents in bytes. The string
stored in contents
will be nul-terminated, so for text files you can pass
NULL for the length
argument. 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. In the error case,
contents
is set to NULL and length
is set to zero.
Returns
TRUE on success, FALSE if an error occurred
g_file_set_contents ()
gboolean
g_file_set_contents (const gchar *filename,
const gchar *contents,
gssize length,
GError **error);
Writes all of contents
to a file named filename
, with good error checking.
If a file called filename
already exists it will be overwritten.
This write 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), 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.
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
.
Returns
TRUE on success, FALSE if an error occurred
Since: 2.8
g_file_test ()
gboolean
g_file_test (const gchar *filename,
GFileTest test);
Returns TRUE if any of the tests in the bitfield test
are
TRUE. For example, (G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)
will return TRUE if the file exists; the check whether it's a
directory doesn't matter since the existence test is TRUE. With
the current set of available tests, there's no point passing in
more than one test at a time.
Apart from G_FILE_TEST_IS_SYMLINK all tests follow symbolic links,
so for a symbolic link to a regular file g_file_test() will return
TRUE for both G_FILE_TEST_IS_SYMLINK and G_FILE_TEST_IS_REGULAR.
Note, that for a dangling symbolic link g_file_test() will return
TRUE for G_FILE_TEST_IS_SYMLINK and FALSE for all other flags.
You should never use g_file_test() to test whether it is safe
to perform an operation, because there is always the possibility
of the condition changing before you actually perform the operation.
For example, you might think you could use G_FILE_TEST_IS_SYMLINK
to know whether it is safe to write to a file without being
tricked into writing into a different location. It doesn't work!
Another thing to note is that G_FILE_TEST_EXISTS and
G_FILE_TEST_IS_EXECUTABLE are implemented using the access()
system call. This usually doesn't matter, but if your program
is setuid or setgid it means that these tests will give you
the answer for the real user ID and group ID, rather than the
effective user ID and group ID.
On Windows, there are no symlinks, so testing for
G_FILE_TEST_IS_SYMLINK will always return FALSE. Testing for
G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
its name indicates that it is executable, checking for well-known
extensions and those listed in the PATHEXT environment variable.
Returns
whether a test was TRUE
g_mkstemp ()
gint
g_mkstemp (gchar *tmpl);
Opens a temporary file. See the mkstemp() documentation
on most UNIX-like systems.
The parameter is a string that should follow the rules for
mkstemp() templates, i.e. contain the string "XXXXXX".
g_mkstemp() is slightly more flexible than mkstemp() in that the
sequence does not have to occur at the very end of the template.
The X string will be modified to form the name of a file that
didn't exist. The string should be in the GLib file name encoding.
Most importantly, on Windows it should be in UTF-8.
[skip]
Returns
A file handle (as from open()) to the file
opened for reading and writing. The file is opened in binary
mode on platforms where there is a difference. The file handle
should be closed with close(). In case of errors, -1 is
returned and errno will be set.
g_mkstemp_full ()
gint
g_mkstemp_full (gchar *tmpl,
gint flags,
gint mode);
Opens a temporary file. See the mkstemp() documentation
on most UNIX-like systems.
The parameter is a string that should follow the rules for
mkstemp() templates, i.e. contain the string "XXXXXX".
g_mkstemp_full() is slightly more flexible than mkstemp()
in that the sequence does not have to occur at the very end of the
template and you can pass a mode
and additional flags
. The X
string will be modified to form the name of a file that didn't exist.
The string should be in the GLib file name encoding. Most importantly,
on Windows it should be in UTF-8.
[skip]
Returns
A file handle (as from open()) to the file
opened for reading and writing. The file handle should be
closed with close(). In case of errors, -1 is returned
and errno will be set.
Since: 2.22
g_file_open_tmp ()
gint
g_file_open_tmp (const gchar *tmpl,
gchar **name_used,
GError **error);
Opens a file for writing in the preferred directory for temporary
files (as returned by g_get_tmp_dir()).
tmpl
should be a string in the GLib file name encoding containing
a sequence of six 'X' characters, as the parameter to g_mkstemp().
However, unlike these functions, the template should only be a
basename, no directory components are allowed. If template is
NULL, a default template is used.
Note that in contrast to g_mkstemp() (and mkstemp()) tmpl
is not
modified, and might thus be a read-only literal string.
Upon success, and if name_used
is non-NULL, the actual name used
is returned in name_used
. This string should be freed with g_free()
when not needed any longer. The returned name is in the GLib file
name encoding.
Returns
A file handle (as from open()) to the file opened for
reading and writing. The file is opened in binary mode on platforms
where there is a difference. The file handle should be closed with
close(). In case of errors, -1 is returned and error
will be set.
g_file_read_link ()
gchar *
g_file_read_link (const gchar *filename,
GError **error);
Reads the contents of the symbolic link filename
like the POSIX
readlink() function. The returned string is in the encoding used
for filenames. Use g_filename_to_utf8() to convert it to UTF-8.
Returns
A newly-allocated string with the contents of
the symbolic link, or NULL if an error occurred.
[type filename]
Since: 2.4
g_mkdir_with_parents ()
gint
g_mkdir_with_parents (const gchar *pathname,
gint mode);
Create a directory if it doesn't already exist. Create intermediate
parent directories as needed, too.
Returns
0 if the directory already exists, or was successfully
created. Returns -1 if an error occurred, with errno set.
Since: 2.8
g_mkdtemp ()
gchar *
g_mkdtemp (gchar *tmpl);
Creates a temporary directory. See the mkdtemp() documentation
on most UNIX-like systems.
The parameter is a string that should follow the rules for
mkdtemp() templates, i.e. contain the string "XXXXXX".
g_mkdtemp() is slightly more flexible than mkdtemp() in that the
sequence does not have to occur at the very end of the template.
The X string will be modified to form the name of a directory that
didn't exist.
The string should be in the GLib file name encoding. Most importantly,
on Windows it should be in UTF-8.
If you are going to be creating a temporary directory inside the
directory returned by g_get_tmp_dir(), you might want to use
g_dir_make_tmp() instead.
[skip]
Returns
A pointer to tmpl
, which has been
modified to hold the directory name. In case of errors, NULL is
returned and errno will be set.
[nullable][type filename]
Since: 2.30
g_mkdtemp_full ()
gchar *
g_mkdtemp_full (gchar *tmpl,
gint mode);
Creates a temporary directory. See the mkdtemp() documentation
on most UNIX-like systems.
The parameter is a string that should follow the rules for
mkdtemp() templates, i.e. contain the string "XXXXXX".
g_mkdtemp_full() is slightly more flexible than mkdtemp() in that the
sequence does not have to occur at the very end of the template
and you can pass a mode
. The X string will be modified to form
the name of a directory that didn't exist. The string should be
in the GLib file name encoding. Most importantly, on Windows it
should be in UTF-8.
If you are going to be creating a temporary directory inside the
directory returned by g_get_tmp_dir(), you might want to use
g_dir_make_tmp() instead.
[skip]
Returns
A pointer to tmpl
, which has been
modified to hold the directory name. In case of errors, NULL is
returned, and errno will be set.
[nullable][type filename]
Since: 2.30
g_dir_make_tmp ()
gchar *
g_dir_make_tmp (const gchar *tmpl,
GError **error);
Creates a subdirectory in the preferred directory for temporary
files (as returned by g_get_tmp_dir()).
tmpl
should be a string in the GLib file name encoding containing
a sequence of six 'X' characters, as the parameter to g_mkstemp().
However, unlike these functions, the template should only be a
basename, no directory components are allowed. If template is
NULL, a default template is used.
Note that in contrast to g_mkdtemp() (and mkdtemp()) tmpl
is not
modified, and might thus be a read-only literal string.
Returns
The actual name used. This string
should be freed with g_free() when not needed any longer and is
is in the GLib file name encoding. In case of errors, NULL is
returned and error
will be set.
[type filename]
Since: 2.30
g_dir_open ()
GDir *
g_dir_open (const gchar *path,
guint flags,
GError **error);
Opens a directory for reading. The names of the files in the
directory can then be retrieved using g_dir_read_name(). Note
that the ordering is not defined.
Returns
a newly allocated GDir on success, NULL on failure.
If non-NULL, you must free the result with g_dir_close()
when you are finished with it.
g_dir_read_name ()
const gchar *
g_dir_read_name (GDir *dir);
Retrieves the name of another entry in the directory, or NULL.
The order of entries returned from this function is not defined,
and may vary by file system or other operating-system dependent
factors.
NULL may also be returned in case of errors. On Unix, you can
check errno to find out if NULL was returned because of an error.
On Unix, the '.' and '..' entries are omitted, and the returned
name is in the on-disk encoding.
On Windows, as is true of all GLib functions which operate on
filenames, the returned name is in UTF-8.
Returns
The entry's name or NULL if there are no
more entries. The return value is owned by GLib and
must not be modified or freed.
[type filename]
g_dir_rewind ()
void
g_dir_rewind (GDir *dir);
Resets the given directory. The next call to g_dir_read_name()
will return the first entry again.
g_dir_close ()
void
g_dir_close (GDir *dir);
Closes the directory and deallocates all related resources.
g_mapped_file_new ()
GMappedFile *
g_mapped_file_new (const gchar *filename,
gboolean writable,
GError **error);
Maps a file into memory. On UNIX, this is using the mmap() function.
If writable
is TRUE, the mapped buffer may be modified, otherwise
it is an error to modify the mapped buffer. Modifications to the buffer
are not visible to other processes mapping the same file, and are not
written back to the file.
Note that modifications of the underlying file might affect the contents
of the GMappedFile. Therefore, mapping should only be used if the file
will not be modified, or if all modifications of the file are done
atomically (e.g. using g_file_set_contents()).
If filename
is the name of an empty, regular file, the function
will successfully return an empty GMappedFile. In other cases of
size 0 (e.g. device files such as /dev/null), error
will be set
to the GFileError value G_FILE_ERROR_INVAL.
Since: 2.8
g_mapped_file_new_from_fd ()
GMappedFile *
g_mapped_file_new_from_fd (gint fd,
gboolean writable,
GError **error);
Maps a file into memory. On UNIX, this is using the mmap() function.
If writable
is TRUE, the mapped buffer may be modified, otherwise
it is an error to modify the mapped buffer. Modifications to the buffer
are not visible to other processes mapping the same file, and are not
written back to the file.
Note that modifications of the underlying file might affect the contents
of the GMappedFile. Therefore, mapping should only be used if the file
will not be modified, or if all modifications of the file are done
atomically (e.g. using g_file_set_contents()).
Since: 2.32
g_mapped_file_ref ()
GMappedFile *
g_mapped_file_ref (GMappedFile *file);
Increments the reference count of file
by one. It is safe to call
this function from any thread.
Since: 2.22
g_mapped_file_unref ()
void
g_mapped_file_unref (GMappedFile *file);
Decrements the reference count of file
by one. If the reference count
drops to 0, unmaps the buffer of file
and frees it.
It is safe to call this function from any thread.
Since 2.22
g_mapped_file_get_length ()
gsize
g_mapped_file_get_length (GMappedFile *file);
Returns the length of the contents of a GMappedFile.
Returns
the length of the contents of file
.
Since: 2.8
g_mapped_file_get_contents ()
gchar *
g_mapped_file_get_contents (GMappedFile *file);
Returns the contents of a GMappedFile.
Note that the contents may not be zero-terminated,
even if the GMappedFile is backed by a text file.
If the file is empty then NULL is returned.
Returns
the contents of file
, or NULL.
Since: 2.8
g_mapped_file_get_bytes ()
GBytes *
g_mapped_file_get_bytes (GMappedFile *file);
Creates a new GBytes which references the data mapped from file
.
The mapped contents of the file must not be modified after creating this
bytes object, because a GBytes should be immutable.
Returns
A newly allocated GBytes referencing data
from file
.
[transfer full]
Since: 2.34
g_open ()
int
g_open (const gchar *filename,
int flags,
int mode);
A wrapper for the POSIX open() function. The open() function is
used to convert a pathname into a file descriptor.
On POSIX systems file descriptors are implemented by the operating
system. On Windows, it's the C library that implements open() and
file descriptors. The actual Win32 API for opening files is quite
different, see MSDN documentation for CreateFile(). The Win32 API
uses file handles, which are more randomish integers, not small
integers like file descriptors.
Because file descriptors are specific to the C library on Windows,
the file descriptor returned by this function makes sense only to
functions in the same C library. Thus if the GLib-using code uses a
different C library than GLib does, the file descriptor returned by
this function cannot be passed to C library functions like write()
or read().
See your C library manual for more details about open().
Returns
a new file descriptor, or -1 if an error occurred.
The return value can be used exactly like the return value
from open().
Since: 2.6
g_rename ()
int
g_rename (const gchar *oldfilename,
const gchar *newfilename);
A wrapper for the POSIX rename() function. The rename() function
renames a file, moving it between directories if required.
See your C library manual for more details about how rename() works
on your system. It is not possible in general on Windows to rename
a file that is open to some process.
Returns
0 if the renaming succeeded, -1 if an error occurred
Since: 2.6
g_mkdir ()
int
g_mkdir (const gchar *filename,
int mode);
A wrapper for the POSIX mkdir() function. The mkdir() function
attempts to create a directory with the given name and permissions.
The mode argument is ignored on Windows.
See your C library manual for more details about mkdir().
Returns
0 if the directory was successfully created, -1 if an error
occurred
Since: 2.6
g_stat ()
int
g_stat (const gchar *filename,
GStatBuf *buf);
A wrapper for the POSIX stat() function. The stat() function
returns information about a file. On Windows the stat() function in
the C library checks only the FAT-style READONLY attribute and does
not look at the ACL at all. Thus on Windows the protection bits in
the st_mode
field are a fabrication of little use.
On Windows the Microsoft C libraries have several variants of the
stat struct and stat() function with names like _stat(), _stat32(),
_stat32i64() and _stat64i32(). The one used here is for 32-bit code
the one with 32-bit size and time fields, specifically called _stat32().
In Microsoft's compiler, by default struct stat means one with
64-bit time fields while in MinGW struct stat is the legacy one
with 32-bit fields. To hopefully clear up this messs, the gstdio.h
header defines a type GStatBuf which is the appropriate struct type
depending on the platform and/or compiler being used. On POSIX it
is just struct stat, but note that even on POSIX platforms, stat()
might be a macro.
See your C library manual for more details about stat().
Returns
0 if the information was successfully retrieved,
-1 if an error occurred
Since: 2.6
g_lstat ()
int
g_lstat (const gchar *filename,
GStatBuf *buf);
A wrapper for the POSIX lstat() function. The lstat() function is
like stat() except that in the case of symbolic links, it returns
information about the symbolic link itself and not the file that it
refers to. If the system does not support symbolic links g_lstat()
is identical to g_stat().
See your C library manual for more details about lstat().
Returns
0 if the information was successfully retrieved,
-1 if an error occurred
Since: 2.6
g_unlink ()
int
g_unlink (const gchar *filename);
A wrapper for the POSIX unlink() function. The unlink() function
deletes a name from the filesystem. If this was the last link to the
file and no processes have it opened, the diskspace occupied by the
file is freed.
See your C library manual for more details about unlink(). Note
that on Windows, it is in general not possible to delete files that
are open to some process, or mapped into memory.
Returns
0 if the name was successfully deleted, -1 if an error
occurred
Since: 2.6
g_remove ()
int
g_remove (const gchar *filename);
A wrapper for the POSIX remove() function. The remove() function
deletes a name from the filesystem.
See your C library manual for more details about how remove() works
on your system. On Unix, remove() removes also directories, as it
calls unlink() for files and rmdir() for directories. On Windows,
although remove() in the C library only works for files, this
function tries first remove() and then if that fails rmdir(), and
thus works for both files and directories. Note however, that on
Windows, it is in general not possible to remove a file that is
open to some process, or mapped into memory.
If this function fails on Windows you can't infer too much from the
errno value. rmdir() is tried regardless of what caused remove() to
fail. Any errno value set by remove() will be overwritten by that
set by rmdir().
Returns
0 if the file was successfully removed, -1 if an error
occurred
Since: 2.6
g_rmdir ()
int
g_rmdir (const gchar *filename);
A wrapper for the POSIX rmdir() function. The rmdir() function
deletes a directory from the filesystem.
See your C library manual for more details about how rmdir() works
on your system.
Returns
0 if the directory was successfully removed, -1 if an error
occurred
Since: 2.6
g_fopen ()
FILE *
g_fopen (const gchar *filename,
const gchar *mode);
A wrapper for the stdio fopen() function. The fopen() function
opens a file and associates a new stream with it.
Because file descriptors are specific to the C library on Windows,
and a file descriptor is part of the FILE struct, the FILE* returned
by this function makes sense only to functions in the same C library.
Thus if the GLib-using code uses a different C library than GLib does,
the FILE* returned by this function cannot be passed to C library
functions like fprintf() or fread().
See your C library manual for more details about fopen().
As close() and fclose() are part of the C library, this implies that it is
currently impossible to close a file if the application C library and the C library
used by GLib are different. Convenience functions like g_file_set_contents()
avoid this problem.
Returns
A FILE* if the file was successfully opened, or NULL if
an error occurred
Since: 2.6
g_freopen ()
FILE *
g_freopen (const gchar *filename,
const gchar *mode,
FILE *stream);
A wrapper for the POSIX freopen() function. The freopen() function
opens a file and associates it with an existing stream.
See your C library manual for more details about freopen().
Returns
A FILE* if the file was successfully opened, or NULL if
an error occurred.
Since: 2.6
g_fsync ()
gint
g_fsync (gint fd);
A wrapper for the POSIX fsync() function (_commit() on Windows).
The fsync() function is used to synchronize a file's in-core
state with that of the disk.
See the C library manual for more details about fsync().
Returns
0 on success, or -1 if an error occurred.
The return value can be used exactly like the return value from fsync().
Since: 2.64
g_chmod ()
int
g_chmod (const gchar *filename,
int mode);
A wrapper for the POSIX chmod() function. The chmod() function is
used to set the permissions of a file system object.
On Windows the file protection mechanism is not at all POSIX-like,
and the underlying chmod() function in the C library just sets or
clears the FAT-style READONLY attribute. It does not touch any
ACL. Software that needs to manage file permissions on Windows
exactly should use the Win32 API.
See your C library manual for more details about chmod().
Returns
0 if the operation succeeded, -1 on error
Since: 2.8
g_access ()
int
g_access (const gchar *filename,
int mode);
A wrapper for the POSIX access() function. This function is used to
test a pathname for one or several of read, write or execute
permissions, or just existence.
On Windows, the file protection mechanism is not at all POSIX-like,
and the underlying function in the C library only checks the
FAT-style READONLY attribute, and does not look at the ACL of a
file at all. This function is this in practise almost useless on
Windows. Software that needs to handle file permissions on Windows
more exactly should use the Win32 API.
See your C library manual for more details about access().
Returns
zero if the pathname refers to an existing file system
object that has all the tested permissions, or -1 otherwise
or on error.
Since: 2.8
g_creat ()
int
g_creat (const gchar *filename,
int mode);
A wrapper for the POSIX creat() function. The creat() function is
used to convert a pathname into a file descriptor, creating a file
if necessary.
On POSIX systems file descriptors are implemented by the operating
system. On Windows, it's the C library that implements creat() and
file descriptors. The actual Windows API for opening files is
different, see MSDN documentation for CreateFile(). The Win32 API
uses file handles, which are more randomish integers, not small
integers like file descriptors.
Because file descriptors are specific to the C library on Windows,
the file descriptor returned by this function makes sense only to
functions in the same C library. Thus if the GLib-using code uses a
different C library than GLib does, the file descriptor returned by
this function cannot be passed to C library functions like write()
or read().
See your C library manual for more details about creat().
Returns
a new file descriptor, or -1 if an error occurred.
The return value can be used exactly like the return value
from creat().
Since: 2.8
g_chdir ()
int
g_chdir (const gchar *path);
A wrapper for the POSIX chdir() function. The function changes the
current directory of the process to path
.
See your C library manual for more details about chdir().
Returns
0 on success, -1 if an error occurred.
Since: 2.8
g_utime ()
int
g_utime (const gchar *filename,
struct utimbuf *utb);
A wrapper for the POSIX utime() function. The utime() function
sets the access and modification timestamps of a file.
See your C library manual for more details about how utime() works
on your system.
Returns
0 if the operation was successful, -1 if an error occurred
Since: 2.18
g_close ()
gboolean
g_close (gint fd,
GError **error);
This wraps the close() call; in case of error, errno will be
preserved, but the error will also be stored as a GError in error
.
Besides using GError, there is another major reason to prefer this
function over the call provided by the system; on Unix, it will
attempt to correctly handle EINTR, which has platform-specific
semantics.
Returns
TRUE on success, FALSE if there was an error.
Since: 2.36