25
@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})
26
Reads an entire file into allocated memory, with good error checking.
28
If the call was successful, it returns @samp{@code{#t}} and sets @var{contents}
29
to the file contents and @var{length} to the length of the file contents in
30
bytes. The string stored in @var{contents} will be nul-terminated, so for text
31
files you can pass @samp{@code{#f}} for the @var{length} argument. If the call
32
was not successful, it returns @samp{@code{#f}} and sets @var{error}. The error
33
domain is @code{<g-file-error>}. Possible error codes are those in the
34
@code{<g-file-error>} enumeration. In the error case, @var{contents} is set to
35
@samp{@code{#f}} and @var{length} is set to zero.
39
name of a file to read contents from, in the GLib file name encoding
42
location to store an allocated string
45
location to store length in bytes of the contents, or @samp{@code{#f}}
48
return location for a @code{<g-error>}, or @samp{@code{#f}}
51
@samp{@code{#t}} on success, @samp{@code{#f}} if an error occurred
57
@deffn Function g-file-test (filename@tie{}@code{mchars}) (test@tie{}@code{<g-file-test>}) @result{}@tie{} (ret@tie{}@code{bool})
58
Returns @samp{@code{#t}} if any of the tests in the bitfield @var{test} are
59
@samp{@code{#t}}. For example, @samp{(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)}
60
will return @samp{@code{#t}} if the file exists; the check whether it's a
61
directory doesn't matter since the existence test is @samp{@code{#t}}. With the
62
current set of available tests, there's no point passing in more than one test
65
Apart from @samp{G_FILE_TEST_IS_SYMLINK} all tests follow symbolic links, so for
66
a symbolic link to a regular file @code{g-file-test} will return
67
@samp{@code{#t}} for both @samp{G_FILE_TEST_IS_SYMLINK} and
68
@samp{G_FILE_TEST_IS_REGULAR}.
70
Note, that for a dangling symbolic link @code{g-file-test} will return
71
@samp{@code{#t}} for @samp{G_FILE_TEST_IS_SYMLINK} and @samp{@code{#f}} for all
74
You should never use @code{g-file-test} to test whether it is safe to perform an
75
operation, because there is always the possibility of the condition changing
76
before you actually perform the operation. For example, you might think you
77
could use @samp{G_FILE_TEST_IS_SYMLINK} to know whether it is is safe to write
78
to a file without being tricked into writing into a different location. It
83
/* DON'T DO THIS */
84
if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) @{
85
fd = g_open (filename, O_WRONLY);
86
/* write to fd */
90
Another thing to note is that @samp{G_FILE_TEST_EXISTS} and
91
@samp{G_FILE_TEST_IS_EXECUTABLE} are implemented using the @code{access} system
92
call. This usually doesn't matter, but if your program is setuid or setgid it
93
means that these tests will give you the answer for the real user ID and group
94
ID, rather than the effective user ID and group ID.
96
On Windows, there are no symlinks, so testing for @samp{G_FILE_TEST_IS_SYMLINK}
97
will always return @samp{@code{#f}}. Testing for
98
@samp{G_FILE_TEST_IS_EXECUTABLE} will just check that the file exists and its
99
name indicates that it is executable, checking for well-known extensions and
100
those listed in the @samp{PATHEXT} environment variable.
104
a filename to test in the GLib file name encoding
107
bitfield of @code{<g-file-test>} flags
110
whether a test was @samp{@code{#t}}
116
@deffn Function g-mkstemp (tmpl@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{int})
117
Opens a temporary file. See the @code{mkstemp} documentation on most UNIX-like
120
The parameter is a string that should follow the rules for @code{mkstemp}
121
templates, i.e. contain the string "XXXXXX". @code{g-mkstemp} is slightly more
122
flexible than @code{mkstemp} in that the sequence does not have to occur at the
123
very end of the template. The X string will be modified to form the name of a
124
file that didn't exist. The string should be in the GLib file name encoding.
125
Most importantly, on Windows it should be in UTF-8.
132
A file handle (as from @code{open}) to the file opened for reading and writing.
133
The file is opened in binary mode on platforms where there is a difference. The
134
file handle should be closed with @code{close}. In case of errors, -1 is
141
@deffn Function g-file-open-tmp (tmpl@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{int}) (name_used@tie{}@code{mchars})
142
Opens a file for writing in the preferred directory for temporary files (as
143
returned by @code{g-get-tmp-dir}).
145
@var{tmpl} should be a string in the GLib file name encoding containing a
146
sequence of six 'X' characters, as the parameter to @code{g-mkstemp}. However,
147
unlike these functions, the template should only be a basename, no directory
148
components are allowed. If template is @samp{@code{#f}}, a default template is
151
Note that in contrast to @code{g-mkstemp} (and @code{mkstemp}) @var{tmpl} is not
152
modified, and might thus be a read-only literal string.
154
The actual name used is returned in @var{name-used} if non-@samp{@code{#f}}.
155
This string should be freed with @code{g-free} when not needed any longer. The
156
returned name is in the GLib file name encoding.
160
Template for file name, as in @code{g-mkstemp}, basename only, or
161
@samp{@code{#f}}, to a default template
164
location to store actual name used
167
return location for a @code{<g-error>}
170
A file handle (as from @code{open}) to the file opened for reading and writing.
171
The file is opened in binary mode on platforms where there is a difference. The
172
file handle should be closed with @code{close}. In case of errors, -1 is
173
returned and @var{error} will be set.
179
@deffn Function g-file-read-link (filename@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
180
Reads the contents of the symbolic link @var{filename} like the POSIX
181
@code{readlink} function. The returned string is in the encoding used for
182
filenames. Use @code{g-filename-to-utf8} to convert it to UTF-8.
189
return location for a @code{<g-error>}
192
A newly allocated string with the contents of the symbolic link, or
193
@samp{@code{#f}} if an error occurred.
202
26
@c %end of fragment
added
removed
glib/doc/glib/defuns-fileutils.xml.texi
