glib/gfileutils.h

   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__ */