glib-2.0/glib/gfileutils.h

0001 /* gfileutils.h - File utility functions
0002  *
0003  *  Copyright 2000 Red Hat, Inc.
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_FILEUTILS_H__
0022 #define __G_FILEUTILS_H__
0023
0024 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0025 #error "Only <glib.h> can be included directly."
0026 #endif
0027
0028 #include <glibconfig.h>
0029 #include <glib/gerror.h>
0030
0031 G_BEGIN_DECLS
0032
0033 #define G_FILE_ERROR g_file_error_quark ()
0034
0035 typedef enum
0036 {
0037   G_FILE_ERROR_EXIST,
0038   G_FILE_ERROR_ISDIR,
0039   G_FILE_ERROR_ACCES,
0040   G_FILE_ERROR_NAMETOOLONG,
0041   G_FILE_ERROR_NOENT,
0042   G_FILE_ERROR_NOTDIR,
0043   G_FILE_ERROR_NXIO,
0044   G_FILE_ERROR_NODEV,
0045   G_FILE_ERROR_ROFS,
0046   G_FILE_ERROR_TXTBSY,
0047   G_FILE_ERROR_FAULT,
0048   G_FILE_ERROR_LOOP,
0049   G_FILE_ERROR_NOSPC,
0050   G_FILE_ERROR_NOMEM,
0051   G_FILE_ERROR_MFILE,
0052   G_FILE_ERROR_NFILE,
0053   G_FILE_ERROR_BADF,
0054   G_FILE_ERROR_INVAL,
0055   G_FILE_ERROR_PIPE,
0056   G_FILE_ERROR_AGAIN,
0057   G_FILE_ERROR_INTR,
0058   G_FILE_ERROR_IO,
0059   G_FILE_ERROR_PERM,
0060   G_FILE_ERROR_NOSYS,
0061   G_FILE_ERROR_FAILED
0062 } GFileError;
0063
0064 /* For backward-compat reasons, these are synced to an old
0065  * anonymous enum in libgnome. But don't use that enum
0066  * in new code.
0067  */
0068 typedef enum
0069 {
0070   G_FILE_TEST_IS_REGULAR    = 1 << 0,
0071   G_FILE_TEST_IS_SYMLINK    = 1 << 1,
0072   G_FILE_TEST_IS_DIR        = 1 << 2,
0073   G_FILE_TEST_IS_EXECUTABLE = 1 << 3,
0074   G_FILE_TEST_EXISTS        = 1 << 4
0075 } GFileTest;
0076
0077 /**
0078  * GFileSetContentsFlags:
0079  * @G_FILE_SET_CONTENTS_NONE: No guarantees about file consistency or durability.
0080  *   The most dangerous setting, which is slightly faster than other settings.
0081  * @G_FILE_SET_CONTENTS_CONSISTENT: Guarantee file consistency: after a crash,
0082  *   either the old version of the file or the new version of the file will be
0083  *   available, but not a mixture. On Unix systems this equates to an `fsync()`
0084  *   on the file and use of an atomic `rename()` of the new version of the file
0085  *   over the old.
0086  * @G_FILE_SET_CONTENTS_DURABLE: Guarantee file durability: after a crash, the
0087  *   new version of the file will be available. On Unix systems this equates to
0088  *   an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or
0089  *   the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the
0090  *   directory containing the file after calling `rename()`.
0091  * @G_FILE_SET_CONTENTS_ONLY_EXISTING: Only apply consistency and durability
0092  *   guarantees if the file already exists. This may speed up file operations
0093  *   if the file doesn’t currently exist, but may result in a corrupted version
0094  *   of the new file if the system crashes while writing it.
0095  *
0096  * Flags to pass to g_file_set_contents_full() to affect its safety and
0097  * performance.
0098  *
0099  * Since: 2.66
0100  */
0101 typedef enum
0102 {
0103   G_FILE_SET_CONTENTS_NONE = 0,
0104   G_FILE_SET_CONTENTS_CONSISTENT = 1 << 0,
0105   G_FILE_SET_CONTENTS_DURABLE = 1 << 1,
0106   G_FILE_SET_CONTENTS_ONLY_EXISTING = 1 << 2
0107 } GFileSetContentsFlags
0108 GLIB_AVAILABLE_ENUMERATOR_IN_2_66;
0109
0110 GLIB_AVAILABLE_IN_ALL
0111 GQuark     g_file_error_quark      (void);
0112 /* So other code can generate a GFileError */
0113 GLIB_AVAILABLE_IN_ALL
0114 GFileError g_file_error_from_errno (gint err_no);
0115
0116 GLIB_AVAILABLE_IN_ALL
0117 gboolean g_file_test         (const gchar  *filename,
0118                               GFileTest     test);
0119 GLIB_AVAILABLE_IN_ALL
0120 gboolean g_file_get_contents (const gchar  *filename,
0121                               gchar       **contents,
0122                               gsize        *length,
0123                               GError      **error);
0124 GLIB_AVAILABLE_IN_ALL
0125 gboolean g_file_set_contents (const gchar *filename,
0126                               const gchar *contents,
0127                               gssize         length,
0128                               GError       **error);
0129 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0130 GLIB_AVAILABLE_IN_2_66
0131 gboolean g_file_set_contents_full (const gchar            *filename,
0132                                    const gchar            *contents,
0133                                    gssize                  length,
0134                                    GFileSetContentsFlags   flags,
0135                                    int                     mode,
0136                                    GError                **error);
0137 G_GNUC_END_IGNORE_DEPRECATIONS
0138 GLIB_AVAILABLE_IN_ALL
0139 gchar   *g_file_read_link    (const gchar  *filename,
0140                               GError      **error);
0141
0142 /* Wrapper / workalike for mkdtemp() */
0143 GLIB_AVAILABLE_IN_2_30
0144 gchar   *g_mkdtemp            (gchar        *tmpl);
0145 GLIB_AVAILABLE_IN_2_30
0146 gchar   *g_mkdtemp_full       (gchar        *tmpl,
0147                                gint          mode);
0148
0149 /* Wrapper / workalike for mkstemp() */
0150 GLIB_AVAILABLE_IN_ALL
0151 gint     g_mkstemp            (gchar        *tmpl);
0152 GLIB_AVAILABLE_IN_ALL
0153 gint     g_mkstemp_full       (gchar        *tmpl,
0154                                gint          flags,
0155                                gint          mode);
0156
0157 /* Wrappers for g_mkstemp and g_mkdtemp() */
0158 GLIB_AVAILABLE_IN_ALL
0159 gint     g_file_open_tmp      (const gchar  *tmpl,
0160                                gchar       **name_used,
0161                                GError      **error);
0162 GLIB_AVAILABLE_IN_2_30
0163 gchar   *g_dir_make_tmp       (const gchar  *tmpl,
0164                                GError      **error);
0165
0166 GLIB_AVAILABLE_IN_ALL
0167 gchar   *g_build_path         (const gchar *separator,
0168                                const gchar *first_element,
0169                                ...) G_GNUC_MALLOC G_GNUC_NULL_TERMINATED;
0170 GLIB_AVAILABLE_IN_ALL
0171 gchar   *g_build_pathv        (const gchar  *separator,
0172                                gchar       **args) G_GNUC_MALLOC;
0173
0174 GLIB_AVAILABLE_IN_ALL
0175 gchar   *g_build_filename     (const gchar *first_element,
0176                                ...) G_GNUC_MALLOC G_GNUC_NULL_TERMINATED;
0177 GLIB_AVAILABLE_IN_ALL
0178 gchar   *g_build_filenamev    (gchar      **args) G_GNUC_MALLOC;
0179 GLIB_AVAILABLE_IN_2_56
0180 gchar   *g_build_filename_valist (const gchar  *first_element,
0181                                   va_list      *args) G_GNUC_MALLOC;
0182
0183 GLIB_AVAILABLE_IN_ALL
0184 gint     g_mkdir_with_parents (const gchar *pathname,
0185                                gint         mode);
0186
0187 #ifdef G_OS_WIN32
0188
0189 /* On Win32, the canonical directory separator is the backslash, and
0190  * the search path separator is the semicolon. Note that also the
0191  * (forward) slash works as directory separator.
0192  */
0193 #define G_IS_DIR_SEPARATOR(c) ((c) == G_DIR_SEPARATOR || (c) == '/')
0194
0195 #else  /* !G_OS_WIN32 */
0196
0197 #define G_IS_DIR_SEPARATOR(c) ((c) == G_DIR_SEPARATOR)
0198
0199 #endif /* !G_OS_WIN32 */
0200
0201 GLIB_AVAILABLE_IN_ALL
0202 gboolean     g_path_is_absolute (const gchar *file_name);
0203 GLIB_AVAILABLE_IN_ALL
0204 const gchar *g_path_skip_root   (const gchar *file_name);
0205
0206 GLIB_DEPRECATED_FOR(g_path_get_basename)
0207 const gchar *g_basename         (const gchar *file_name);
0208 #define g_dirname g_path_get_dirname GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_path_get_dirname)
0209
0210 GLIB_AVAILABLE_IN_ALL
0211 gchar *g_get_current_dir   (void);
0212 GLIB_AVAILABLE_IN_ALL
0213 gchar *g_path_get_basename (const gchar *file_name) G_GNUC_MALLOC;
0214 GLIB_AVAILABLE_IN_ALL
0215 gchar *g_path_get_dirname  (const gchar *file_name) G_GNUC_MALLOC;
0216
0217 GLIB_AVAILABLE_IN_2_58
0218 gchar *g_canonicalize_filename (const gchar *filename,
0219                                 const gchar *relative_to) G_GNUC_MALLOC;
0220
0221 G_END_DECLS
0222
0223 #endif /* __G_FILEUTILS_H__ */