1 /* gfileutils.h - File utility functions
2 *
3 * Copyright 2000 Red Hat, Inc.
4 *
5 * SPDX-License-Identifier: LGPL-2.1-or-later
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public License
18 * along with this library; if not, see <http://www.gnu.org/licenses/>.
19 */
20
21 #ifndef __G_FILEUTILS_H__
22 #define __G_FILEUTILS_H__
23
24 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
25 #error "Only <glib.h> can be included directly."
26 #endif
27
28 #include <glibconfig.h>
29 #include <glib/gerror.h>
30
31 G_BEGIN_DECLS
32
33 #define G_FILE_ERROR g_file_error_quark ()
34
35 typedef enum
36 {
37 G_FILE_ERROR_EXIST,
38 G_FILE_ERROR_ISDIR,
39 G_FILE_ERROR_ACCES,
40 G_FILE_ERROR_NAMETOOLONG,
41 G_FILE_ERROR_NOENT,
42 G_FILE_ERROR_NOTDIR,
43 G_FILE_ERROR_NXIO,
44 G_FILE_ERROR_NODEV,
45 G_FILE_ERROR_ROFS,
46 G_FILE_ERROR_TXTBSY,
47 G_FILE_ERROR_FAULT,
48 G_FILE_ERROR_LOOP,
49 G_FILE_ERROR_NOSPC,
50 G_FILE_ERROR_NOMEM,
51 G_FILE_ERROR_MFILE,
52 G_FILE_ERROR_NFILE,
53 G_FILE_ERROR_BADF,
54 G_FILE_ERROR_INVAL,
55 G_FILE_ERROR_PIPE,
56 G_FILE_ERROR_AGAIN,
57 G_FILE_ERROR_INTR,
58 G_FILE_ERROR_IO,
59 G_FILE_ERROR_PERM,
60 G_FILE_ERROR_NOSYS,
61 G_FILE_ERROR_FAILED
62 } GFileError;
63
64 /* For backward-compat reasons, these are synced to an old
65 * anonymous enum in libgnome. But don't use that enum
66 * in new code.
67 */
68 typedef enum
69 {
70 G_FILE_TEST_IS_REGULAR = 1 << 0,
71 G_FILE_TEST_IS_SYMLINK = 1 << 1,
72 G_FILE_TEST_IS_DIR = 1 << 2,
73 G_FILE_TEST_IS_EXECUTABLE = 1 << 3,
74 G_FILE_TEST_EXISTS = 1 << 4
75 } GFileTest;
76
77 /**
78 * GFileSetContentsFlags:
79 * @G_FILE_SET_CONTENTS_NONE: No guarantees about file consistency or durability.
80 * The most dangerous setting, which is slightly faster than other settings.
81 * @G_FILE_SET_CONTENTS_CONSISTENT: Guarantee file consistency: after a crash,
82 * either the old version of the file or the new version of the file will be
83 * available, but not a mixture. On Unix systems this equates to an `fsync()`
84 * on the file and use of an atomic `rename()` of the new version of the file
85 * over the old.
86 * @G_FILE_SET_CONTENTS_DURABLE: Guarantee file durability: after a crash, the
87 * new version of the file will be available. On Unix systems this equates to
88 * an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or
89 * the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the
90 * directory containing the file after calling `rename()`.
91 * @G_FILE_SET_CONTENTS_ONLY_EXISTING: Only apply consistency and durability
92 * guarantees if the file already exists. This may speed up file operations
93 * if the file doesn’t currently exist, but may result in a corrupted version
94 * of the new file if the system crashes while writing it.
95 *
96 * Flags to pass to g_file_set_contents_full() to affect its safety and
97 * performance.
98 *
99 * Since: 2.66
100 */
101 typedef enum
102 {
103 G_FILE_SET_CONTENTS_NONE = 0,
104 G_FILE_SET_CONTENTS_CONSISTENT = 1 << 0,
105 G_FILE_SET_CONTENTS_DURABLE = 1 << 1,
106 G_FILE_SET_CONTENTS_ONLY_EXISTING = 1 << 2
107 } GFileSetContentsFlags
108 GLIB_AVAILABLE_ENUMERATOR_IN_2_66;
109
110 GLIB_AVAILABLE_IN_ALL
111 GQuark g_file_error_quark (void);
112 /* So other code can generate a GFileError */
113 GLIB_AVAILABLE_IN_ALL
114 GFileError g_file_error_from_errno (gint err_no);
115
116 GLIB_AVAILABLE_IN_ALL
117 gboolean g_file_test (const gchar *filename,
118 GFileTest test);
119 GLIB_AVAILABLE_IN_ALL
120 gboolean g_file_get_contents (const gchar *filename,
121 gchar **contents,
122 gsize *length,
123 GError **error);
124 GLIB_AVAILABLE_IN_ALL
125 gboolean g_file_set_contents (const gchar *filename,
126 const gchar *contents,
127 gssize length,
128 GError **error);
129 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
130 GLIB_AVAILABLE_IN_2_66
131 gboolean g_file_set_contents_full (const gchar *filename,
132 const gchar *contents,
133 gssize length,
134 GFileSetContentsFlags flags,
135 int mode,
136 GError **error);
137 G_GNUC_END_IGNORE_DEPRECATIONS
138 GLIB_AVAILABLE_IN_ALL
139 gchar *g_file_read_link (const gchar *filename,
140 GError **error);
141
142 /* Wrapper / workalike for mkdtemp() */
143 GLIB_AVAILABLE_IN_2_30
144 gchar *g_mkdtemp (gchar *tmpl);
145 GLIB_AVAILABLE_IN_2_30
146 gchar *g_mkdtemp_full (gchar *tmpl,
147 gint mode);
148
149 /* Wrapper / workalike for mkstemp() */
150 GLIB_AVAILABLE_IN_ALL
151 gint g_mkstemp (gchar *tmpl);
152 GLIB_AVAILABLE_IN_ALL
153 gint g_mkstemp_full (gchar *tmpl,
154 gint flags,
155 gint mode);
156
157 /* Wrappers for g_mkstemp and g_mkdtemp() */
158 GLIB_AVAILABLE_IN_ALL
159 gint g_file_open_tmp (const gchar *tmpl,
160 gchar **name_used,
161 GError **error);
162 GLIB_AVAILABLE_IN_2_30
163 gchar *g_dir_make_tmp (const gchar *tmpl,
164 GError **error);
165
166 GLIB_AVAILABLE_IN_ALL
167 gchar *g_build_path (const gchar *separator,
168 const gchar *first_element,
169 ...) G_GNUC_MALLOC G_GNUC_NULL_TERMINATED;
170 GLIB_AVAILABLE_IN_ALL
171 gchar *g_build_pathv (const gchar *separator,
172 gchar **args) G_GNUC_MALLOC;
173
174 GLIB_AVAILABLE_IN_ALL
175 gchar *g_build_filename (const gchar *first_element,
176 ...) G_GNUC_MALLOC G_GNUC_NULL_TERMINATED;
177 GLIB_AVAILABLE_IN_ALL
178 gchar *g_build_filenamev (gchar **args) G_GNUC_MALLOC;
179 GLIB_AVAILABLE_IN_2_56
180 gchar *g_build_filename_valist (const gchar *first_element,
181 va_list *args) G_GNUC_MALLOC;
182
183 GLIB_AVAILABLE_IN_ALL
184 gint g_mkdir_with_parents (const gchar *pathname,
185 gint mode);
186
187 #ifdef G_OS_WIN32
188
189 /* On Win32, the canonical directory separator is the backslash, and
190 * the search path separator is the semicolon. Note that also the
191 * (forward) slash works as directory separator.
192 */
193 #define G_IS_DIR_SEPARATOR(c) ((c) == G_DIR_SEPARATOR || (c) == '/')
194
195 #else /* !G_OS_WIN32 */
196
197 #define G_IS_DIR_SEPARATOR(c) ((c) == G_DIR_SEPARATOR)
198
199 #endif /* !G_OS_WIN32 */
200
201 GLIB_AVAILABLE_IN_ALL
202 gboolean g_path_is_absolute (const gchar *file_name);
203 GLIB_AVAILABLE_IN_ALL
204 const gchar *g_path_skip_root (const gchar *file_name);
205
206 GLIB_DEPRECATED_FOR(g_path_get_basename)
207 const gchar *g_basename (const gchar *file_name);
208 #define g_dirname g_path_get_dirname GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_path_get_dirname)
209
210 GLIB_AVAILABLE_IN_ALL
211 gchar *g_get_current_dir (void);
212 GLIB_AVAILABLE_IN_ALL
213 gchar *g_path_get_basename (const gchar *file_name) G_GNUC_MALLOC;
214 GLIB_AVAILABLE_IN_ALL
215 gchar *g_path_get_dirname (const gchar *file_name) G_GNUC_MALLOC;
216
217 GLIB_AVAILABLE_IN_2_58
218 gchar *g_canonicalize_filename (const gchar *filename,
219 const gchar *relative_to) G_GNUC_MALLOC;
220
221 G_END_DECLS
222
223 #endif /* __G_FILEUTILS_H__ */