From 7154d44c5c5a23e0a631f571bc689ff43995ee82 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 1 Oct 2011 23:03:09 -0400 Subject: [PATCH] Move file utility docs inline --- docs/reference/glib/tmpl/.gitignore | 1 + docs/reference/glib/tmpl/fileutils.sgml | 536 ------------------------ glib/gdir.c | 6 + glib/gfileutils.c | 135 ++++++ glib/gmappedfile.c | 10 +- 5 files changed, 151 insertions(+), 537 deletions(-) delete mode 100644 docs/reference/glib/tmpl/fileutils.sgml diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index ea3575dd2..042045848 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -14,6 +14,7 @@ datasets.sgml datalist.sgml date-time.sgml error_reporting.sgml +fileutils.sgml ghostutils.sgml gregex.sgml gurifuncs.sgml diff --git a/docs/reference/glib/tmpl/fileutils.sgml b/docs/reference/glib/tmpl/fileutils.sgml deleted file mode 100644 index 45cf73c0b..000000000 --- a/docs/reference/glib/tmpl/fileutils.sgml +++ /dev/null @@ -1,536 +0,0 @@ - -File Utilities - - -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 -G_FILENAME_ENCODING 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(). - - - - - - - - - - - - - - - -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_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. - - - -Error domain for file operations. Errors in this domain will -be from the #GFileError enumeration. See #GError for information on -error domains. - - - - - - -A test to perform on a file using g_file_test(). - - -@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. - - - - - - -@err_no: -@Returns: - - - - - - - -@filename: -@contents: -@length: -@error: -@Returns: - - - - - - - -@filename: -@contents: -@length: -@error: -@Returns: - - - - - - - -@filename: -@test: -@Returns: - - - - - - - -@tmpl: -@Returns: - - - - - - - -@tmpl: -@flags: -@mode: -@Returns: - - - - - - - -@tmpl: -@name_used: -@error: -@Returns: - - - - - - - -@filename: -@error: -@Returns: - - - - - - - -@pathname: -@mode: -@Returns: - - - - - - - -@tmpl: -@Returns: - - - - - - - -@tmpl: -@mode: -@Returns: - - - - - - - -@tmpl: -@error: -@Returns: - - - - -An opaque structure representing an opened directory. - - - - - - - - -@path: -@flags: -@error: -@Returns: - - - - - - - -@dir: -@Returns: - - - - - - - -@dir: - - - - - - - -@dir: - - - - -The #GMappedFile represents a file mapping created with -g_mapped_file_new(). It has only private members and should -not be accessed directly. - - - - - - - - -@filename: -@writable: -@error: -@Returns: - - - - - - - -@file: -@Returns: - - - - - - - -@file: - - - - - - - -@file: - - - - - - - -@file: -@Returns: - - - - - - - -@file: -@Returns: - - - - - - - -@filename: -@flags: -@mode: -@Returns: - - - - - - - -@oldfilename: -@newfilename: -@Returns: - - - - - - - -@filename: -@mode: -@Returns: - - - - - - - - - - - - - -@filename: -@buf: -@Returns: - - - - - - - -@filename: -@buf: -@Returns: - - - - - - - -@filename: -@Returns: - - - - - - - -@filename: -@Returns: - - - - - - - -@filename: -@Returns: - - - - - - - -@filename: -@mode: -@Returns: - - - - - - - -@filename: -@mode: -@stream: -@Returns: - - - - - - - -@filename: -@mode: -@Returns: - - - - - - - -@filename: -@mode: -@Returns: - - - - - - - -@filename: -@mode: -@Returns: - - - - - - - -@path: -@Returns: - - - - - - - -@filename: -@utb: -@Returns: - - diff --git a/glib/gdir.c b/glib/gdir.c index 9919bbb14..3173ae70e 100644 --- a/glib/gdir.c +++ b/glib/gdir.c @@ -48,6 +48,12 @@ #include "../build/win32/dirent/wdirent.c" #endif +/** + * GDir: + * + * An opaque structure representing an opened directory. + */ + struct _GDir { #ifdef G_OS_WIN32 diff --git a/glib/gfileutils.c b/glib/gfileutils.c index 83105312d..5e7e28695 100644 --- a/glib/gfileutils.c +++ b/glib/gfileutils.c @@ -58,6 +58,141 @@ #include #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 + * G_FILENAME_ENCODING 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 diff --git a/glib/gmappedfile.c b/glib/gmappedfile.c index 57af4118d..4a73827ec 100644 --- a/glib/gmappedfile.c +++ b/glib/gmappedfile.c @@ -69,7 +69,15 @@ #define MAP_FAILED ((void *) -1) #endif -struct _GMappedFile +/** + * GMappedFile: + * + * The #GMappedFile represents a file mapping created with + * g_mapped_file_new(). It has only private members and should + * not be accessed directly. + */ + +struct _GMappedFile { gchar *contents; gsize length;