glib-2.0/glib/gstdio.h

0001 /* gstdio.h - GFilename wrappers for C library functions
0002  *
0003  * Copyright 2004 Tor Lillqvist
0004  *
0005  * SPDX-License-Identifier: LGPL-2.1-or-later
0006  *
0007  * This library is free software; you can redistribute it and/or
0008  * modify it under the terms of the GNU Lesser General Public
0009  * License as published by the Free Software Foundation; either
0010  * version 2.1 of the License, or (at your option) any later version.
0011  *
0012  * This library is distributed in the hope that it will be useful,
0013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0015  * Lesser General Public License for more details.
0016  *
0017  * You should have received a copy of the GNU Lesser General Public License
0018  * along with this library; if not, see <http://www.gnu.org/licenses/>.
0019  */
0020
0021 #ifndef __G_STDIO_H__
0022 #define __G_STDIO_H__
0023
0024 #include <glib/gprintf.h>
0025
0026 #include <errno.h>
0027 #include <sys/stat.h>
0028
0029 G_BEGIN_DECLS
0030
0031 #if (defined (__MINGW64_VERSION_MAJOR) || defined (_MSC_VER)) && !defined(_WIN64)
0032
0033 /* Make it clear that we mean the struct with 32-bit st_size and
0034  * 32-bit st_*time fields as that is how the 32-bit GLib DLL normally
0035  * has been compiled. If you get a compiler warning when calling
0036  * g_stat(), do take it seriously and make sure that the type of
0037  * struct stat the code in GLib fills in matches the struct the type
0038  * of struct stat you pass to g_stat(). To avoid hassle, to get file
0039  * attributes just use the GIO API instead which doesn't use struct
0040  * stat.
0041  *
0042  * Sure, it would be nicer to use a struct with 64-bit st_size and
0043  * 64-bit st_*time fields, but changing that now would break ABI. And
0044  * in MinGW, a plain "struct stat" is the one with 32-bit st_size and
0045  * st_*time fields.
0046  */
0047
0048 typedef struct _stat32 GStatBuf;
0049
0050 #elif defined(__MINGW64_VERSION_MAJOR) && defined(_WIN64)
0051
0052 typedef struct _stat64 GStatBuf;
0053
0054 #else
0055
0056 typedef struct stat GStatBuf;
0057
0058 #endif
0059
0060 #if defined(G_OS_UNIX) && !defined(G_STDIO_WRAP_ON_UNIX) && !defined(__GI_SCANNER__)
0061
0062 /* Just pass on to the system functions, so there's no potential for data
0063  * format mismatches, especially with large file interfaces.
0064  * A few functions can't be handled in this way, since they are not defined
0065  * in a portable system header that we could include here.
0066  *
0067  * G_STDIO_WRAP_ON_UNIX is not public API and its behaviour is not guaranteed
0068  * in future.
0069  */
0070
0071 #ifndef __GTK_DOC_IGNORE__
0072 #define g_chmod   chmod
0073 #define g_open    open
0074 #define g_creat   creat
0075 #define g_rename  rename
0076 #define g_mkdir   mkdir
0077 #define g_stat    stat
0078 #define g_lstat   lstat
0079 #define g_remove  remove
0080 #define g_fopen   fopen
0081 #define g_freopen freopen
0082 #define g_fsync   fsync
0083 #define g_utime   utime
0084 #endif
0085
0086 GLIB_AVAILABLE_IN_ALL
0087 int g_access (const gchar *filename,
0088           int          mode);
0089
0090 GLIB_AVAILABLE_IN_ALL
0091 int g_chdir  (const gchar *path);
0092
0093 GLIB_AVAILABLE_IN_ALL
0094 int g_unlink (const gchar *filename);
0095
0096 GLIB_AVAILABLE_IN_ALL
0097 int g_rmdir  (const gchar *filename);
0098
0099 #else /* ! G_OS_UNIX */
0100
0101 /* Wrappers for C library functions that take pathname arguments. On
0102  * Unix, the pathname is a file name as it literally is in the file
0103  * system. On well-maintained systems with consistent users who know
0104  * what they are doing and no exchange of files with others this would
0105  * be a well-defined encoding, preferably UTF-8. On Windows, the
0106  * pathname is always in UTF-8, even if that is not the on-disk
0107  * encoding, and not the encoding accepted by the C library or Win32
0108  * API.
0109  */
0110
0111 GLIB_AVAILABLE_IN_ALL
0112 int g_access    (const gchar *filename,
0113          int          mode);
0114
0115 GLIB_AVAILABLE_IN_ALL
0116 int g_chmod     (const gchar *filename,
0117          int          mode);
0118
0119 GLIB_AVAILABLE_IN_ALL
0120 int g_open      (const gchar *filename,
0121                  int          flags,
0122                  int          mode);
0123
0124 GLIB_AVAILABLE_IN_ALL
0125 int g_creat     (const gchar *filename,
0126                  int          mode);
0127
0128 GLIB_AVAILABLE_IN_ALL
0129 int g_rename    (const gchar *oldfilename,
0130                  const gchar *newfilename);
0131
0132 GLIB_AVAILABLE_IN_ALL
0133 int g_mkdir     (const gchar *filename,
0134                  int          mode);
0135
0136 GLIB_AVAILABLE_IN_ALL
0137 int g_chdir     (const gchar *path);
0138
0139 GLIB_AVAILABLE_IN_ALL
0140 int g_stat      (const gchar *filename,
0141                  GStatBuf    *buf);
0142
0143 GLIB_AVAILABLE_IN_ALL
0144 int g_lstat     (const gchar *filename,
0145                  GStatBuf    *buf);
0146
0147 GLIB_AVAILABLE_IN_ALL
0148 int g_unlink    (const gchar *filename);
0149
0150 GLIB_AVAILABLE_IN_ALL
0151 int g_remove    (const gchar *filename);
0152
0153 GLIB_AVAILABLE_IN_ALL
0154 int g_rmdir     (const gchar *filename);
0155
0156 GLIB_AVAILABLE_IN_ALL
0157 FILE *g_fopen   (const gchar *filename,
0158                  const gchar *mode);
0159
0160 GLIB_AVAILABLE_IN_ALL
0161 FILE *g_freopen (const gchar *filename,
0162                  const gchar *mode,
0163                  FILE        *stream);
0164
0165 GLIB_AVAILABLE_IN_2_64
0166 gint g_fsync    (gint fd);
0167
0168 struct utimbuf;         /* Don't need the real definition of struct utimbuf when just
0169                  * including this header.
0170                  */
0171
0172 GLIB_AVAILABLE_IN_ALL
0173 int g_utime     (const gchar    *filename,
0174          struct utimbuf *utb);
0175
0176 #endif /* G_OS_UNIX */
0177
0178 GLIB_AVAILABLE_IN_2_36
0179 gboolean g_close (gint       fd,
0180                   GError   **error);
0181
0182 /**
0183  * g_clear_fd: (skip)
0184  * @fd_ptr: (not optional) (inout) (transfer full): a pointer to a file descriptor
0185  * @error: Used to return an error on failure
0186  *
0187  * If @fd_ptr points to a file descriptor, close it and return
0188  * whether closing it was successful, like g_close().
0189  * If @fd_ptr points to a negative number, return %TRUE without closing
0190  * anything.
0191  * In both cases, set @fd_ptr to `-1` before returning.
0192  *
0193  * Like g_close(), if closing the file descriptor fails, the error is
0194  * stored in both %errno and @error. If this function succeeds,
0195  * %errno is undefined.
0196  *
0197  * On POSIX platforms, this function is async-signal safe
0198  * if @error is %NULL and @fd_ptr points to either a negative number or a
0199  * valid open file descriptor.
0200  * This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc
0201  * under those conditions.
0202  * See [`signal(7)`](man:signal(7)) and
0203  * [`signal-safety(7)`](man:signal-safety(7)) for more details.
0204  *
0205  * It is a programming error for @fd_ptr to point to a non-negative
0206  * number that is not a valid file descriptor.
0207  *
0208  * A typical use of this function is to clean up a file descriptor at
0209  * the end of its scope, whether it has been set successfully or not:
0210  *
0211  * |[
0212  * gboolean
0213  * operate_on_fd (GError **error)
0214  * {
0215  *   gboolean ret = FALSE;
0216  *   int fd = -1;
0217  *
0218  *   fd = open_a_fd (error);
0219  *
0220  *   if (fd < 0)
0221  *     goto out;
0222  *
0223  *   if (!do_something (fd, error))
0224  *     goto out;
0225  *
0226  *   if (!g_clear_fd (&fd, error))
0227  *     goto out;
0228  *
0229  *   ret = TRUE;
0230  *
0231  * out:
0232  *   // OK to call even if fd was never opened or was already closed
0233  *   g_clear_fd (&fd, NULL);
0234  *   return ret;
0235  * }
0236  * ]|
0237  *
0238  * This function is also useful in conjunction with #g_autofd.
0239  *
0240  * Returns: %TRUE on success
0241  * Since: 2.76
0242  */
0243 GLIB_AVAILABLE_STATIC_INLINE_IN_2_76
0244 static inline gboolean g_clear_fd (int     *fd_ptr,
0245                                    GError **error);
0246
0247 GLIB_AVAILABLE_STATIC_INLINE_IN_2_76
0248 static inline gboolean
0249 g_clear_fd (int     *fd_ptr,
0250             GError **error)
0251 {
0252   int fd = *fd_ptr;
0253
0254   *fd_ptr = -1;
0255
0256   if (fd < 0)
0257     return TRUE;
0258
0259   /* Suppress "Not available before" warning */
0260   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0261   return g_close (fd, error);
0262   G_GNUC_END_IGNORE_DEPRECATIONS
0263 }
0264
0265 /* g_autofd should be defined on the same compilers where g_autofree is
0266  * This avoids duplicating the feature-detection here. */
0267 #ifdef g_autofree
0268 #ifndef __GTK_DOC_IGNORE__
0269 /* Not public API */
0270 static inline void
0271 _g_clear_fd_ignore_error (int *fd_ptr)
0272 {
0273   /* Don't overwrite thread-local errno if closing the fd fails */
0274   int errsv = errno;
0275
0276   /* Suppress "Not available before" warning */
0277   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0278
0279   if (!g_clear_fd (fd_ptr, NULL))
0280     {
0281       /* Do nothing: we ignore all errors, except for EBADF which
0282        * is a programming error, checked for by g_close(). */
0283     }
0284
0285   G_GNUC_END_IGNORE_DEPRECATIONS
0286
0287   errno = errsv;
0288 }
0289 #endif
0290
0291 #define g_autofd _GLIB_CLEANUP(_g_clear_fd_ignore_error) GLIB_AVAILABLE_MACRO_IN_2_76
0292 #endif
0293
0294 G_END_DECLS
0295
0296 #endif /* __G_STDIO_H__ */