Move file utility docs inline

This commit is contained in:
Matthias Clasen
2011-10-01 23:03:09 -04:00
parent ca77b0e252
commit 7154d44c5c
5 changed files with 151 additions and 537 deletions

View File

@@ -58,6 +58,141 @@
#include <sys/vfs.h>
#endif
/**
* SECTION:fileutils
* @title: File Utilities
* @short_description: various file-related functions
*
* 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.
*
* 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.
*
* 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.
*
* 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().
*/
/**
* GFileError:
* @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.
*
* Values corresponding to @errno codes returned from file operations
* on UNIX. Unlike @errno 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.
*
* 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.
*/
/**
* G_FILE_ERROR:
*
* Error domain for file operations. Errors in this domain will
* be from the #GFileError enumeration. See #GError for information
* on error domains.
*/
/**
* GFileTest:
* @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.
*
* A test to perform on a file using g_file_test().
*/
/**
* g_mkdir_with_parents:
* @pathname: a pathname in the GLib file name encoding