mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-03-03 14:42:10 +01:00
340 lines
8.2 KiB
Plaintext
340 lines
8.2 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
File Utilities
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
various file-related functions.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
There is a group of functions which wrap the common POSIX functions
|
|
dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(),
|
|
g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these
|
|
wrappers is to make it possible to handle file names with any Unicode
|
|
characters in them on Windows without having to use ifdefs and the
|
|
wide character API in the application code.
|
|
</para>
|
|
<para>
|
|
The pathname argument should be in the GLib file name encoding. On
|
|
POSIX this is the actual on-disk encoding which might correspond to
|
|
the locale settings of the process (or the
|
|
<envar>G_FILENAME_ENCODING</envar> environment variable), or not.
|
|
</para>
|
|
<para>
|
|
On Windows the GLib file name encoding is UTF-8. Note that the
|
|
Microsoft C library does not use UTF-8, but has separate APIs for
|
|
current system code page and wide characters (UTF-16). The GLib
|
|
wrappers call the wide character API if present (on modern Windows
|
|
systems), otherwise convert to/from the system code page.
|
|
</para>
|
|
|
|
<para>
|
|
Another group of functions allows to open and read directories
|
|
in the GLib file name encoding. These are g_dir_open(),
|
|
g_dir_read_name(), g_dir_rewind(), g_dir_close().
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ENUM GFileError ##### -->
|
|
<para>
|
|
Values corresponding to <literal>errno</literal> codes returned from file operations
|
|
on UNIX. Unlike <literal>errno</literal> codes, #GFileError values are available on
|
|
all systems, even Windows. The exact meaning of each code depends on what
|
|
sort of file operation you were performing; the UNIX documentation
|
|
gives more details. The following error code descriptions come
|
|
from the GNU C Library manual, and are under the copyright
|
|
of that manual.
|
|
</para>
|
|
|
|
<para>
|
|
It's not very portable to make detailed assumptions about exactly
|
|
which errors will be returned from a given operation. Some errors
|
|
don't occur on some systems, etc., sometimes there are subtle
|
|
differences in when a system will report a given error, etc.
|
|
</para>
|
|
|
|
@G_FILE_ERROR_EXIST: Operation not permitted; only the owner of the
|
|
file (or other resource) or processes with special privileges can
|
|
perform the operation.
|
|
@G_FILE_ERROR_ISDIR: File is a directory; you cannot open a directory
|
|
for writing, or create or remove hard links to it.
|
|
@G_FILE_ERROR_ACCES: Permission denied; the file permissions do not
|
|
allow the attempted operation.
|
|
@G_FILE_ERROR_NAMETOOLONG: Filename too long.
|
|
@G_FILE_ERROR_NOENT: No such file or directory. This is a "file
|
|
doesn't exist" error for ordinary files that are referenced in
|
|
contexts where they are expected to already exist.
|
|
@G_FILE_ERROR_NOTDIR: A file that isn't a directory was specified when
|
|
a directory is required.
|
|
@G_FILE_ERROR_NXIO: No such device or address. The system tried to
|
|
use the device represented by a file you specified, and it
|
|
couldn't find the device. This can mean that the device file was
|
|
installed incorrectly, or that the physical device is missing or
|
|
not correctly attached to the computer.
|
|
@G_FILE_ERROR_NODEV: This file is of a type that doesn't support
|
|
mapping.
|
|
@G_FILE_ERROR_ROFS: The directory containing the new link can't be
|
|
modified because it's on a read-only file system.
|
|
@G_FILE_ERROR_TXTBSY: Text file busy.
|
|
@G_FILE_ERROR_FAULT: You passed in a pointer to bad memory.
|
|
(GLib won't reliably return this, don't pass in pointers to bad
|
|
memory.)
|
|
@G_FILE_ERROR_LOOP: Too many levels of symbolic links were encountered
|
|
in looking up a file name. This often indicates a cycle of symbolic
|
|
links.
|
|
@G_FILE_ERROR_NOSPC: No space left on device; write operation on a
|
|
file failed because the disk is full.
|
|
@G_FILE_ERROR_NOMEM: No memory available. The system cannot allocate
|
|
more virtual memory because its capacity is full.
|
|
@G_FILE_ERROR_MFILE: The current process has too many files open and
|
|
can't open any more. Duplicate descriptors do count toward this
|
|
limit.
|
|
@G_FILE_ERROR_NFILE: There are too many distinct file openings in the
|
|
entire system.
|
|
@G_FILE_ERROR_BADF: Bad file descriptor; for example, I/O on a
|
|
descriptor that has been closed or reading from a descriptor open
|
|
only for writing (or vice versa).
|
|
@G_FILE_ERROR_INVAL: Invalid argument. This is used to indicate
|
|
various kinds of problems with passing the wrong argument to a
|
|
library function.
|
|
@G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the
|
|
other end of a pipe. Every library function that returns this
|
|
error code also generates a `SIGPIPE' signal; this signal
|
|
terminates the program if not handled or blocked. Thus, your
|
|
program will never actually see this code unless it has handled or
|
|
blocked `SIGPIPE'.
|
|
@G_FILE_ERROR_AGAIN: Resource temporarily unavailable; the call might
|
|
work if you try again later.
|
|
@G_FILE_ERROR_INTR: Interrupted function call; an asynchronous signal
|
|
occurred and prevented completion of the call. When this
|
|
happens, you should try the call again.
|
|
@G_FILE_ERROR_IO: Input/output error; usually used for physical read
|
|
or write errors. i.e. the disk or other physical device hardware
|
|
is returning errors.
|
|
@G_FILE_ERROR_PERM: Operation not permitted; only the owner of the
|
|
file (or other resource) or processes with special privileges can
|
|
perform the operation.
|
|
@G_FILE_ERROR_NOSYS: Function not implemented; this indicates that the
|
|
system is missing some functionality.
|
|
@G_FILE_ERROR_FAILED: Does not correspond to a UNIX error code; this
|
|
is the standard "failed for unspecified reason" error code present in
|
|
all #GError error code enumerations. Returned if no specific
|
|
code applies.
|
|
|
|
<!-- ##### MACRO G_FILE_ERROR ##### -->
|
|
<para>
|
|
Error domain for file operations. Errors in this domain will
|
|
be from the #GFileError enumeration. See #GError for information on
|
|
error domains.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### ENUM GFileTest ##### -->
|
|
<para>
|
|
A test to perform on a file using g_file_test().
|
|
</para>
|
|
|
|
@G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file (not a symlink or directory)
|
|
@G_FILE_TEST_IS_SYMLINK: %TRUE if the file is a symlink.
|
|
@G_FILE_TEST_IS_DIR: %TRUE if the file is a directory.
|
|
@G_FILE_TEST_IS_EXECUTABLE: %TRUE if the file is executable.
|
|
@G_FILE_TEST_EXISTS: %TRUE if the file exists. It may or may not be a regular file.
|
|
|
|
<!-- ##### FUNCTION g_file_error_from_errno ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@err_no:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_file_get_contents ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@filename:
|
|
@contents:
|
|
@length:
|
|
@error:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_file_test ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@filename:
|
|
@test:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_mkstemp ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@tmpl:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_file_open_tmp ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@tmpl:
|
|
@name_used:
|
|
@error:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_file_read_link ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@filename:
|
|
@error:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### STRUCT GDir ##### -->
|
|
<para>
|
|
An opaque structure representing an opened directory.
|
|
</para>
|
|
|
|
|
|
<!-- ##### FUNCTION g_dir_open ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@path:
|
|
@flags:
|
|
@error:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_dir_read_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dir:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_dir_rewind ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dir:
|
|
|
|
|
|
<!-- ##### FUNCTION g_dir_close ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dir:
|
|
|
|
|
|
<!-- ##### FUNCTION g_open ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@filename:
|
|
@flags:
|
|
@mode:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_rename ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@oldfilename:
|
|
@newfilename:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_mkdir ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@filename:
|
|
@mode:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_stat ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@filename:
|
|
@buf:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_lstat ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@filename:
|
|
@buf:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_unlink ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@filename:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_remove ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@filename:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_fopen ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@filename:
|
|
@mode:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_freopen ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@filename:
|
|
@mode:
|
|
@stream:
|
|
@Returns:
|
|
|
|
|