
@c %start of fragment

@deffn Function g-file-error-from-errno  (err_no@tie{}@code{int}) @result{}@tie{} (ret@tie{}@code{<g-file-error>})
Gets a @code{<g-file-error>} constant based on the passed-in @var{errno}. For
example, if you pass in @samp{EEXIST} this function returns
@code{<g-file-error-exist>}. Unlike @var{errno} values, you can portably assume
that all @code{<g-file-error>} values will exist.

Normally a @code{<g-file-error>} value goes into a @code{<g-error>} returned
from a function that manipulates files. So you would use
@code{g-file-error-from-errno} when constructing a @code{<g-error>}.

@table @var
@item err-no
an "errno" value

@item ret
@code{<g-file-error>} corresponding to the given @var{errno}

@end table

@end deffn

@deffn Function g-file-get-contents  (filename@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool}) (contents@tie{}@code{mchars}) (length@tie{}@code{size_t})
Reads an entire file into allocated memory, with good error checking.

If the call was successful, it returns @samp{@code{#t}} and sets @var{contents}
to the file contents and @var{length} to the length of the file contents in
bytes. The string stored in @var{contents} will be nul-terminated, so for text
files you can pass @samp{@code{#f}} for the @var{length} argument. If the call
was not successful, it returns @samp{@code{#f}} and sets @var{error}. The error
domain is @code{<g-file-error>}. Possible error codes are those in the
@code{<g-file-error>} enumeration. In the error case, @var{contents} is set to
@samp{@code{#f}} and @var{length} is set to zero.

@table @var
@item filename
name of a file to read contents from, in the GLib file name encoding

@item contents
location to store an allocated string

@item length
location to store length in bytes of the contents, or @samp{@code{#f}}

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
@samp{@code{#t}} on success, @samp{@code{#f}} if an error occurred

@end table

@end deffn

@deffn Function g-file-test  (filename@tie{}@code{mchars}) (test@tie{}@code{<g-file-test>}) @result{}@tie{} (ret@tie{}@code{bool})
Returns @samp{@code{#t}} if any of the tests in the bitfield @var{test} are
@samp{@code{#t}}. For example, @samp{(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)}
will return @samp{@code{#t}} if the file exists; the check whether it's a
directory doesn't matter since the existence test is @samp{@code{#t}}. With the
current set of available tests, there's no point passing in more than one test
at a time.

Apart from @samp{G_FILE_TEST_IS_SYMLINK} all tests follow symbolic links, so for
a symbolic link to a regular file @code{g-file-test} will return
@samp{@code{#t}} for both @samp{G_FILE_TEST_IS_SYMLINK} and
@samp{G_FILE_TEST_IS_REGULAR}.

Note, that for a dangling symbolic link @code{g-file-test} will return
@samp{@code{#t}} for @samp{G_FILE_TEST_IS_SYMLINK} and @samp{@code{#f}} for all
other flags.

You should never use @code{g-file-test} to test whether it is safe to perform an
operation, because there is always the possibility of the condition changing
before you actually perform the operation. For example, you might think you
could use @samp{G_FILE_TEST_IS_SYMLINK} to know whether it is is safe to write
to a file without being tricked into writing into a different location. It
doesn't work!

@example 

/&#x002A; DON'T DO THIS &#x002A;/
 if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) @{
   fd = g_open (filename, O_WRONLY);
   /&#x002A; write to fd &#x002A;/
 @}
@end example

Another thing to note is that @samp{G_FILE_TEST_EXISTS} and
@samp{G_FILE_TEST_IS_EXECUTABLE} are implemented using the @code{access} system
call. This usually doesn't matter, but if your program is setuid or setgid it
means that these tests will give you the answer for the real user ID and group
ID, rather than the effective user ID and group ID.

On Windows, there are no symlinks, so testing for @samp{G_FILE_TEST_IS_SYMLINK}
will always return @samp{@code{#f}}. Testing for
@samp{G_FILE_TEST_IS_EXECUTABLE} will just check that the file exists and its
name indicates that it is executable, checking for well-known extensions and
those listed in the @samp{PATHEXT} environment variable.

@table @var
@item filename
a filename to test in the GLib file name encoding

@item test
bitfield of @code{<g-file-test>} flags

@item ret
whether a test was @samp{@code{#t}}

@end table

@end deffn

@deffn Function g-mkstemp  (tmpl@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{int})
Opens a temporary file. See the @code{mkstemp} documentation on most UNIX-like
systems.

The parameter is a string that should follow the rules for @code{mkstemp}
templates, i.e. contain the string "XXXXXX". @code{g-mkstemp} is slightly more
flexible than @code{mkstemp} in that the sequence does not have to occur at the
very end of the template. The X string will be modified to form the name of a
file that didn't exist. The string should be in the GLib file name encoding.
Most importantly, on Windows it should be in UTF-8.

@table @var
@item tmpl
template filename

@item ret
A file handle (as from @code{open}) 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 @code{close}. In case of errors, -1 is
returned.

@end table

@end deffn

@deffn Function g-file-open-tmp  (tmpl@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{int}) (name_used@tie{}@code{mchars})
Opens a file for writing in the preferred directory for temporary files (as
returned by @code{g-get-tmp-dir}).

@var{tmpl} should be a string in the GLib file name encoding containing a
sequence of six 'X' characters, as the parameter to @code{g-mkstemp}. However,
unlike these functions, the template should only be a basename, no directory
components are allowed. If template is @samp{@code{#f}}, a default template is
used.

Note that in contrast to @code{g-mkstemp} (and @code{mkstemp}) @var{tmpl} is not
modified, and might thus be a read-only literal string.

The actual name used is returned in @var{name-used} if non-@samp{@code{#f}}.
This string should be freed with @code{g-free} when not needed any longer. The
returned name is in the GLib file name encoding.

@table @var
@item tmpl
Template for file name, as in @code{g-mkstemp}, basename only, or
@samp{@code{#f}}, to a default template

@item name-used
location to store actual name used

@item error
return location for a @code{<g-error>}

@item ret
A file handle (as from @code{open}) 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 @code{close}. In case of errors, -1 is
returned and @var{error} will be set.

@end table

@end deffn

@deffn Function g-file-read-link  (filename@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Reads the contents of the symbolic link @var{filename} like the POSIX
@code{readlink} function. The returned string is in the encoding used for
filenames. Use @code{g-filename-to-utf8} to convert it to UTF-8.

@table @var
@item filename
the symbolic link

@item error
return location for a @code{<g-error>}

@item ret
A newly allocated string with the contents of the symbolic link, or
@samp{@code{#f}} if an error occurred.

@end table

Since 2.4

@end deffn


@c %end of fragment
