2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
5
<!ENTITY version SYSTEM "version.xml">
7
<refentry id="glib-File-Utilities">
9
<refentrytitle role="top_of_page" id="glib-File-Utilities.top_of_page">File Utilities</refentrytitle>
10
<manvolnum>3</manvolnum>
11
<refmiscinfo>GLIB Library</refmiscinfo>
15
<refname>File Utilities</refname>
16
<refpurpose>various file-related functions</refpurpose>
19
<refsynopsisdiv id="glib-File-Utilities.synopsis" role="synopsis">
20
<title role="synopsis.title">Synopsis</title>
24
#include <glib.h>
25
#include <glib/gstdio.h>
27
enum <link linkend="GFileError">GFileError</link>;
28
#define <link linkend="G-FILE-ERROR--CAPS">G_FILE_ERROR</link>
29
enum <link linkend="GFileTest">GFileTest</link>;
30
<link linkend="GFileError">GFileError</link> <link linkend="g-file-error-from-errno">g_file_error_from_errno</link> (<link linkend="gint">gint</link> err_no);
31
<link linkend="gboolean">gboolean</link> <link linkend="g-file-get-contents">g_file_get_contents</link> (const <link linkend="gchar">gchar</link> *filename,
32
<link linkend="gchar">gchar</link> **contents,
33
<link linkend="gsize">gsize</link> *length,
34
<link linkend="GError">GError</link> **error);
35
<link linkend="gboolean">gboolean</link> <link linkend="g-file-set-contents">g_file_set_contents</link> (const <link linkend="gchar">gchar</link> *filename,
36
const <link linkend="gchar">gchar</link> *contents,
37
<link linkend="gssize">gssize</link> length,
38
<link linkend="GError">GError</link> **error);
39
<link linkend="gboolean">gboolean</link> <link linkend="g-file-test">g_file_test</link> (const <link linkend="gchar">gchar</link> *filename,
40
<link linkend="GFileTest">GFileTest</link> test);
41
<link linkend="gint">gint</link> <link linkend="g-mkstemp">g_mkstemp</link> (<link linkend="gchar">gchar</link> *tmpl);
42
<link linkend="gint">gint</link> <link linkend="g-mkstemp-full">g_mkstemp_full</link> (<link linkend="gchar">gchar</link> *tmpl,
43
<link linkend="int">int</link> flags,
44
<link linkend="int">int</link> mode);
45
<link linkend="gint">gint</link> <link linkend="g-file-open-tmp">g_file_open_tmp</link> (const <link linkend="gchar">gchar</link> *tmpl,
46
<link linkend="gchar">gchar</link> **name_used,
47
<link linkend="GError">GError</link> **error);
48
<link linkend="gchar">gchar</link> * <link linkend="g-file-read-link">g_file_read_link</link> (const <link linkend="gchar">gchar</link> *filename,
49
<link linkend="GError">GError</link> **error);
50
<link linkend="int">int</link> <link linkend="g-mkdir-with-parents">g_mkdir_with_parents</link> (const <link linkend="gchar">gchar</link> *pathname,
51
<link linkend="int">int</link> mode);
53
<link linkend="GDir">GDir</link>;
54
<link linkend="GDir">GDir</link> * <link linkend="g-dir-open">g_dir_open</link> (const <link linkend="gchar">gchar</link> *path,
55
<link linkend="guint">guint</link> flags,
56
<link linkend="GError">GError</link> **error);
57
const <link linkend="gchar">gchar</link> * <link linkend="g-dir-read-name">g_dir_read_name</link> (<link linkend="GDir">GDir</link> *dir);
58
<link linkend="void">void</link> <link linkend="g-dir-rewind">g_dir_rewind</link> (<link linkend="GDir">GDir</link> *dir);
59
<link linkend="void">void</link> <link linkend="g-dir-close">g_dir_close</link> (<link linkend="GDir">GDir</link> *dir);
61
<link linkend="GMappedFile">GMappedFile</link>;
62
<link linkend="GMappedFile">GMappedFile</link> * <link linkend="g-mapped-file-new">g_mapped_file_new</link> (const <link linkend="gchar">gchar</link> *filename,
63
<link linkend="gboolean">gboolean</link> writable,
64
<link linkend="GError">GError</link> **error);
65
<link linkend="GMappedFile">GMappedFile</link> * <link linkend="g-mapped-file-ref">g_mapped_file_ref</link> (<link linkend="GMappedFile">GMappedFile</link> *file);
66
<link linkend="void">void</link> <link linkend="g-mapped-file-unref">g_mapped_file_unref</link> (<link linkend="GMappedFile">GMappedFile</link> *file);
67
<link linkend="void">void</link> <link linkend="g-mapped-file-free">g_mapped_file_free</link> (<link linkend="GMappedFile">GMappedFile</link> *file);
68
<link linkend="gsize">gsize</link> <link linkend="g-mapped-file-get-length">g_mapped_file_get_length</link> (<link linkend="GMappedFile">GMappedFile</link> *file);
69
<link linkend="gchar">gchar</link> * <link linkend="g-mapped-file-get-contents">g_mapped_file_get_contents</link> (<link linkend="GMappedFile">GMappedFile</link> *file);
71
<link linkend="int">int</link> <link linkend="g-open">g_open</link> (const <link linkend="gchar">gchar</link> *filename,
72
<link linkend="int">int</link> flags,
73
<link linkend="int">int</link> mode);
74
<link linkend="int">int</link> <link linkend="g-rename">g_rename</link> (const <link linkend="gchar">gchar</link> *oldfilename,
75
const <link linkend="gchar">gchar</link> *newfilename);
76
<link linkend="int">int</link> <link linkend="g-mkdir">g_mkdir</link> (const <link linkend="gchar">gchar</link> *filename,
77
<link linkend="int">int</link> mode);
78
<link linkend="int">int</link> <link linkend="g-stat">g_stat</link> (const <link linkend="gchar">gchar</link> *filename,
79
<link linkend="struct--g-stat-struct">struct _g_stat_struct</link> *buf);
80
<link linkend="int">int</link> <link linkend="g-lstat">g_lstat</link> (const <link linkend="gchar">gchar</link> *filename,
81
<link linkend="struct--g-stat-struct">struct _g_stat_struct</link> *buf);
82
<link linkend="int">int</link> <link linkend="g-unlink">g_unlink</link> (const <link linkend="gchar">gchar</link> *filename);
83
<link linkend="int">int</link> <link linkend="g-remove">g_remove</link> (const <link linkend="gchar">gchar</link> *filename);
84
<link linkend="int">int</link> <link linkend="g-rmdir">g_rmdir</link> (const <link linkend="gchar">gchar</link> *filename);
85
<link linkend="FILE--CAPS">FILE</link> * <link linkend="g-fopen">g_fopen</link> (const <link linkend="gchar">gchar</link> *filename,
86
const <link linkend="gchar">gchar</link> *mode);
87
<link linkend="FILE--CAPS">FILE</link> * <link linkend="g-freopen">g_freopen</link> (const <link linkend="gchar">gchar</link> *filename,
88
const <link linkend="gchar">gchar</link> *mode,
89
<link linkend="FILE--CAPS">FILE</link> *stream);
90
<link linkend="int">int</link> <link linkend="g-chmod">g_chmod</link> (const <link linkend="gchar">gchar</link> *filename,
91
<link linkend="int">int</link> mode);
92
<link linkend="int">int</link> <link linkend="g-access">g_access</link> (const <link linkend="gchar">gchar</link> *filename,
93
<link linkend="int">int</link> mode);
94
<link linkend="int">int</link> <link linkend="g-creat">g_creat</link> (const <link linkend="gchar">gchar</link> *filename,
95
<link linkend="int">int</link> mode);
96
<link linkend="int">int</link> <link linkend="g-chdir">g_chdir</link> (const <link linkend="gchar">gchar</link> *path);
97
<link linkend="int">int</link> <link linkend="g-utime">g_utime</link> (const <link linkend="gchar">gchar</link> *filename,
98
<link linkend="struct-utimbuf">struct utimbuf</link> *utb);
110
<refsect1 id="glib-File-Utilities.description" role="desc">
111
<title role="desc.title">Description</title>
113
There is a group of functions which wrap the common POSIX functions
114
dealing with filenames (<link linkend="g-open"><function>g_open()</function></link>, <link linkend="g-rename"><function>g_rename()</function></link>, <link linkend="g-mkdir"><function>g_mkdir()</function></link>, <link linkend="g-stat"><function>g_stat()</function></link>,
115
<link linkend="g-unlink"><function>g_unlink()</function></link>, <link linkend="g-remove"><function>g_remove()</function></link>, <link linkend="g-fopen"><function>g_fopen()</function></link>, <link linkend="g-freopen"><function>g_freopen()</function></link>). The point of these
116
wrappers is to make it possible to handle file names with any Unicode
117
characters in them on Windows without having to use ifdefs and the
118
wide character API in the application code.
121
The pathname argument should be in the GLib file name encoding. On
122
POSIX this is the actual on-disk encoding which might correspond to
123
the locale settings of the process (or the
124
<envar>G_FILENAME_ENCODING</envar> environment variable), or not.
127
On Windows the GLib file name encoding is UTF-8. Note that the
128
Microsoft C library does not use UTF-8, but has separate APIs for
129
current system code page and wide characters (UTF-16). The GLib
130
wrappers call the wide character API if present (on modern Windows
131
systems), otherwise convert to/from the system code page.
134
Another group of functions allows to open and read directories
135
in the GLib file name encoding. These are <link linkend="g-dir-open"><function>g_dir_open()</function></link>,
136
<link linkend="g-dir-read-name"><function>g_dir_read_name()</function></link>, <link linkend="g-dir-rewind"><function>g_dir_rewind()</function></link>, <link linkend="g-dir-close"><function>g_dir_close()</function></link>.
140
<refsect1 id="glib-File-Utilities.details" role="details">
141
<title role="details.title">Details</title>
142
<refsect2 id="GFileError" role="enum">
143
<title>enum GFileError</title>
144
<indexterm zone="GFileError"><primary sortas="FileError">GFileError</primary></indexterm><programlisting>typedef enum
149
G_FILE_ERROR_NAMETOOLONG,
174
Values corresponding to <literal>errno</literal> codes returned from file operations
175
on UNIX. Unlike <literal>errno</literal> codes, <link linkend="GFileError"><type>GFileError</type></link> values are available on
176
all systems, even Windows. The exact meaning of each code depends on what
177
sort of file operation you were performing; the UNIX documentation
178
gives more details. The following error code descriptions come
179
from the GNU C Library manual, and are under the copyright
183
It's not very portable to make detailed assumptions about exactly
184
which errors will be returned from a given operation. Some errors
185
don't occur on some systems, etc., sometimes there are subtle
186
differences in when a system will report a given error, etc.
187
</para><variablelist role="enum">
188
<varlistentry id="G-FILE-ERROR-EXIST--CAPS" role="constant">
189
<term><literal>G_FILE_ERROR_EXIST</literal></term>
190
<listitem><simpara>Operation not permitted; only the owner of the
191
file (or other resource) or processes with special privileges can
192
perform the operation.
193
</simpara></listitem>
195
<varlistentry id="G-FILE-ERROR-ISDIR--CAPS" role="constant">
196
<term><literal>G_FILE_ERROR_ISDIR</literal></term>
197
<listitem><simpara>File is a directory; you cannot open a directory
198
for writing, or create or remove hard links to it.
199
</simpara></listitem>
201
<varlistentry id="G-FILE-ERROR-ACCES--CAPS" role="constant">
202
<term><literal>G_FILE_ERROR_ACCES</literal></term>
203
<listitem><simpara>Permission denied; the file permissions do not
204
allow the attempted operation.
205
</simpara></listitem>
207
<varlistentry id="G-FILE-ERROR-NAMETOOLONG--CAPS" role="constant">
208
<term><literal>G_FILE_ERROR_NAMETOOLONG</literal></term>
209
<listitem><simpara>Filename too long.
210
</simpara></listitem>
212
<varlistentry id="G-FILE-ERROR-NOENT--CAPS" role="constant">
213
<term><literal>G_FILE_ERROR_NOENT</literal></term>
214
<listitem><simpara>No such file or directory. This is a "file
215
doesn't exist" error for ordinary files that are referenced in
216
contexts where they are expected to already exist.
217
</simpara></listitem>
219
<varlistentry id="G-FILE-ERROR-NOTDIR--CAPS" role="constant">
220
<term><literal>G_FILE_ERROR_NOTDIR</literal></term>
221
<listitem><simpara>A file that isn't a directory was specified when
222
a directory is required.
223
</simpara></listitem>
225
<varlistentry id="G-FILE-ERROR-NXIO--CAPS" role="constant">
226
<term><literal>G_FILE_ERROR_NXIO</literal></term>
227
<listitem><simpara>No such device or address. The system tried to
228
use the device represented by a file you specified, and it
229
couldn't find the device. This can mean that the device file was
230
installed incorrectly, or that the physical device is missing or
231
not correctly attached to the computer.
232
</simpara></listitem>
234
<varlistentry id="G-FILE-ERROR-NODEV--CAPS" role="constant">
235
<term><literal>G_FILE_ERROR_NODEV</literal></term>
236
<listitem><simpara>This file is of a type that doesn't support
238
</simpara></listitem>
240
<varlistentry id="G-FILE-ERROR-ROFS--CAPS" role="constant">
241
<term><literal>G_FILE_ERROR_ROFS</literal></term>
242
<listitem><simpara>The directory containing the new link can't be
243
modified because it's on a read-only file system.
244
</simpara></listitem>
246
<varlistentry id="G-FILE-ERROR-TXTBSY--CAPS" role="constant">
247
<term><literal>G_FILE_ERROR_TXTBSY</literal></term>
248
<listitem><simpara>Text file busy.
249
</simpara></listitem>
251
<varlistentry id="G-FILE-ERROR-FAULT--CAPS" role="constant">
252
<term><literal>G_FILE_ERROR_FAULT</literal></term>
253
<listitem><simpara>You passed in a pointer to bad memory.
254
(GLib won't reliably return this, don't pass in pointers to bad
256
</simpara></listitem>
258
<varlistentry id="G-FILE-ERROR-LOOP--CAPS" role="constant">
259
<term><literal>G_FILE_ERROR_LOOP</literal></term>
260
<listitem><simpara>Too many levels of symbolic links were encountered
261
in looking up a file name. This often indicates a cycle of symbolic
263
</simpara></listitem>
265
<varlistentry id="G-FILE-ERROR-NOSPC--CAPS" role="constant">
266
<term><literal>G_FILE_ERROR_NOSPC</literal></term>
267
<listitem><simpara>No space left on device; write operation on a
268
file failed because the disk is full.
269
</simpara></listitem>
271
<varlistentry id="G-FILE-ERROR-NOMEM--CAPS" role="constant">
272
<term><literal>G_FILE_ERROR_NOMEM</literal></term>
273
<listitem><simpara>No memory available. The system cannot allocate
274
more virtual memory because its capacity is full.
275
</simpara></listitem>
277
<varlistentry id="G-FILE-ERROR-MFILE--CAPS" role="constant">
278
<term><literal>G_FILE_ERROR_MFILE</literal></term>
279
<listitem><simpara>The current process has too many files open and
280
can't open any more. Duplicate descriptors do count toward this
282
</simpara></listitem>
284
<varlistentry id="G-FILE-ERROR-NFILE--CAPS" role="constant">
285
<term><literal>G_FILE_ERROR_NFILE</literal></term>
286
<listitem><simpara>There are too many distinct file openings in the
288
</simpara></listitem>
290
<varlistentry id="G-FILE-ERROR-BADF--CAPS" role="constant">
291
<term><literal>G_FILE_ERROR_BADF</literal></term>
292
<listitem><simpara>Bad file descriptor; for example, I/O on a
293
descriptor that has been closed or reading from a descriptor open
294
only for writing (or vice versa).
295
</simpara></listitem>
297
<varlistentry id="G-FILE-ERROR-INVAL--CAPS" role="constant">
298
<term><literal>G_FILE_ERROR_INVAL</literal></term>
299
<listitem><simpara>Invalid argument. This is used to indicate
300
various kinds of problems with passing the wrong argument to a
302
</simpara></listitem>
304
<varlistentry id="G-FILE-ERROR-PIPE--CAPS" role="constant">
305
<term><literal>G_FILE_ERROR_PIPE</literal></term>
306
<listitem><simpara>Broken pipe; there is no process reading from the
307
other end of a pipe. Every library function that returns this
308
error code also generates a `SIGPIPE' signal; this signal
309
terminates the program if not handled or blocked. Thus, your
310
program will never actually see this code unless it has handled or
312
</simpara></listitem>
314
<varlistentry id="G-FILE-ERROR-AGAIN--CAPS" role="constant">
315
<term><literal>G_FILE_ERROR_AGAIN</literal></term>
316
<listitem><simpara>Resource temporarily unavailable; the call might
317
work if you try again later.
318
</simpara></listitem>
320
<varlistentry id="G-FILE-ERROR-INTR--CAPS" role="constant">
321
<term><literal>G_FILE_ERROR_INTR</literal></term>
322
<listitem><simpara>Interrupted function call; an asynchronous signal
323
occurred and prevented completion of the call. When this
324
happens, you should try the call again.
325
</simpara></listitem>
327
<varlistentry id="G-FILE-ERROR-IO--CAPS" role="constant">
328
<term><literal>G_FILE_ERROR_IO</literal></term>
329
<listitem><simpara>Input/output error; usually used for physical read
330
or write errors. i.e. the disk or other physical device hardware
332
</simpara></listitem>
334
<varlistentry id="G-FILE-ERROR-PERM--CAPS" role="constant">
335
<term><literal>G_FILE_ERROR_PERM</literal></term>
336
<listitem><simpara>Operation not permitted; only the owner of the
337
file (or other resource) or processes with special privileges can
338
perform the operation.
339
</simpara></listitem>
341
<varlistentry id="G-FILE-ERROR-NOSYS--CAPS" role="constant">
342
<term><literal>G_FILE_ERROR_NOSYS</literal></term>
343
<listitem><simpara>Function not implemented; this indicates that the
344
system is missing some functionality.
345
</simpara></listitem>
347
<varlistentry id="G-FILE-ERROR-FAILED--CAPS" role="constant">
348
<term><literal>G_FILE_ERROR_FAILED</literal></term>
349
<listitem><simpara>Does not correspond to a UNIX error code; this
350
is the standard "failed for unspecified reason" error code present in
351
all <link linkend="GError"><type>GError</type></link> error code enumerations. Returned if no specific
353
</simpara></listitem>
355
</variablelist></refsect2>
356
<refsect2 id="G-FILE-ERROR--CAPS" role="macro">
357
<title>G_FILE_ERROR</title>
358
<indexterm zone="G-FILE-ERROR--CAPS"><primary sortas="FILE_ERROR">G_FILE_ERROR</primary></indexterm><programlisting>#define G_FILE_ERROR g_file_error_quark ()
361
Error domain for file operations. Errors in this domain will
362
be from the <link linkend="GFileError"><type>GFileError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on
365
<refsect2 id="GFileTest" role="enum">
366
<title>enum GFileTest</title>
367
<indexterm zone="GFileTest"><primary sortas="FileTest">GFileTest</primary></indexterm><programlisting>typedef enum
369
G_FILE_TEST_IS_REGULAR = 1 << 0,
370
G_FILE_TEST_IS_SYMLINK = 1 << 1,
371
G_FILE_TEST_IS_DIR = 1 << 2,
372
G_FILE_TEST_IS_EXECUTABLE = 1 << 3,
373
G_FILE_TEST_EXISTS = 1 << 4
377
A test to perform on a file using <link linkend="g-file-test"><function>g_file_test()</function></link>.
378
</para><variablelist role="enum">
379
<varlistentry id="G-FILE-TEST-IS-REGULAR--CAPS" role="constant">
380
<term><literal>G_FILE_TEST_IS_REGULAR</literal></term>
381
<listitem><simpara>%TRUE if the file is a regular file (not a directory).
382
Note that this test will also return <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the tested file is a symlink
384
</simpara></listitem>
386
<varlistentry id="G-FILE-TEST-IS-SYMLINK--CAPS" role="constant">
387
<term><literal>G_FILE_TEST_IS_SYMLINK</literal></term>
388
<listitem><simpara>%TRUE if the file is a symlink.
389
</simpara></listitem>
391
<varlistentry id="G-FILE-TEST-IS-DIR--CAPS" role="constant">
392
<term><literal>G_FILE_TEST_IS_DIR</literal></term>
393
<listitem><simpara>%TRUE if the file is a directory.
394
</simpara></listitem>
396
<varlistentry id="G-FILE-TEST-IS-EXECUTABLE--CAPS" role="constant">
397
<term><literal>G_FILE_TEST_IS_EXECUTABLE</literal></term>
398
<listitem><simpara>%TRUE if the file is executable.
399
</simpara></listitem>
401
<varlistentry id="G-FILE-TEST-EXISTS--CAPS" role="constant">
402
<term><literal>G_FILE_TEST_EXISTS</literal></term>
403
<listitem><simpara>%TRUE if the file exists.
404
It may or may not be a regular file.
405
</simpara></listitem>
407
</variablelist></refsect2>
408
<refsect2 id="g-file-error-from-errno" role="function">
409
<title>g_file_error_from_errno ()</title>
410
<indexterm zone="g-file-error-from-errno"><primary sortas="file_error_from_errno">g_file_error_from_errno</primary></indexterm><programlisting><link linkend="GFileError">GFileError</link> g_file_error_from_errno (<link linkend="gint">gint</link> err_no);</programlisting>
412
Gets a <link linkend="GFileError"><type>GFileError</type></link> constant based on the passed-in <parameter>errno</parameter>.
413
For example, if you pass in <link linkend="EEXIST--CAPS"><literal>EEXIST</literal></link> this function returns
414
<link linkend="G-FILE-ERROR-EXIST--CAPS"><type>G_FILE_ERROR_EXIST</type></link>. Unlike <parameter>errno</parameter> values, you can portably
415
assume that all <link linkend="GFileError"><type>GFileError</type></link> values will exist.
418
Normally a <link linkend="GFileError"><type>GFileError</type></link> value goes into a <link linkend="GError"><type>GError</type></link> returned
419
from a function that manipulates files. So you would use
420
<link linkend="g-file-error-from-errno"><function>g_file_error_from_errno()</function></link> when constructing a <link linkend="GError"><type>GError</type></link>.</para>
422
</para><variablelist role="params">
423
<varlistentry><term><parameter>err_no</parameter> :</term>
424
<listitem><simpara> an "errno" value
425
</simpara></listitem></varlistentry>
426
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GFileError"><type>GFileError</type></link> corresponding to the given <parameter>errno</parameter>
427
</simpara></listitem></varlistentry>
428
</variablelist></refsect2>
429
<refsect2 id="g-file-get-contents" role="function">
430
<title>g_file_get_contents ()</title>
431
<indexterm zone="g-file-get-contents"><primary sortas="file_get_contents">g_file_get_contents</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_file_get_contents (const <link linkend="gchar">gchar</link> *filename,
432
<link linkend="gchar">gchar</link> **contents,
433
<link linkend="gsize">gsize</link> *length,
434
<link linkend="GError">GError</link> **error);</programlisting>
436
Reads an entire file into allocated memory, with good error
440
If the call was successful, it returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> and sets <parameter>contents</parameter> to the file
441
contents and <parameter>length</parameter> to the length of the file contents in bytes. The string
442
stored in <parameter>contents</parameter> will be nul-terminated, so for text files you can pass
443
<link linkend="NULL--CAPS"><literal>NULL</literal></link> for the <parameter>length</parameter> argument. If the call was not successful, it returns
444
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link> and sets <parameter>error</parameter>. The error domain is <link linkend="G-FILE-ERROR--CAPS"><type>G_FILE_ERROR</type></link>. Possible error
445
codes are those in the <link linkend="GFileError"><type>GFileError</type></link> enumeration. In the error case,
446
<parameter>contents</parameter> is set to <link linkend="NULL--CAPS"><literal>NULL</literal></link> and <parameter>length</parameter> is set to zero.</para>
448
</para><variablelist role="params">
449
<varlistentry><term><parameter>filename</parameter> :</term>
450
<listitem><simpara> name of a file to read contents from, in the GLib file name encoding
451
</simpara></listitem></varlistentry>
452
<varlistentry><term><parameter>contents</parameter> :</term>
453
<listitem><simpara> location to store an allocated string, use <link linkend="g-free"><function>g_free()</function></link> to free
455
</simpara></listitem></varlistentry>
456
<varlistentry><term><parameter>length</parameter> :</term>
457
<listitem><simpara> location to store length in bytes of the contents, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
458
</simpara></listitem></varlistentry>
459
<varlistentry><term><parameter>error</parameter> :</term>
460
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
461
</simpara></listitem></varlistentry>
462
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if an error occurred
463
</simpara></listitem></varlistentry>
464
</variablelist></refsect2>
465
<refsect2 id="g-file-set-contents" role="function" condition="since:2.8">
466
<title>g_file_set_contents ()</title>
467
<indexterm zone="g-file-set-contents" role="2.8"><primary sortas="file_set_contents">g_file_set_contents</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_file_set_contents (const <link linkend="gchar">gchar</link> *filename,
468
const <link linkend="gchar">gchar</link> *contents,
469
<link linkend="gssize">gssize</link> length,
470
<link linkend="GError">GError</link> **error);</programlisting>
472
Writes all of <parameter>contents</parameter> to a file named <parameter>filename</parameter>, with good error checking.
473
If a file called <parameter>filename</parameter> already exists it will be overwritten.
476
This write is atomic in the sense that it is first written to a temporary
477
file which is then renamed to the final name. Notes:
480
On Unix, if <parameter>filename</parameter> already exists hard links to <parameter>filename</parameter> will break.
481
Also since the file is recreated, existing permissions, access control
482
lists, metadata etc. may be lost. If <parameter>filename</parameter> is a symbolic link,
483
the link itself will be replaced, not the linked file.
486
On Windows renaming a file will not remove an existing file with the
487
new name, so on Windows there is a race condition between the existing
488
file being removed and the temporary file being renamed.
491
On Windows there is no way to remove a file that is open to some
492
process, or mapped into memory. Thus, this function will fail if
493
<parameter>filename</parameter> already exists and is open.
498
If the call was sucessful, it returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>. If the call was not successful,
499
it returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> and sets <parameter>error</parameter>. The error domain is <link linkend="G-FILE-ERROR--CAPS"><type>G_FILE_ERROR</type></link>.
500
Possible error codes are those in the <link linkend="GFileError"><type>GFileError</type></link> enumeration.</para>
502
</para><variablelist role="params">
503
<varlistentry><term><parameter>filename</parameter> :</term>
504
<listitem><simpara> name of a file to write <parameter>contents</parameter> to, in the GLib file name
506
</simpara></listitem></varlistentry>
507
<varlistentry><term><parameter>contents</parameter> :</term>
508
<listitem><simpara> string to write to the file
509
</simpara></listitem></varlistentry>
510
<varlistentry><term><parameter>length</parameter> :</term>
511
<listitem><simpara> length of <parameter>contents</parameter>, or -1 if <parameter>contents</parameter> is a nul-terminated string
512
</simpara></listitem></varlistentry>
513
<varlistentry><term><parameter>error</parameter> :</term>
514
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
515
</simpara></listitem></varlistentry>
516
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if an error occurred
518
</simpara></listitem></varlistentry>
519
</variablelist><para role="since">Since 2.8</para></refsect2>
520
<refsect2 id="g-file-test" role="function">
521
<title>g_file_test ()</title>
522
<indexterm zone="g-file-test"><primary sortas="file_test">g_file_test</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_file_test (const <link linkend="gchar">gchar</link> *filename,
523
<link linkend="GFileTest">GFileTest</link> test);</programlisting>
525
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if any of the tests in the bitfield <parameter>test</parameter> are
526
<link linkend="TRUE--CAPS"><literal>TRUE</literal></link>. For example, <literal>(G_FILE_TEST_EXISTS |
527
G_FILE_TEST_IS_DIR)</literal> will return <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the file exists;
528
the check whether it's a directory doesn't matter since the existence
529
test is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>. With the current set of available tests, there's no point
530
passing in more than one test at a time.
533
Apart from <link linkend="G-FILE-TEST-IS-SYMLINK--CAPS"><literal>G_FILE_TEST_IS_SYMLINK</literal></link> all tests follow symbolic links,
534
so for a symbolic link to a regular file <link linkend="g-file-test"><function>g_file_test()</function></link> will return
535
<link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for both <link linkend="G-FILE-TEST-IS-SYMLINK--CAPS"><literal>G_FILE_TEST_IS_SYMLINK</literal></link> and <link linkend="G-FILE-TEST-IS-REGULAR--CAPS"><literal>G_FILE_TEST_IS_REGULAR</literal></link>.
538
Note, that for a dangling symbolic link <link linkend="g-file-test"><function>g_file_test()</function></link> will return
539
<link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for <link linkend="G-FILE-TEST-IS-SYMLINK--CAPS"><literal>G_FILE_TEST_IS_SYMLINK</literal></link> and <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all other flags.
542
You should never use <link linkend="g-file-test"><function>g_file_test()</function></link> to test whether it is safe
543
to perform an operation, because there is always the possibility
544
of the condition changing before you actually perform the operation.
545
For example, you might think you could use <link linkend="G-FILE-TEST-IS-SYMLINK--CAPS"><literal>G_FILE_TEST_IS_SYMLINK</literal></link>
546
to know whether it is safe to write to a file without being
547
tricked into writing into a different location. It doesn't work!
548
<informalexample><programlisting>
549
/* DON'T DO THIS */
550
if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
552
fd = g_open (filename, O_WRONLY);
553
/* write to fd */
555
</programlisting></informalexample>
558
Another thing to note is that <link linkend="G-FILE-TEST-EXISTS--CAPS"><literal>G_FILE_TEST_EXISTS</literal></link> and
559
<link linkend="G-FILE-TEST-IS-EXECUTABLE--CAPS"><literal>G_FILE_TEST_IS_EXECUTABLE</literal></link> are implemented using the <link linkend="access"><function>access()</function></link>
560
system call. This usually doesn't matter, but if your program
561
is setuid or setgid it means that these tests will give you
562
the answer for the real user ID and group ID, rather than the
563
effective user ID and group ID.
566
On Windows, there are no symlinks, so testing for
567
<link linkend="G-FILE-TEST-IS-SYMLINK--CAPS"><literal>G_FILE_TEST_IS_SYMLINK</literal></link> will always return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>. Testing for
568
<link linkend="G-FILE-TEST-IS-EXECUTABLE--CAPS"><literal>G_FILE_TEST_IS_EXECUTABLE</literal></link> will just check that the file exists and
569
its name indicates that it is executable, checking for well-known
570
extensions and those listed in the <link linkend="PATHEXT--CAPS"><literal>PATHEXT</literal></link> environment variable.</para>
572
</para><variablelist role="params">
573
<varlistentry><term><parameter>filename</parameter> :</term>
574
<listitem><simpara> a filename to test in the GLib file name encoding
575
</simpara></listitem></varlistentry>
576
<varlistentry><term><parameter>test</parameter> :</term>
577
<listitem><simpara> bitfield of <link linkend="GFileTest"><type>GFileTest</type></link> flags
578
</simpara></listitem></varlistentry>
579
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> whether a test was <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>
580
</simpara></listitem></varlistentry>
581
</variablelist></refsect2>
582
<refsect2 id="g-mkstemp" role="function">
583
<title>g_mkstemp ()</title>
584
<indexterm zone="g-mkstemp"><primary sortas="mkstemp">g_mkstemp</primary></indexterm><programlisting><link linkend="gint">gint</link> g_mkstemp (<link linkend="gchar">gchar</link> *tmpl);</programlisting>
586
Opens a temporary file. See the <link linkend="mkstemp"><function>mkstemp()</function></link> documentation
587
on most UNIX-like systems.
590
The parameter is a string that should follow the rules for
591
<link linkend="mkstemp"><function>mkstemp()</function></link> templates, i.e. contain the string "XXXXXX".
592
<link linkend="g-mkstemp"><function>g_mkstemp()</function></link> is slightly more flexible than <link linkend="mkstemp"><function>mkstemp()</function></link>
593
in that the sequence does not have to occur at the very end of the
594
template. The X string will
595
be modified to form the name of a file that didn't exist.
596
The string should be in the GLib file name encoding. Most importantly,
597
on Windows it should be in UTF-8.</para>
599
</para><variablelist role="params">
600
<varlistentry><term><parameter>tmpl</parameter> :</term>
601
<listitem><simpara> template filename
602
</simpara></listitem></varlistentry>
603
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A file handle (as from <link linkend="open"><function>open()</function></link>) to the file
604
opened for reading and writing. The file is opened in binary mode
605
on platforms where there is a difference. The file handle should be
606
closed with <link linkend="close"><function>close()</function></link>. In case of errors, -1 is returned.
607
</simpara></listitem></varlistentry>
608
</variablelist></refsect2>
609
<refsect2 id="g-mkstemp-full" role="function" condition="since:2.22">
610
<title>g_mkstemp_full ()</title>
611
<indexterm zone="g-mkstemp-full" role="2.22"><primary sortas="mkstemp_full">g_mkstemp_full</primary></indexterm><programlisting><link linkend="gint">gint</link> g_mkstemp_full (<link linkend="gchar">gchar</link> *tmpl,
612
<link linkend="int">int</link> flags,
613
<link linkend="int">int</link> mode);</programlisting>
615
Opens a temporary file. See the <link linkend="mkstemp"><function>mkstemp()</function></link> documentation
616
on most UNIX-like systems.
619
The parameter is a string that should follow the rules for
620
<link linkend="mkstemp"><function>mkstemp()</function></link> templates, i.e. contain the string "XXXXXX".
621
<link linkend="g-mkstemp-full"><function>g_mkstemp_full()</function></link> is slightly more flexible than <link linkend="mkstemp"><function>mkstemp()</function></link>
622
in that the sequence does not have to occur at the very end of the
623
template and you can pass a <parameter>mode</parameter> and additional <parameter>flags</parameter>. The X
624
string will be modified to form the name of a file that didn't exist.
625
The string should be in the GLib file name encoding. Most importantly,
626
on Windows it should be in UTF-8.</para>
628
</para><variablelist role="params">
629
<varlistentry><term><parameter>tmpl</parameter> :</term>
630
<listitem><simpara> template filename
631
</simpara></listitem></varlistentry>
632
<varlistentry><term><parameter>flags</parameter> :</term>
633
<listitem><simpara> flags to pass to an <link linkend="open"><function>open()</function></link> call in addition to O_EXCL and
634
O_CREAT, which are passed automatically
635
</simpara></listitem></varlistentry>
636
<varlistentry><term><parameter>mode</parameter> :</term>
637
<listitem><simpara> permissios to create the temporary file with
638
</simpara></listitem></varlistentry>
639
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A file handle (as from <link linkend="open"><function>open()</function></link>) to the file
640
opened for reading and writing. The file handle should be
641
closed with <link linkend="close"><function>close()</function></link>. In case of errors, -1 is returned.
643
</simpara></listitem></varlistentry>
644
</variablelist><para role="since">Since 2.22</para></refsect2>
645
<refsect2 id="g-file-open-tmp" role="function">
646
<title>g_file_open_tmp ()</title>
647
<indexterm zone="g-file-open-tmp"><primary sortas="file_open_tmp">g_file_open_tmp</primary></indexterm><programlisting><link linkend="gint">gint</link> g_file_open_tmp (const <link linkend="gchar">gchar</link> *tmpl,
648
<link linkend="gchar">gchar</link> **name_used,
649
<link linkend="GError">GError</link> **error);</programlisting>
651
Opens a file for writing in the preferred directory for temporary
652
files (as returned by <link linkend="g-get-tmp-dir"><function>g_get_tmp_dir()</function></link>).
655
<parameter>tmpl</parameter> should be a string in the GLib file name encoding containing
656
a sequence of six 'X' characters, as the parameter to <link linkend="g-mkstemp"><function>g_mkstemp()</function></link>.
657
However, unlike these functions, the template should only be a
658
basename, no directory components are allowed. If template is
659
<link linkend="NULL--CAPS"><literal>NULL</literal></link>, a default template is used.
662
Note that in contrast to <link linkend="g-mkstemp"><function>g_mkstemp()</function></link> (and <link linkend="mkstemp"><function>mkstemp()</function></link>)
663
<parameter>tmpl</parameter> is not modified, and might thus be a read-only literal string.
666
The actual name used is returned in <parameter>name_used</parameter> if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>. This
667
string should be freed with <link linkend="g-free"><function>g_free()</function></link> when not needed any longer.
668
The returned name is in the GLib file name encoding.</para>
670
</para><variablelist role="params">
671
<varlistentry><term><parameter>tmpl</parameter> :</term>
672
<listitem><simpara> Template for file name, as in <link linkend="g-mkstemp"><function>g_mkstemp()</function></link>, basename only,
673
or <link linkend="NULL--CAPS"><literal>NULL</literal></link>, to a default template
674
</simpara></listitem></varlistentry>
675
<varlistentry><term><parameter>name_used</parameter> :</term>
676
<listitem><simpara> location to store actual name used, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
677
</simpara></listitem></varlistentry>
678
<varlistentry><term><parameter>error</parameter> :</term>
679
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
680
</simpara></listitem></varlistentry>
681
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A file handle (as from <link linkend="open"><function>open()</function></link>) to
682
the file opened for reading and writing. The file is opened in binary
683
mode on platforms where there is a difference. The file handle should be
684
closed with <link linkend="close"><function>close()</function></link>. In case of errors, -1 is returned
685
and <parameter>error</parameter> will be set.
686
</simpara></listitem></varlistentry>
687
</variablelist></refsect2>
688
<refsect2 id="g-file-read-link" role="function" condition="since:2.4">
689
<title>g_file_read_link ()</title>
690
<indexterm zone="g-file-read-link" role="2.4"><primary sortas="file_read_link">g_file_read_link</primary></indexterm><programlisting><link linkend="gchar">gchar</link> * g_file_read_link (const <link linkend="gchar">gchar</link> *filename,
691
<link linkend="GError">GError</link> **error);</programlisting>
693
Reads the contents of the symbolic link <parameter>filename</parameter> like the POSIX
694
<link linkend="readlink"><function>readlink()</function></link> function. The returned string is in the encoding used
695
for filenames. Use <link linkend="g-filename-to-utf8"><function>g_filename_to_utf8()</function></link> to convert it to UTF-8.</para>
697
</para><variablelist role="params">
698
<varlistentry><term><parameter>filename</parameter> :</term>
699
<listitem><simpara> the symbolic link
700
</simpara></listitem></varlistentry>
701
<varlistentry><term><parameter>error</parameter> :</term>
702
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
703
</simpara></listitem></varlistentry>
704
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A newly-allocated string with the contents of the symbolic link,
705
or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if an error occurred.
707
</simpara></listitem></varlistentry>
708
</variablelist><para role="since">Since 2.4</para></refsect2>
709
<refsect2 id="g-mkdir-with-parents" role="function" condition="since:2.8">
710
<title>g_mkdir_with_parents ()</title>
711
<indexterm zone="g-mkdir-with-parents" role="2.8"><primary sortas="mkdir_with_parents">g_mkdir_with_parents</primary></indexterm><programlisting><link linkend="int">int</link> g_mkdir_with_parents (const <link linkend="gchar">gchar</link> *pathname,
712
<link linkend="int">int</link> mode);</programlisting>
714
Create a directory if it doesn't already exist. Create intermediate
715
parent directories as needed, too.</para>
717
</para><variablelist role="params">
718
<varlistentry><term><parameter>pathname</parameter> :</term>
719
<listitem><simpara> a pathname in the GLib file name encoding
720
</simpara></listitem></varlistentry>
721
<varlistentry><term><parameter>mode</parameter> :</term>
722
<listitem><simpara> permissions to use for newly created directories
723
</simpara></listitem></varlistentry>
724
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the directory already exists, or was successfully
725
created. Returns -1 if an error occurred, with errno set.
727
</simpara></listitem></varlistentry>
728
</variablelist><para role="since">Since 2.8</para></refsect2>
729
<refsect2 id="GDir" role="struct">
731
<indexterm zone="GDir"><primary sortas="Dir">GDir</primary></indexterm><programlisting>typedef struct _GDir GDir;</programlisting>
733
An opaque structure representing an opened directory.
735
<refsect2 id="g-dir-open" role="function">
736
<title>g_dir_open ()</title>
737
<indexterm zone="g-dir-open"><primary sortas="dir_open">g_dir_open</primary></indexterm><programlisting><link linkend="GDir">GDir</link> * g_dir_open (const <link linkend="gchar">gchar</link> *path,
738
<link linkend="guint">guint</link> flags,
739
<link linkend="GError">GError</link> **error);</programlisting>
741
Opens a directory for reading. The names of the files in the
742
directory can then be retrieved using <link linkend="g-dir-read-name"><function>g_dir_read_name()</function></link>.</para>
744
</para><variablelist role="params">
745
<varlistentry><term><parameter>path</parameter> :</term>
746
<listitem><simpara> the path to the directory you are interested in. On Unix
747
in the on-disk encoding. On Windows in UTF-8
748
</simpara></listitem></varlistentry>
749
<varlistentry><term><parameter>flags</parameter> :</term>
750
<listitem><simpara> Currently must be set to 0. Reserved for future use.
751
</simpara></listitem></varlistentry>
752
<varlistentry><term><parameter>error</parameter> :</term>
753
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
754
If non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, an error will be set if and only if
755
<link linkend="g-dir-open"><function>g_dir_open()</function></link> fails.
756
</simpara></listitem></varlistentry>
757
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated <link linkend="GDir"><type>GDir</type></link> on success, <link linkend="NULL--CAPS"><literal>NULL</literal></link> on failure.
758
If non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, you must free the result with <link linkend="g-dir-close"><function>g_dir_close()</function></link>
759
when you are finished with it.
760
</simpara></listitem></varlistentry>
761
</variablelist></refsect2>
762
<refsect2 id="g-dir-read-name" role="function">
763
<title>g_dir_read_name ()</title>
764
<indexterm zone="g-dir-read-name"><primary sortas="dir_read_name">g_dir_read_name</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * g_dir_read_name (<link linkend="GDir">GDir</link> *dir);</programlisting>
766
Retrieves the name of the next entry in the directory. The '.' and
767
'..' entries are omitted. On Windows, the returned name is in
768
UTF-8. On Unix, it is in the on-disk encoding.</para>
770
</para><variablelist role="params">
771
<varlistentry><term><parameter>dir</parameter> :</term>
772
<listitem><simpara> a <link linkend="GDir"><type>GDir</type></link>* created by <link linkend="g-dir-open"><function>g_dir_open()</function></link>
773
</simpara></listitem></varlistentry>
774
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The entry's name or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if there are no
775
more entries. The return value is owned by GLib and
776
must not be modified or freed.
777
</simpara></listitem></varlistentry>
778
</variablelist></refsect2>
779
<refsect2 id="g-dir-rewind" role="function">
780
<title>g_dir_rewind ()</title>
781
<indexterm zone="g-dir-rewind"><primary sortas="dir_rewind">g_dir_rewind</primary></indexterm><programlisting><link linkend="void">void</link> g_dir_rewind (<link linkend="GDir">GDir</link> *dir);</programlisting>
783
Resets the given directory. The next call to <link linkend="g-dir-read-name"><function>g_dir_read_name()</function></link>
784
will return the first entry again.</para>
786
</para><variablelist role="params">
787
<varlistentry><term><parameter>dir</parameter> :</term>
788
<listitem><simpara> a <link linkend="GDir"><type>GDir</type></link>* created by <link linkend="g-dir-open"><function>g_dir_open()</function></link>
789
</simpara></listitem></varlistentry>
790
</variablelist></refsect2>
791
<refsect2 id="g-dir-close" role="function">
792
<title>g_dir_close ()</title>
793
<indexterm zone="g-dir-close"><primary sortas="dir_close">g_dir_close</primary></indexterm><programlisting><link linkend="void">void</link> g_dir_close (<link linkend="GDir">GDir</link> *dir);</programlisting>
795
Closes the directory and deallocates all related resources.</para>
797
</para><variablelist role="params">
798
<varlistentry><term><parameter>dir</parameter> :</term>
799
<listitem><simpara> a <link linkend="GDir"><type>GDir</type></link>* created by <link linkend="g-dir-open"><function>g_dir_open()</function></link>
800
</simpara></listitem></varlistentry>
801
</variablelist></refsect2>
802
<refsect2 id="GMappedFile" role="struct">
803
<title>GMappedFile</title>
804
<indexterm zone="GMappedFile"><primary sortas="MappedFile">GMappedFile</primary></indexterm><programlisting>typedef struct _GMappedFile GMappedFile;</programlisting>
806
The <link linkend="GMappedFile"><type>GMappedFile</type></link> represents a file mapping created with
807
<link linkend="g-mapped-file-new"><function>g_mapped_file_new()</function></link>. It has only private members and should
808
not be accessed directly.
810
<refsect2 id="g-mapped-file-new" role="function" condition="since:2.8">
811
<title>g_mapped_file_new ()</title>
812
<indexterm zone="g-mapped-file-new" role="2.8"><primary sortas="mapped_file_new">g_mapped_file_new</primary></indexterm><programlisting><link linkend="GMappedFile">GMappedFile</link> * g_mapped_file_new (const <link linkend="gchar">gchar</link> *filename,
813
<link linkend="gboolean">gboolean</link> writable,
814
<link linkend="GError">GError</link> **error);</programlisting>
816
Maps a file into memory. On UNIX, this is using the <link linkend="mmap"><function>mmap()</function></link> function.
819
If <parameter>writable</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, the mapped buffer may be modified, otherwise
820
it is an error to modify the mapped buffer. Modifications to the buffer
821
are not visible to other processes mapping the same file, and are not
822
written back to the file.
825
Note that modifications of the underlying file might affect the contents
826
of the <link linkend="GMappedFile"><type>GMappedFile</type></link>. Therefore, mapping should only be used if the file
827
will not be modified, or if all modifications of the file are done
828
atomically (e.g. using <link linkend="g-file-set-contents"><function>g_file_set_contents()</function></link>).</para>
830
</para><variablelist role="params">
831
<varlistentry><term><parameter>filename</parameter> :</term>
832
<listitem><simpara> The path of the file to load, in the GLib filename encoding
833
</simpara></listitem></varlistentry>
834
<varlistentry><term><parameter>writable</parameter> :</term>
835
<listitem><simpara> whether the mapping should be writable
836
</simpara></listitem></varlistentry>
837
<varlistentry><term><parameter>error</parameter> :</term>
838
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
839
</simpara></listitem></varlistentry>
840
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated <link linkend="GMappedFile"><type>GMappedFile</type></link> which must be unref'd
841
with <link linkend="g-mapped-file-unref"><function>g_mapped_file_unref()</function></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the mapping failed.
843
</simpara></listitem></varlistentry>
844
</variablelist><para role="since">Since 2.8</para></refsect2>
845
<refsect2 id="g-mapped-file-ref" role="function" condition="since:2.22">
846
<title>g_mapped_file_ref ()</title>
847
<indexterm zone="g-mapped-file-ref" role="2.22"><primary sortas="mapped_file_ref">g_mapped_file_ref</primary></indexterm><programlisting><link linkend="GMappedFile">GMappedFile</link> * g_mapped_file_ref (<link linkend="GMappedFile">GMappedFile</link> *file);</programlisting>
849
Increments the reference count of <parameter>file</parameter> by one. It is safe to call
850
this function from any thread.</para>
852
</para><variablelist role="params">
853
<varlistentry><term><parameter>file</parameter> :</term>
854
<listitem><simpara> a <link linkend="GMappedFile"><type>GMappedFile</type></link>
855
</simpara></listitem></varlistentry>
856
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the passed in <link linkend="GMappedFile"><type>GMappedFile</type></link>.
858
</simpara></listitem></varlistentry>
859
</variablelist><para role="since">Since 2.22</para></refsect2>
860
<refsect2 id="g-mapped-file-unref" role="function">
861
<title>g_mapped_file_unref ()</title>
862
<indexterm zone="g-mapped-file-unref"><primary sortas="mapped_file_unref">g_mapped_file_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_mapped_file_unref (<link linkend="GMappedFile">GMappedFile</link> *file);</programlisting>
864
Decrements the reference count of <parameter>file</parameter> by one. If the reference count
865
drops to 0, unmaps the buffer of <parameter>file</parameter> and frees it.
868
It is safe to call this function from any thread.
873
</para><variablelist role="params">
874
<varlistentry><term><parameter>file</parameter> :</term>
875
<listitem><simpara> a <link linkend="GMappedFile"><type>GMappedFile</type></link>
876
</simpara></listitem></varlistentry>
877
</variablelist></refsect2>
878
<refsect2 id="g-mapped-file-free" role="function" condition="deprecated:2.22: Use g_mapped_file_unref() instead.|since:2.8">
879
<title>g_mapped_file_free ()</title>
880
<indexterm zone="g-mapped-file-free" role="deprecated"><primary sortas="mapped_file_free">g_mapped_file_free</primary></indexterm><indexterm zone="g-mapped-file-free" role="2.8"><primary sortas="mapped_file_free">g_mapped_file_free</primary></indexterm><programlisting><link linkend="void">void</link> g_mapped_file_free (<link linkend="GMappedFile">GMappedFile</link> *file);</programlisting>
881
<warning><para><literal>g_mapped_file_free</literal> has been deprecated since version 2.22 and should not be used in newly-written code. Use <link linkend="g-mapped-file-unref"><function>g_mapped_file_unref()</function></link> instead.</para></warning>
883
This call existed before <link linkend="GMappedFile"><type>GMappedFile</type></link> had refcounting and is currently
884
exactly the same as <link linkend="g-mapped-file-unref"><function>g_mapped_file_unref()</function></link>.</para>
886
</para><variablelist role="params">
887
<varlistentry><term><parameter>file</parameter> :</term>
888
<listitem><simpara> a <link linkend="GMappedFile"><type>GMappedFile</type></link>
889
</simpara></listitem></varlistentry>
890
</variablelist><para role="since">Since 2.8</para></refsect2>
891
<refsect2 id="g-mapped-file-get-length" role="function" condition="since:2.8">
892
<title>g_mapped_file_get_length ()</title>
893
<indexterm zone="g-mapped-file-get-length" role="2.8"><primary sortas="mapped_file_get_length">g_mapped_file_get_length</primary></indexterm><programlisting><link linkend="gsize">gsize</link> g_mapped_file_get_length (<link linkend="GMappedFile">GMappedFile</link> *file);</programlisting>
895
Returns the length of the contents of a <link linkend="GMappedFile"><type>GMappedFile</type></link>.</para>
897
</para><variablelist role="params">
898
<varlistentry><term><parameter>file</parameter> :</term>
899
<listitem><simpara> a <link linkend="GMappedFile"><type>GMappedFile</type></link>
900
</simpara></listitem></varlistentry>
901
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the length of the contents of <parameter>file</parameter>.
903
</simpara></listitem></varlistentry>
904
</variablelist><para role="since">Since 2.8</para></refsect2>
905
<refsect2 id="g-mapped-file-get-contents" role="function" condition="since:2.8">
906
<title>g_mapped_file_get_contents ()</title>
907
<indexterm zone="g-mapped-file-get-contents" role="2.8"><primary sortas="mapped_file_get_contents">g_mapped_file_get_contents</primary></indexterm><programlisting><link linkend="gchar">gchar</link> * g_mapped_file_get_contents (<link linkend="GMappedFile">GMappedFile</link> *file);</programlisting>
909
Returns the contents of a <link linkend="GMappedFile"><type>GMappedFile</type></link>.
912
Note that the contents may not be zero-terminated,
913
even if the <link linkend="GMappedFile"><type>GMappedFile</type></link> is backed by a text file.
916
If the file is empty then <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned.</para>
918
</para><variablelist role="params">
919
<varlistentry><term><parameter>file</parameter> :</term>
920
<listitem><simpara> a <link linkend="GMappedFile"><type>GMappedFile</type></link>
921
</simpara></listitem></varlistentry>
922
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the contents of <parameter>file</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
924
</simpara></listitem></varlistentry>
925
</variablelist><para role="since">Since 2.8</para></refsect2>
926
<refsect2 id="g-open" role="function" condition="since:2.6">
927
<title>g_open ()</title>
928
<indexterm zone="g-open" role="2.6"><primary sortas="open">g_open</primary></indexterm><programlisting><link linkend="int">int</link> g_open (const <link linkend="gchar">gchar</link> *filename,
929
<link linkend="int">int</link> flags,
930
<link linkend="int">int</link> mode);</programlisting>
932
A wrapper for the POSIX <link linkend="open"><function>open()</function></link> function. The <link linkend="open"><function>open()</function></link> function is
933
used to convert a pathname into a file descriptor.
936
On POSIX systems file descriptors are implemented by the operating
937
system. On Windows, it's the C library that implements <link linkend="open"><function>open()</function></link> and
938
file descriptors. The actual Win32 API for opening files is quite
939
different, see MSDN documentation for <link linkend="CreateFile"><function>CreateFile()</function></link>. The Win32 API
940
uses file handles, which are more randomish integers, not small
941
integers like file descriptors.
944
Because file descriptors are specific to the C library on Windows,
945
the file descriptor returned by this function makes sense only to
946
functions in the same C library. Thus if the GLib-using code uses a
947
different C library than GLib does, the file descriptor returned by
948
this function cannot be passed to C library functions like <link linkend="write"><function>write()</function></link>
949
or <link linkend="read"><function>read()</function></link>.
952
See your C library manual for more details about <link linkend="open"><function>open()</function></link>.</para>
954
</para><variablelist role="params">
955
<varlistentry><term><parameter>filename</parameter> :</term>
956
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
957
</simpara></listitem></varlistentry>
958
<varlistentry><term><parameter>flags</parameter> :</term>
959
<listitem><simpara> as in <link linkend="open"><function>open()</function></link>
960
</simpara></listitem></varlistentry>
961
<varlistentry><term><parameter>mode</parameter> :</term>
962
<listitem><simpara> as in <link linkend="open"><function>open()</function></link>
963
</simpara></listitem></varlistentry>
964
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new file descriptor, or -1 if an error occurred. The
965
return value can be used exactly like the return value from <link linkend="open"><function>open()</function></link>.
967
</simpara></listitem></varlistentry>
968
</variablelist><para role="since">Since 2.6</para></refsect2>
969
<refsect2 id="g-rename" role="function" condition="since:2.6">
970
<title>g_rename ()</title>
971
<indexterm zone="g-rename" role="2.6"><primary sortas="rename">g_rename</primary></indexterm><programlisting><link linkend="int">int</link> g_rename (const <link linkend="gchar">gchar</link> *oldfilename,
972
const <link linkend="gchar">gchar</link> *newfilename);</programlisting>
974
A wrapper for the POSIX <link linkend="rename"><function>rename()</function></link> function. The <link linkend="rename"><function>rename()</function></link> function
975
renames a file, moving it between directories if required.
978
See your C library manual for more details about how <link linkend="rename"><function>rename()</function></link> works
979
on your system. It is not possible in general on Windows to rename
980
a file that is open to some process.</para>
982
</para><variablelist role="params">
983
<varlistentry><term><parameter>oldfilename</parameter> :</term>
984
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
985
</simpara></listitem></varlistentry>
986
<varlistentry><term><parameter>newfilename</parameter> :</term>
987
<listitem><simpara> a pathname in the GLib file name encoding
988
</simpara></listitem></varlistentry>
989
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the renaming succeeded, -1 if an error occurred
991
</simpara></listitem></varlistentry>
992
</variablelist><para role="since">Since 2.6</para></refsect2>
993
<refsect2 id="g-mkdir" role="function" condition="since:2.6">
994
<title>g_mkdir ()</title>
995
<indexterm zone="g-mkdir" role="2.6"><primary sortas="mkdir">g_mkdir</primary></indexterm><programlisting><link linkend="int">int</link> g_mkdir (const <link linkend="gchar">gchar</link> *filename,
996
<link linkend="int">int</link> mode);</programlisting>
998
A wrapper for the POSIX <link linkend="mkdir"><function>mkdir()</function></link> function. The <link linkend="mkdir"><function>mkdir()</function></link> function
999
attempts to create a directory with the given name and permissions.
1000
The mode argument is ignored on Windows.
1003
See your C library manual for more details about <link linkend="mkdir"><function>mkdir()</function></link>.</para>
1005
</para><variablelist role="params">
1006
<varlistentry><term><parameter>filename</parameter> :</term>
1007
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1008
</simpara></listitem></varlistentry>
1009
<varlistentry><term><parameter>mode</parameter> :</term>
1010
<listitem><simpara> permissions to use for the newly created directory
1011
</simpara></listitem></varlistentry>
1012
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the directory was successfully created, -1 if an error
1015
</simpara></listitem></varlistentry>
1016
</variablelist><para role="since">Since 2.6</para></refsect2>
1017
<refsect2 id="g-stat" role="function" condition="since:2.6">
1018
<title>g_stat ()</title>
1019
<indexterm zone="g-stat" role="2.6"><primary sortas="stat">g_stat</primary></indexterm><programlisting><link linkend="int">int</link> g_stat (const <link linkend="gchar">gchar</link> *filename,
1020
<link linkend="struct--g-stat-struct">struct _g_stat_struct</link> *buf);</programlisting>
1022
A wrapper for the POSIX <link linkend="stat"><function>stat()</function></link> function. The <link linkend="stat"><function>stat()</function></link> function
1023
returns information about a file. On Windows the <link linkend="stat"><function>stat()</function></link> function in
1024
the C library checks only the FAT-style READONLY attribute and does
1025
not look at the ACL at all. Thus on Windows the protection bits in
1026
the st_mode field are a fabrication of little use.
1029
See your C library manual for more details about <link linkend="stat"><function>stat()</function></link>.</para>
1031
</para><variablelist role="params">
1032
<varlistentry><term><parameter>filename</parameter> :</term>
1033
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1034
</simpara></listitem></varlistentry>
1035
<varlistentry><term><parameter>buf</parameter> :</term>
1036
<listitem><simpara> a pointer to a <structname>stat</structname> struct, which
1037
will be filled with the file information
1038
</simpara></listitem></varlistentry>
1039
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the information was successfully retrieved, -1 if an error
1042
</simpara></listitem></varlistentry>
1043
</variablelist><para role="since">Since 2.6</para></refsect2>
1044
<refsect2 id="g-lstat" role="function" condition="since:2.6">
1045
<title>g_lstat ()</title>
1046
<indexterm zone="g-lstat" role="2.6"><primary sortas="lstat">g_lstat</primary></indexterm><programlisting><link linkend="int">int</link> g_lstat (const <link linkend="gchar">gchar</link> *filename,
1047
<link linkend="struct--g-stat-struct">struct _g_stat_struct</link> *buf);</programlisting>
1049
A wrapper for the POSIX <link linkend="lstat"><function>lstat()</function></link> function. The <link linkend="lstat"><function>lstat()</function></link> function is
1050
like <link linkend="stat"><function>stat()</function></link> except that in the case of symbolic links, it returns
1051
information about the symbolic link itself and not the file that it
1052
refers to. If the system does not support symbolic links <link linkend="g-lstat"><function>g_lstat()</function></link>
1053
is identical to <link linkend="g-stat"><function>g_stat()</function></link>.
1056
See your C library manual for more details about <link linkend="lstat"><function>lstat()</function></link>.</para>
1058
</para><variablelist role="params">
1059
<varlistentry><term><parameter>filename</parameter> :</term>
1060
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1061
</simpara></listitem></varlistentry>
1062
<varlistentry><term><parameter>buf</parameter> :</term>
1063
<listitem><simpara> a pointer to a <structname>stat</structname> struct, which
1064
will be filled with the file information
1065
</simpara></listitem></varlistentry>
1066
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the information was successfully retrieved, -1 if an error
1069
</simpara></listitem></varlistentry>
1070
</variablelist><para role="since">Since 2.6</para></refsect2>
1071
<refsect2 id="g-unlink" role="function" condition="since:2.6">
1072
<title>g_unlink ()</title>
1073
<indexterm zone="g-unlink" role="2.6"><primary sortas="unlink">g_unlink</primary></indexterm><programlisting><link linkend="int">int</link> g_unlink (const <link linkend="gchar">gchar</link> *filename);</programlisting>
1075
A wrapper for the POSIX <link linkend="unlink"><function>unlink()</function></link> function. The <link linkend="unlink"><function>unlink()</function></link> function
1076
deletes a name from the filesystem. If this was the last link to the
1077
file and no processes have it opened, the diskspace occupied by the
1081
See your C library manual for more details about <link linkend="unlink"><function>unlink()</function></link>. Note
1082
that on Windows, it is in general not possible to delete files that
1083
are open to some process, or mapped into memory.</para>
1085
</para><variablelist role="params">
1086
<varlistentry><term><parameter>filename</parameter> :</term>
1087
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1088
</simpara></listitem></varlistentry>
1089
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the name was successfully deleted, -1 if an error
1092
</simpara></listitem></varlistentry>
1093
</variablelist><para role="since">Since 2.6</para></refsect2>
1094
<refsect2 id="g-remove" role="function" condition="since:2.6">
1095
<title>g_remove ()</title>
1096
<indexterm zone="g-remove" role="2.6"><primary sortas="remove">g_remove</primary></indexterm><programlisting><link linkend="int">int</link> g_remove (const <link linkend="gchar">gchar</link> *filename);</programlisting>
1098
A wrapper for the POSIX <link linkend="remove"><function>remove()</function></link> function. The <link linkend="remove"><function>remove()</function></link> function
1099
deletes a name from the filesystem.
1102
See your C library manual for more details about how <link linkend="remove"><function>remove()</function></link> works
1103
on your system. On Unix, <link linkend="remove"><function>remove()</function></link> removes also directories, as it
1104
calls <link linkend="unlink"><function>unlink()</function></link> for files and <link linkend="rmdir"><function>rmdir()</function></link> for directories. On Windows,
1105
although <link linkend="remove"><function>remove()</function></link> in the C library only works for files, this
1106
function tries first <link linkend="remove"><function>remove()</function></link> and then if that fails <link linkend="rmdir"><function>rmdir()</function></link>, and
1107
thus works for both files and directories. Note however, that on
1108
Windows, it is in general not possible to remove a file that is
1109
open to some process, or mapped into memory.
1112
If this function fails on Windows you can't infer too much from the
1113
errno value. <link linkend="rmdir"><function>rmdir()</function></link> is tried regardless of what caused <link linkend="remove"><function>remove()</function></link> to
1114
fail. Any errno value set by <link linkend="remove"><function>remove()</function></link> will be overwritten by that
1115
set by <link linkend="rmdir"><function>rmdir()</function></link>.</para>
1117
</para><variablelist role="params">
1118
<varlistentry><term><parameter>filename</parameter> :</term>
1119
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1120
</simpara></listitem></varlistentry>
1121
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the file was successfully removed, -1 if an error
1124
</simpara></listitem></varlistentry>
1125
</variablelist><para role="since">Since 2.6</para></refsect2>
1126
<refsect2 id="g-rmdir" role="function" condition="since:2.6">
1127
<title>g_rmdir ()</title>
1128
<indexterm zone="g-rmdir" role="2.6"><primary sortas="rmdir">g_rmdir</primary></indexterm><programlisting><link linkend="int">int</link> g_rmdir (const <link linkend="gchar">gchar</link> *filename);</programlisting>
1130
A wrapper for the POSIX <link linkend="rmdir"><function>rmdir()</function></link> function. The <link linkend="rmdir"><function>rmdir()</function></link> function
1131
deletes a directory from the filesystem.
1134
See your C library manual for more details about how <link linkend="rmdir"><function>rmdir()</function></link> works
1135
on your system.</para>
1137
</para><variablelist role="params">
1138
<varlistentry><term><parameter>filename</parameter> :</term>
1139
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1140
</simpara></listitem></varlistentry>
1141
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the directory was successfully removed, -1 if an error
1144
</simpara></listitem></varlistentry>
1145
</variablelist><para role="since">Since 2.6</para></refsect2>
1146
<refsect2 id="g-fopen" role="function" condition="since:2.6">
1147
<title>g_fopen ()</title>
1148
<indexterm zone="g-fopen" role="2.6"><primary sortas="fopen">g_fopen</primary></indexterm><programlisting><link linkend="FILE--CAPS">FILE</link> * g_fopen (const <link linkend="gchar">gchar</link> *filename,
1149
const <link linkend="gchar">gchar</link> *mode);</programlisting>
1151
A wrapper for the stdio <link linkend="fopen"><function>fopen()</function></link> function. The <link linkend="fopen"><function>fopen()</function></link> function
1152
opens a file and associates a new stream with it.
1155
Because file descriptors are specific to the C library on Windows,
1156
and a file descriptor is partof the <type>FILE</type> struct, the
1157
<type>FILE</type> pointer returned by this function makes sense
1158
only to functions in the same C library. Thus if the GLib-using
1159
code uses a different C library than GLib does, the
1160
<type>FILE</type> pointer returned by this function cannot be
1161
passed to C library functions like <link linkend="fprintf"><function>fprintf()</function></link> or <link linkend="fread"><function>fread()</function></link>.
1164
See your C library manual for more details about <link linkend="fopen"><function>fopen()</function></link>.</para>
1166
</para><variablelist role="params">
1167
<varlistentry><term><parameter>filename</parameter> :</term>
1168
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1169
</simpara></listitem></varlistentry>
1170
<varlistentry><term><parameter>mode</parameter> :</term>
1171
<listitem><simpara> a string describing the mode in which the file should be
1173
</simpara></listitem></varlistentry>
1174
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <type>FILE</type> pointer if the file was successfully
1175
opened, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if an error occurred
1177
</simpara></listitem></varlistentry>
1178
</variablelist><para role="since">Since 2.6</para></refsect2>
1179
<refsect2 id="g-freopen" role="function" condition="since:2.6">
1180
<title>g_freopen ()</title>
1181
<indexterm zone="g-freopen" role="2.6"><primary sortas="freopen">g_freopen</primary></indexterm><programlisting><link linkend="FILE--CAPS">FILE</link> * g_freopen (const <link linkend="gchar">gchar</link> *filename,
1182
const <link linkend="gchar">gchar</link> *mode,
1183
<link linkend="FILE--CAPS">FILE</link> *stream);</programlisting>
1185
A wrapper for the POSIX <link linkend="freopen"><function>freopen()</function></link> function. The <link linkend="freopen"><function>freopen()</function></link> function
1186
opens a file and associates it with an existing stream.
1189
See your C library manual for more details about <link linkend="freopen"><function>freopen()</function></link>.</para>
1191
</para><variablelist role="params">
1192
<varlistentry><term><parameter>filename</parameter> :</term>
1193
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1194
</simpara></listitem></varlistentry>
1195
<varlistentry><term><parameter>mode</parameter> :</term>
1196
<listitem><simpara> a string describing the mode in which the file should be
1198
</simpara></listitem></varlistentry>
1199
<varlistentry><term><parameter>stream</parameter> :</term>
1200
<listitem><simpara> an existing stream which will be reused, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1201
</simpara></listitem></varlistentry>
1202
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <type>FILE</type> pointer if the file was successfully
1203
opened, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if an error occurred.
1205
</simpara></listitem></varlistentry>
1206
</variablelist><para role="since">Since 2.6</para></refsect2>
1207
<refsect2 id="g-chmod" role="function" condition="since:2.8">
1208
<title>g_chmod ()</title>
1209
<indexterm zone="g-chmod" role="2.8"><primary sortas="chmod">g_chmod</primary></indexterm><programlisting><link linkend="int">int</link> g_chmod (const <link linkend="gchar">gchar</link> *filename,
1210
<link linkend="int">int</link> mode);</programlisting>
1212
A wrapper for the POSIX <link linkend="chmod"><function>chmod()</function></link> function. The <link linkend="chmod"><function>chmod()</function></link> function is
1213
used to set the permissions of a file system object.
1216
On Windows the file protection mechanism is not at all POSIX-like,
1217
and the underlying <link linkend="chmod"><function>chmod()</function></link> function in the C library just sets or
1218
clears the FAT-style READONLY attribute. It does not touch any
1219
ACL. Software that needs to manage file permissions on Windows
1220
exactly should use the Win32 API.
1223
See your C library manual for more details about <link linkend="chmod"><function>chmod()</function></link>.</para>
1225
</para><variablelist role="params">
1226
<varlistentry><term><parameter>filename</parameter> :</term>
1227
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1228
</simpara></listitem></varlistentry>
1229
<varlistentry><term><parameter>mode</parameter> :</term>
1230
<listitem><simpara> as in <link linkend="chmod"><function>chmod()</function></link>
1231
</simpara></listitem></varlistentry>
1232
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> zero if the operation succeeded, -1 on error.
1234
</simpara></listitem></varlistentry>
1235
</variablelist><para role="since">Since 2.8</para></refsect2>
1236
<refsect2 id="g-access" role="function" condition="since:2.8">
1237
<title>g_access ()</title>
1238
<indexterm zone="g-access" role="2.8"><primary sortas="access">g_access</primary></indexterm><programlisting><link linkend="int">int</link> g_access (const <link linkend="gchar">gchar</link> *filename,
1239
<link linkend="int">int</link> mode);</programlisting>
1241
A wrapper for the POSIX <link linkend="access"><function>access()</function></link> function. This function is used to
1242
test a pathname for one or several of read, write or execute
1243
permissions, or just existence.
1246
On Windows, the file protection mechanism is not at all POSIX-like,
1247
and the underlying function in the C library only checks the
1248
FAT-style READONLY attribute, and does not look at the ACL of a
1249
file at all. This function is this in practise almost useless on
1250
Windows. Software that needs to handle file permissions on Windows
1251
more exactly should use the Win32 API.
1254
See your C library manual for more details about <link linkend="access"><function>access()</function></link>.</para>
1256
</para><variablelist role="params">
1257
<varlistentry><term><parameter>filename</parameter> :</term>
1258
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1259
</simpara></listitem></varlistentry>
1260
<varlistentry><term><parameter>mode</parameter> :</term>
1261
<listitem><simpara> as in <link linkend="access"><function>access()</function></link>
1262
</simpara></listitem></varlistentry>
1263
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> zero if the pathname refers to an existing file system
1264
object that has all the tested permissions, or -1 otherwise or on
1267
</simpara></listitem></varlistentry>
1268
</variablelist><para role="since">Since 2.8</para></refsect2>
1269
<refsect2 id="g-creat" role="function" condition="since:2.8">
1270
<title>g_creat ()</title>
1271
<indexterm zone="g-creat" role="2.8"><primary sortas="creat">g_creat</primary></indexterm><programlisting><link linkend="int">int</link> g_creat (const <link linkend="gchar">gchar</link> *filename,
1272
<link linkend="int">int</link> mode);</programlisting>
1274
A wrapper for the POSIX <link linkend="creat"><function>creat()</function></link> function. The <link linkend="creat"><function>creat()</function></link> function is
1275
used to convert a pathname into a file descriptor, creating a file
1279
On POSIX systems file descriptors are implemented by the operating
1280
system. On Windows, it's the C library that implements <link linkend="creat"><function>creat()</function></link> and
1281
file descriptors. The actual Windows API for opening files is
1282
different, see MSDN documentation for <link linkend="CreateFile"><function>CreateFile()</function></link>. The Win32 API
1283
uses file handles, which are more randomish integers, not small
1284
integers like file descriptors.
1287
Because file descriptors are specific to the C library on Windows,
1288
the file descriptor returned by this function makes sense only to
1289
functions in the same C library. Thus if the GLib-using code uses a
1290
different C library than GLib does, the file descriptor returned by
1291
this function cannot be passed to C library functions like <link linkend="write"><function>write()</function></link>
1292
or <link linkend="read"><function>read()</function></link>.
1295
See your C library manual for more details about <link linkend="creat"><function>creat()</function></link>.</para>
1297
</para><variablelist role="params">
1298
<varlistentry><term><parameter>filename</parameter> :</term>
1299
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1300
</simpara></listitem></varlistentry>
1301
<varlistentry><term><parameter>mode</parameter> :</term>
1302
<listitem><simpara> as in <link linkend="creat"><function>creat()</function></link>
1303
</simpara></listitem></varlistentry>
1304
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new file descriptor, or -1 if an error occurred. The
1305
return value can be used exactly like the return value from <link linkend="creat"><function>creat()</function></link>.
1307
</simpara></listitem></varlistentry>
1308
</variablelist><para role="since">Since 2.8</para></refsect2>
1309
<refsect2 id="g-chdir" role="function" condition="since:2.8">
1310
<title>g_chdir ()</title>
1311
<indexterm zone="g-chdir" role="2.8"><primary sortas="chdir">g_chdir</primary></indexterm><programlisting><link linkend="int">int</link> g_chdir (const <link linkend="gchar">gchar</link> *path);</programlisting>
1313
A wrapper for the POSIX <link linkend="chdir"><function>chdir()</function></link> function. The function changes the
1314
current directory of the process to <parameter>path</parameter>.
1317
See your C library manual for more details about <link linkend="chdir"><function>chdir()</function></link>.</para>
1319
</para><variablelist role="params">
1320
<varlistentry><term><parameter>path</parameter> :</term>
1321
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1322
</simpara></listitem></varlistentry>
1323
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 on success, -1 if an error occurred.
1325
</simpara></listitem></varlistentry>
1326
</variablelist><para role="since">Since 2.8</para></refsect2>
1327
<refsect2 id="g-utime" role="function" condition="since:2.18">
1328
<title>g_utime ()</title>
1329
<indexterm zone="g-utime" role="2.18"><primary sortas="utime">g_utime</primary></indexterm><programlisting><link linkend="int">int</link> g_utime (const <link linkend="gchar">gchar</link> *filename,
1330
<link linkend="struct-utimbuf">struct utimbuf</link> *utb);</programlisting>
1332
A wrapper for the POSIX <link linkend="utime"><function>utime()</function></link> function. The <link linkend="utime"><function>utime()</function></link> function
1333
sets the access and modification timestamps of a file.
1336
See your C library manual for more details about how <link linkend="utime"><function>utime()</function></link> works
1337
on your system.</para>
1339
</para><variablelist role="params">
1340
<varlistentry><term><parameter>filename</parameter> :</term>
1341
<listitem><simpara> a pathname in the GLib file name encoding (UTF-8 on Windows)
1342
</simpara></listitem></varlistentry>
1343
<varlistentry><term><parameter>utb</parameter> :</term>
1344
<listitem><simpara> a pointer to a struct utimbuf.
1345
</simpara></listitem></varlistentry>
1346
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the operation was successful, -1 if an error
1349
</simpara></listitem></varlistentry>
1350
</variablelist><para role="since">Since 2.18</para></refsect2>
added
removed
docs/reference/glib/xml/fileutils.xml
