fileutils.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<entry><literal>TRUE</literal> if the file is a regular file (not a symlink or directory)
</entry>
</row>
<row>
<entry><literal>G_FILE_TEST_IS_SYMLINK</literal></entry>
<entry><literal>TRUE</literal> if the file is a symlink.
</entry>
</row>
<row>
<entry><literal>G_FILE_TEST_IS_DIR</literal></entry>
<entry><literal>TRUE</literal> if the file is a directory.
</entry>
</row>
<row>
<entry><literal>G_FILE_TEST_IS_EXECUTABLE</literal></entry>
<entry><literal>TRUE</literal> if the file is executable.
</entry>
</row>
<row>
<entry><literal>G_FILE_TEST_EXISTS</literal></entry>
<entry><literal>TRUE</literal> if the file exists. It may or may not be a regular file.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-file-error-from-errno">g_file_error_from_errno ()</title>
<programlisting><link linkend="GFileError">GFileError</link>  g_file_error_from_errno         (<link linkend="gint">gint</link> err_no);</programlisting>
<para>
Gets a <link linkend="GFileError">GFileError</link> constant based on the passed-in <parameter>errno</parameter>.
For example, if you pass in <literal>EEXIST</literal> this function returns
<link linkend="G-FILE-ERROR-EXIST-CAPS">G_FILE_ERROR_EXIST</link>. Unlike <parameter>errno</parameter> values, you can portably
assume that all <link linkend="GFileError">GFileError</link> values will exist.
</para>
<para>
Normally a <link linkend="GFileError">GFileError</link> value goes into a <link linkend="GError">GError</link> returned
from a function that manipulates files. So you would use
<link linkend="g-file-error-from-errno">g_file_error_from_errno</link>() when constructing a <link linkend="GError">GError</link>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>err_no</parameter>&nbsp;:</entry>
<entry> an "errno" value
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <link linkend="GFileError">GFileError</link> corresponding to the given <parameter>errno</parameter>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-file-get-contents">g_file_get_contents ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_file_get_contents             (const <link linkend="gchar">gchar</link> *filename,
                                             <link linkend="gchar">gchar</link> **contents,
                                             <link linkend="gsize">gsize</link> *length,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Reads an entire file into allocated memory, with good error
checking. If <parameter>error</parameter> is set, <literal>FALSE</literal> is returned, and <parameter>contents</parameter> is set
to <literal>NULL</literal>. If <literal>TRUE</literal> is returned, <parameter>error</parameter> will not be set, and <parameter>contents</parameter>
will be set to the file contents.  The string stored in <parameter>contents</parameter>
will be nul-terminated, so for text files you can pass <literal>NULL</literal> for the
<parameter>length</parameter> argument.  The error domain is <link linkend="G-FILE-ERROR-CAPS">G_FILE_ERROR</link>. Possible
error codes are those in the <link linkend="GFileError">GFileError</link> enumeration.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> a file to read contents from
</entry></row>
<row><entry align="right"><parameter>contents</parameter>&nbsp;:</entry>
<entry> location to store an allocated string
</entry></row>
<row><entry align="right"><parameter>length</parameter>&nbsp;:</entry>
<entry> location to store length in bytes of the contents
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> return location for a <link linkend="GError">GError</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> on success, <literal>FALSE</literal> if error is set
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-file-test">g_file_test ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_file_test                     (const <link linkend="gchar">gchar</link> *filename,
                                             <link linkend="GFileTest">GFileTest</link> test);</programlisting>
