Branch data Line data Source code
1 : : /* gstdio.h - GFilename wrappers for C library functions
2 : : *
3 : : * Copyright 2004 Tor Lillqvist
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_STDIO_H__
22 : : #define __G_STDIO_H__
23 : :
24 : : #include <glib/gprintf.h>
25 : :
26 : : #include <errno.h>
27 : : #include <sys/stat.h>
28 : :
29 : : G_BEGIN_DECLS
30 : :
31 : : #if (defined (__MINGW64_VERSION_MAJOR) || defined (_MSC_VER)) && !defined(_WIN64)
32 : :
33 : : /* Make it clear that we mean the struct with 32-bit st_size and
34 : : * 32-bit st_*time fields as that is how the 32-bit GLib DLL normally
35 : : * has been compiled. If you get a compiler warning when calling
36 : : * g_stat(), do take it seriously and make sure that the type of
37 : : * struct stat the code in GLib fills in matches the struct the type
38 : : * of struct stat you pass to g_stat(). To avoid hassle, to get file
39 : : * attributes just use the GIO API instead which doesn't use struct
40 : : * stat.
41 : : *
42 : : * Sure, it would be nicer to use a struct with 64-bit st_size and
43 : : * 64-bit st_*time fields, but changing that now would break ABI. And
44 : : * in MinGW, a plain "struct stat" is the one with 32-bit st_size and
45 : : * st_*time fields.
46 : : */
47 : :
48 : : typedef struct _stat32 GStatBuf;
49 : :
50 : : #elif defined(__MINGW64_VERSION_MAJOR) && defined(_WIN64)
51 : :
52 : : typedef struct _stat64 GStatBuf;
53 : :
54 : : #else
55 : :
56 : : typedef struct stat GStatBuf;
57 : :
58 : : #endif
59 : :
60 : : #if defined(G_OS_UNIX) && !defined(G_STDIO_WRAP_ON_UNIX) && !defined(__GI_SCANNER__)
61 : :
62 : : /* Just pass on to the system functions, so there's no potential for data
63 : : * format mismatches, especially with large file interfaces.
64 : : * A few functions can't be handled in this way, since they are not defined
65 : : * in a portable system header that we could include here.
66 : : *
67 : : * G_STDIO_WRAP_ON_UNIX is not public API and its behaviour is not guaranteed
68 : : * in future.
69 : : */
70 : :
71 : : #ifndef __GTK_DOC_IGNORE__
72 : : #define g_chmod chmod
73 : : #define g_open open
74 : : #define g_creat creat
75 : : #define g_rename rename
76 : : #define g_mkdir mkdir
77 : : #define g_stat stat
78 : : #define g_lstat lstat
79 : : #define g_remove remove
80 : : #define g_fopen fopen
81 : : #define g_freopen freopen
82 : : #define g_fsync fsync
83 : : #define g_utime utime
84 : : #endif
85 : :
86 : : GLIB_AVAILABLE_IN_ALL
87 : : int g_access (const gchar *filename,
88 : : int mode);
89 : :
90 : : GLIB_AVAILABLE_IN_ALL
91 : : int g_chdir (const gchar *path);
92 : :
93 : : GLIB_AVAILABLE_IN_ALL
94 : : int g_unlink (const gchar *filename);
95 : :
96 : : GLIB_AVAILABLE_IN_ALL
97 : : int g_rmdir (const gchar *filename);
98 : :
99 : : #else /* ! G_OS_UNIX */
100 : :
101 : : /* Wrappers for C library functions that take pathname arguments. On
102 : : * Unix, the pathname is a file name as it literally is in the file
103 : : * system. On well-maintained systems with consistent users who know
104 : : * what they are doing and no exchange of files with others this would
105 : : * be a well-defined encoding, preferably UTF-8. On Windows, the
106 : : * pathname is always in UTF-8, even if that is not the on-disk
107 : : * encoding, and not the encoding accepted by the C library or Win32
108 : : * API.
109 : : */
110 : :
111 : : GLIB_AVAILABLE_IN_ALL
112 : : int g_access (const gchar *filename,
113 : : int mode);
114 : :
115 : : GLIB_AVAILABLE_IN_ALL
116 : : int g_chmod (const gchar *filename,
117 : : int mode);
118 : :
119 : : GLIB_AVAILABLE_IN_ALL
120 : : int g_open (const gchar *filename,
121 : : int flags,
122 : : int mode);
123 : :
124 : : GLIB_AVAILABLE_IN_ALL
125 : : int g_creat (const gchar *filename,
126 : : int mode);
127 : :
128 : : GLIB_AVAILABLE_IN_ALL
129 : : int g_rename (const gchar *oldfilename,
130 : : const gchar *newfilename);
131 : :
132 : : GLIB_AVAILABLE_IN_ALL
133 : : int g_mkdir (const gchar *filename,
134 : : int mode);
135 : :
136 : : GLIB_AVAILABLE_IN_ALL
137 : : int g_chdir (const gchar *path);
138 : :
139 : : GLIB_AVAILABLE_IN_ALL
140 : : int g_stat (const gchar *filename,
141 : : GStatBuf *buf);
142 : :
143 : : GLIB_AVAILABLE_IN_ALL
144 : : int g_lstat (const gchar *filename,
145 : : GStatBuf *buf);
146 : :
147 : : GLIB_AVAILABLE_IN_ALL
148 : : int g_unlink (const gchar *filename);
149 : :
150 : : GLIB_AVAILABLE_IN_ALL
151 : : int g_remove (const gchar *filename);
152 : :
153 : : GLIB_AVAILABLE_IN_ALL
154 : : int g_rmdir (const gchar *filename);
155 : :
156 : : GLIB_AVAILABLE_IN_ALL
157 : : FILE *g_fopen (const gchar *filename,
158 : : const gchar *mode);
159 : :
160 : : GLIB_AVAILABLE_IN_ALL
161 : : FILE *g_freopen (const gchar *filename,
162 : : const gchar *mode,
163 : : FILE *stream);
164 : :
165 : : GLIB_AVAILABLE_IN_2_64
166 : : gint g_fsync (gint fd);
167 : :
168 : : struct utimbuf; /* Don't need the real definition of struct utimbuf when just
169 : : * including this header.
170 : : */
171 : :
172 : : GLIB_AVAILABLE_IN_ALL
173 : : int g_utime (const gchar *filename,
174 : : struct utimbuf *utb);
175 : :
176 : : #endif /* G_OS_UNIX */
177 : :
178 : : GLIB_AVAILABLE_IN_2_36
179 : : gboolean g_close (gint fd,
180 : : GError **error);
181 : :
182 : : /**
183 : : * g_clear_fd: (skip)
184 : : * @fd_ptr: (not optional) (inout) (transfer full): a pointer to a file descriptor
185 : : * @error: Used to return an error on failure
186 : : *
187 : : * If @fd_ptr points to a file descriptor, close it and return
188 : : * whether closing it was successful, like g_close().
189 : : * If @fd_ptr points to a negative number, return %TRUE without closing
190 : : * anything.
191 : : * In both cases, set @fd_ptr to `-1` before returning.
192 : : *
193 : : * Like g_close(), if closing the file descriptor fails, the error is
194 : : * stored in both %errno and @error. If this function succeeds,
195 : : * %errno is undefined.
196 : : *
197 : : * On POSIX platforms, this function is async-signal safe
198 : : * if @error is %NULL and @fd_ptr points to either a negative number or a
199 : : * valid open file descriptor.
200 : : * This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc
201 : : * under those conditions.
202 : : * See [`signal(7)`](man:signal(7)) and
203 : : * [`signal-safety(7)`](man:signal-safety(7)) for more details.
204 : : *
205 : : * It is a programming error for @fd_ptr to point to a non-negative
206 : : * number that is not a valid file descriptor.
207 : : *
208 : : * A typical use of this function is to clean up a file descriptor at
209 : : * the end of its scope, whether it has been set successfully or not:
210 : : *
211 : : * |[
212 : : * gboolean
213 : : * operate_on_fd (GError **error)
214 : : * {
215 : : * gboolean ret = FALSE;
216 : : * int fd = -1;
217 : : *
218 : : * fd = open_a_fd (error);
219 : : *
220 : : * if (fd < 0)
221 : : * goto out;
222 : : *
223 : : * if (!do_something (fd, error))
224 : : * goto out;
225 : : *
226 : : * if (!g_clear_fd (&fd, error))
227 : : * goto out;
228 : : *
229 : : * ret = TRUE;
230 : : *
231 : : * out:
232 : : * // OK to call even if fd was never opened or was already closed
233 : : * g_clear_fd (&fd, NULL);
234 : : * return ret;
235 : : * }
236 : : * ]|
237 : : *
238 : : * This function is also useful in conjunction with #g_autofd.
239 : : *
240 : : * Returns: %TRUE on success
241 : : * Since: 2.76
242 : : */
243 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_76
244 : : static inline gboolean g_clear_fd (int *fd_ptr,
245 : : GError **error);
246 : :
247 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_76
248 : : static inline gboolean
249 : 11798 : g_clear_fd (int *fd_ptr,
250 : : GError **error)
251 : : {
252 : 11798 : int fd = *fd_ptr;
253 : :
254 : 11798 : *fd_ptr = -1;
255 : :
256 : 11798 : if (fd < 0)
257 : 4936 : return TRUE;
258 : :
259 : : /* Suppress "Not available before" warning */
260 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
261 : 6862 : return g_close (fd, error);
262 : : G_GNUC_END_IGNORE_DEPRECATIONS
263 : : }
264 : :
265 : : /* g_autofd should be defined on the same compilers where g_autofree is
266 : : * This avoids duplicating the feature-detection here. */
267 : : #ifdef g_autofree
268 : : #ifndef __GTK_DOC_IGNORE__
269 : : /* Not public API */
270 : : static inline void
271 : 3 : _g_clear_fd_ignore_error (int *fd_ptr)
272 : : {
273 : : /* Don't overwrite thread-local errno if closing the fd fails */
274 : 3 : int errsv = errno;
275 : :
276 : : /* Suppress "Not available before" warning */
277 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
278 : :
279 : 3 : if (!g_clear_fd (fd_ptr, NULL))
280 : : {
281 : : /* Do nothing: we ignore all errors, except for EBADF which
282 : : * is a programming error, checked for by g_close(). */
283 : : }
284 : :
285 : : G_GNUC_END_IGNORE_DEPRECATIONS
286 : :
287 : 3 : errno = errsv;
288 : 3 : }
289 : : #endif
290 : :
291 : : #define g_autofd _GLIB_CLEANUP(_g_clear_fd_ignore_error) GLIB_AVAILABLE_MACRO_IN_2_76
292 : : #endif
293 : :
294 : : G_END_DECLS
295 : :
296 : : #endif /* __G_STDIO_H__ */
|
