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>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
<!-- ##### 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:
-@G_FILE_ERROR_ISDIR:
-@G_FILE_ERROR_ACCES:
-@G_FILE_ERROR_NAMETOOLONG:
-@G_FILE_ERROR_NOENT:
-@G_FILE_ERROR_NOTDIR:
-@G_FILE_ERROR_NXIO:
-@G_FILE_ERROR_NODEV:
-@G_FILE_ERROR_ROFS:
-@G_FILE_ERROR_TXTBSY:
-@G_FILE_ERROR_FAULT:
-@G_FILE_ERROR_LOOP:
-@G_FILE_ERROR_NOSPC:
-@G_FILE_ERROR_NOMEM:
-@G_FILE_ERROR_MFILE:
-@G_FILE_ERROR_NFILE:
-@G_FILE_ERROR_BADF:
-@G_FILE_ERROR_INVAL:
-@G_FILE_ERROR_PIPE:
-@G_FILE_ERROR_AGAIN:
-@G_FILE_ERROR_INTR:
-@G_FILE_ERROR_IO:
-@G_FILE_ERROR_PERM:
-@G_FILE_ERROR_FAILED:
+@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: The underlying file system of the specified file
+ does not support memory 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:
-@G_FILE_TEST_IS_SYMLINK:
-@G_FILE_TEST_IS_DIR:
-@G_FILE_TEST_IS_EXECUTABLE:
-@G_FILE_TEST_EXISTS:
+@G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file (not a directory).
+ Note that this test will also return %TRUE if the tested file is a symlink
+ to a regular file.
+@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>
@Returns:
+<!-- ##### FUNCTION g_file_set_contents ##### -->
+<para>
+
+</para>
+
+@filename:
+@contents:
+@length:
+@error:
+@Returns:
+
+
<!-- ##### FUNCTION g_file_test ##### -->
<para>
@Returns:
+<!-- ##### FUNCTION g_mkstemp_full ##### -->
+<para>
+
+</para>
+
+@tmpl:
+@flags:
+@mode:
+@Returns:
+
+
<!-- ##### FUNCTION g_file_open_tmp ##### -->
<para>
@Returns:
+<!-- ##### FUNCTION g_file_read_link ##### -->
+<para>
+
+</para>
+
+@filename:
+@error:
+@Returns:
+
+
+<!-- ##### FUNCTION g_mkdir_with_parents ##### -->
+<para>
+
+</para>
+
+@pathname:
+@mode:
+@Returns:
+
+
+<!-- ##### FUNCTION g_mkdtemp ##### -->
+<para>
+
+</para>
+
+@tmpl:
+@Returns:
+
+
+<!-- ##### FUNCTION g_mkdtemp_full ##### -->
+<para>
+
+</para>
+
+@tmpl:
+@mode:
+@Returns:
+
+
+<!-- ##### FUNCTION g_dir_make_tmp ##### -->
+<para>
+
+</para>
+
+@tmpl:
+@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:
+
+
+<!-- ##### STRUCT GMappedFile ##### -->
+<para>
+The #GMappedFile represents a file mapping created with
+g_mapped_file_new(). It has only private members and should
+not be accessed directly.
+</para>
+
+
+<!-- ##### FUNCTION g_mapped_file_new ##### -->
+<para>
+
+</para>
+
+@filename:
+@writable:
+@error:
+@Returns:
+
+
+<!-- ##### FUNCTION g_mapped_file_ref ##### -->
+<para>
+
+</para>
+
+@file:
+@Returns:
+
+
+<!-- ##### FUNCTION g_mapped_file_unref ##### -->
+<para>
+
+</para>
+
+@file:
+
+
+<!-- ##### FUNCTION g_mapped_file_free ##### -->
+<para>
+
+</para>
+
+@file:
+
+
+<!-- ##### FUNCTION g_mapped_file_get_length ##### -->
+<para>
+
+</para>
+
+@file:
+@Returns:
+
+
+<!-- ##### FUNCTION g_mapped_file_get_contents ##### -->
+<para>
+
+</para>
+
+@file:
+@Returns:
+
+
+<!-- ##### 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:
+
+
+<!-- ##### TYPEDEF GStatBuf ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### 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_rmdir ##### -->
+<para>
+
+</para>
+
+@filename:
+@Returns:
+
+
+<!-- ##### FUNCTION g_fopen ##### -->
+<para>
+
+</para>
+
+@filename:
+@mode:
+@Returns:
+
+
+<!-- ##### FUNCTION g_freopen ##### -->
+<para>
+
+</para>
+
+@filename:
+@mode:
+@stream:
+@Returns:
+
+
+<!-- ##### FUNCTION g_chmod ##### -->
+<para>
+
+</para>
+
+@filename:
+@mode:
+@Returns:
+
+
+<!-- ##### FUNCTION g_access ##### -->
+<para>
+
+</para>
+
+@filename:
+@mode:
+@Returns:
+
+
+<!-- ##### FUNCTION g_creat ##### -->
+<para>
+
+</para>
+
+@filename:
+@mode:
+@Returns:
+
+
+<!-- ##### FUNCTION g_chdir ##### -->
+<para>
+
+</para>
+
+@path:
+@Returns:
+
+
+<!-- ##### FUNCTION g_utime ##### -->
+<para>
+
+</para>
+
+@filename:
+@utb:
+@Returns:
+
+
projects / platform / upstream / glib.git / blobdiff