<para>
Returns <literal>TRUE</literal> if any of the tests in the bitfield <parameter>test</parameter> are
<literal>TRUE</literal>. For example, <literal>(G_FILE_TEST_EXISTS | 
G_FILE_TEST_IS_DIR)</literal> will return <literal>TRUE</literal> if the file exists; 
the check whether it's a directory doesn't matter since the existence 
test is <literal>TRUE</literal>. With the current set of available tests, there's no point
passing in more than one test at a time.
</para>
<para>
Apart from <link linkend="G-FILE-TEST-IS-SYMLINK-CAPS">G_FILE_TEST_IS_SYMLINK</link> all tests follow symbolic links,
so for a symbolic link to a regular file <link linkend="g-file-test">g_file_test</link>() will return
<literal>TRUE</literal> for both <link linkend="G-FILE-TEST-IS-SYMLINK-CAPS">G_FILE_TEST_IS_SYMLINK</link> and <link linkend="G-FILE-TEST-IS-REGULAR-CAPS">G_FILE_TEST_IS_REGULAR</link>.
</para>
<para>
Note, that for a dangling symbolic link <link linkend="g-file-test">g_file_test</link>() will return
<literal>TRUE</literal> for <link linkend="G-FILE-TEST-IS-SYMLINK-CAPS">G_FILE_TEST_IS_SYMLINK</link> and <literal>FALSE</literal> for all other flags.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> a filename to test
</entry></row>
<row><entry align="right"><parameter>test</parameter>&nbsp;:</entry>
<entry> bitfield of <link linkend="GFileTest">GFileTest</link> flags
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> whether a test was <literal>TRUE</literal>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-mkstemp">g_mkstemp ()</title>
<programlisting>int         g_mkstemp                       (char *tmpl);</programlisting>
<para>
Opens a temporary file. See the <function><link linkend="mkstemp">mkstemp</link>()</function> documentation
on most UNIX-like systems. This is a portability wrapper, which simply calls 
<function><link linkend="mkstemp">mkstemp</link>()</function> on systems that have it, and implements 
it in GLib otherwise.
</para>
<para>
The parameter is a string that should match the rules for
<function><link linkend="mkstemp">mkstemp</link>()</function>, i.e. end in "XXXXXX". The X string will 
be modified to form the name of a file that didn't exist.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tmpl</parameter>&nbsp;:</entry>
<entry> template filename
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A file handle (as from <function><link linkend="open">open</link>()</function>) 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 <function><link linkend="close">close</link>()</function>. In case of errors, -1 is returned.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-file-open-tmp">g_file_open_tmp ()</title>
<programlisting>int         g_file_open_tmp                 (const char *tmpl,
                                             char **name_used,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Opens a file for writing in the preferred directory for temporary
files (as returned by <link linkend="g-get-tmp-dir">g_get_tmp_dir</link>()). 
</para>
<para>
<parameter>tmpl</parameter> should be a string ending with six 'X' characters, as the
parameter to <link linkend="g-mkstemp">g_mkstemp</link>() (or <function><link linkend="mkstemp">mkstemp</link>()</function>). 
However, unlike these functions, the template should only be a 
basename, no directory components are allowed. If template is <literal>NULL</literal>, 
a default template is used.
</para>
<para>
Note that in contrast to <link linkend="g-mkstemp">g_mkstemp</link>() (and <function><link linkend="mkstemp">mkstemp</link>()</function>) 
<parameter>tmpl</parameter> is not modified, and might thus be a read-only literal string.
</para>
<para>
The actual name used is returned in <parameter>name_used</parameter> if non-<literal>NULL</literal>. This
string should be freed with <link linkend="g-free">g_free</link>() when not needed any longer.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tmpl</parameter>&nbsp;:</entry>
<entry> Template for file name, as in <link linkend="g-mkstemp">g_mkstemp</link>(), basename only
</entry></row>
<row><entry align="right"><parameter>name_used</parameter>&nbsp;:</entry>
<entry> location to store actual name used
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> return location for a <link linkend="GError">GError</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A file handle (as from <function><link linkend="open">open</link>()</function>) 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 <function><link linkend="close">close</link>()</function>. In case of errors, -1 is returned 
and <parameter>error</parameter> will be set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GDir">struct GDir</title>
<programlisting>struct GDir;</programlisting>
<para>
An opaque structure representing an opened directory.
</para></refsect2>
<refsect2>
<title><anchor id="g-dir-open">g_dir_open ()</title>
<programlisting><link linkend="GDir">GDir</link>*       g_dir_open                      (const <link linkend="gchar">gchar</link> *path,
                                             <link linkend="guint">guint</link> flags,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Opens a directory for reading. The names of the files
in the directory can then be retrieved using
<link linkend="g-dir-get-name">g_dir_get_name</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>path</parameter>&nbsp;:</entry>
<entry> the path to the directory you are interested in
</entry></row>
<row><entry align="right"><parameter>flags</parameter>&nbsp;:</entry>
<entry> Currently must be set to 0. Reserved for future use.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> return location for a <link linkend="GError">GError</link>, or <literal>NULL</literal>.
        If non-<literal>NULL</literal>, an error will be set if and only if
        g_dir_open_fails.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly allocated <link linkend="GDir">GDir</link> on success, <literal>NULL</literal> on failure.
  If non-<literal>NULL</literal>, you must free the result with <link linkend="g-dir-close">g_dir_close</link>()
  when you are finished with it.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-dir-read-name">g_dir_read_name ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_dir_read_name       (<link linkend="GDir">GDir</link> *dir);</programlisting>
<para>
Retrieves the name of the next entry in the directory.
The '.' and '..' entries are omitted.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dir</parameter>&nbsp;:</entry>
<entry> a <link linkend="GDir">GDir</link>* created by <link linkend="g-dir-open">g_dir_open</link>()
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The entries name or <literal>NULL</literal> if there are no 
  more entries. The return value is owned by GLib and
  must not be modified or freed.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-dir-rewind">g_dir_rewind ()</title>
<programlisting>void        g_dir_rewind                    (<link linkend="GDir">GDir</link> *dir);</programlisting>
<para>
Resets the given directory. The next call to <link linkend="g-dir-read-name">g_dir_read_name</link>()
will return the first entry again.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dir</parameter>&nbsp;:</entry>
<entry> a <link linkend="GDir">GDir</link>* created by <link linkend="g-dir-open">g_dir_open</link>()
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-dir-close">g_dir_close ()</title>
<programlisting>void        g_dir_close                     (<link linkend="GDir">GDir</link> *dir);</programlisting>
<para>
Closes the directory and deallocates all related resources.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dir</parameter>&nbsp;:</entry>
<entry> a <link linkend="GDir">GDir</link>* created by <link linkend="g-dir-open">g_dir_open</link>()
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>