glib/gdir.c

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * gdir.c: Simplified wrapper around the DIRENT functions.
   5  *
   6  * Copyright 2001 Hans Breuer
   7  * Copyright 2004 Tor Lillqvist
   8  *
   9  * SPDX-License-Identifier: LGPL-2.1-or-later
  10  *
  11  * This library is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Lesser General Public
  13  * License as published by the Free Software Foundation; either
  14  * version 2.1 of the License, or (at your option) any later version.
  15  *
  16  * This library is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public
  22  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  23  */
  24
  25 #include "config.h"
  26
  27 #include <errno.h>
  28 #include <string.h>
  29 #include <stdio.h>
  30 #include <sys/stat.h>
  31
  32 #ifdef HAVE_DIRENT_H
  33 #include <sys/types.h>
  34 #include <dirent.h>
  35 #endif
  36
  37 #include "gdir.h"
  38
  39 #include "gconvert.h"
  40 #include "gfileutils.h"
  41 #include "gstrfuncs.h"
  42 #include "gtestutils.h"
  43 #include "glibintl.h"
  44
  45 #if defined (_MSC_VER) && !defined (HAVE_DIRENT_H)
  46 #include "dirent/dirent.h"
  47 #endif
  48
  49 #include "glib-private.h" /* g_dir_open_with_errno, g_dir_new_from_dirp */
  50
  51 /**
  52  * GDir:
  53  *
  54  * An opaque structure representing an opened directory.
  55  */
  56
  57 struct _GDir
  58 {
  59 #ifdef G_OS_WIN32
  60   _WDIR *wdirp;
  61 #else
  62   DIR *dirp;
  63 #endif
  64 #ifdef G_OS_WIN32
  65   /* maximum encoding of FILENAME_MAX UTF-8 characters, plus a nul terminator
  66    * (FILENAME_MAX is not guaranteed to include one) */
  67   gchar utf8_buf[FILENAME_MAX*4 + 1];
  68 #endif
  69 };
  70
  71 /*< private >
  72  * g_dir_open_with_errno:
  73  * @path: the path to the directory you are interested in.
  74  * @flags: Currently must be set to 0. Reserved for future use.
  75  *
  76  * Opens a directory for reading.
  77  *
  78  * This function is equivalent to g_dir_open() except in the error case,
  79  * errno will be set accordingly.
  80  *
  81  * This is useful if you want to construct your own error message.
  82  *
  83  * Returns: a newly allocated #GDir on success, or %NULL on failure,
  84  *   with errno set accordingly.
  85  *
  86  * Since: 2.38
  87  */
  88 GDir *
  89 g_dir_open_with_errno (const gchar *path,
  90                        guint        flags)
  91 {
  92   GDir dir;
  93 #ifdef G_OS_WIN32
  94   gint saved_errno;
  95   wchar_t *wpath;
  96 #endif
  97
  98   g_return_val_if_fail (path != NULL, NULL);
  99
 100 #ifdef G_OS_WIN32
 101   wpath = g_utf8_to_utf16 (path, -1, NULL, NULL, NULL);
 102
 103   g_return_val_if_fail (wpath != NULL, NULL);
 104
 105   dir.wdirp = _wopendir (wpath);
 106   saved_errno = errno;
 107   g_free (wpath);
 108   errno = saved_errno;
 109
 110   if (dir.wdirp == NULL)
 111     return NULL;
 112 #else
 113   dir.dirp = opendir (path);
 114
 115   if (dir.dirp == NULL)
 116     return NULL;
 117 #endif
 118
 119   return g_memdup2 (&dir, sizeof dir);
 120 }
 121
 122 /**
 123  * g_dir_open:
 124  * @path: the path to the directory you are interested in. On Unix
 125  *         in the on-disk encoding. On Windows in UTF-8
 126  * @flags: Currently must be set to 0. Reserved for future use.
 127  * @error: return location for a #GError, or %NULL.
 128  *         If non-%NULL, an error will be set if and only if
 129  *         g_dir_open() fails.
 130  *
 131  * Opens a directory for reading. The names of the files in the
 132  * directory can then be retrieved using g_dir_read_name().  Note
 133  * that the ordering is not defined.
 134  *
 135  * Returns: a newly allocated #GDir on success, %NULL on failure.
 136  *   If non-%NULL, you must free the result with g_dir_close()
 137  *   when you are finished with it.
 138  **/
 139 GDir *
 140 g_dir_open (const gchar  *path,
 141             guint         flags,
 142             GError      **error)
 143 {
 144   gint saved_errno;
 145   GDir *dir;
 146
 147   dir = g_dir_open_with_errno (path, flags);
 148
 149   if (dir == NULL)
 150     {
 151       gchar *utf8_path;
 152
 153       saved_errno = errno;
 154
 155       utf8_path = g_filename_to_utf8 (path, -1, NULL, NULL, NULL);
 156
 157       g_set_error (error, G_FILE_ERROR, g_file_error_from_errno (saved_errno),
 158                    _("Error opening directory “%s”: %s"), utf8_path, g_strerror (saved_errno));
 159       g_free (utf8_path);
 160     }
 161
 162   return dir;
 163 }
 164
 165 /*< private >
 166  * g_dir_new_from_dirp:
 167  * @dirp: a #DIR* created by opendir() or fdopendir()
 168  *
 169  * Creates a #GDir object from the DIR object that is created using
 170  * opendir() or fdopendir().  The created #GDir assumes ownership of the
 171  * passed-in #DIR pointer.
 172  *
 173  * @dirp must not be %NULL.
 174  *
 175  * This function never fails.
 176  *
 177  * Returns: a newly allocated #GDir, which should be closed using
 178  *     g_dir_close().
 179  *
 180  * Since: 2.38
 181  **/
 182 GDir *
 183 g_dir_new_from_dirp (gpointer dirp)
 184 {
 185 #ifdef G_OS_UNIX
 186   GDir *dir;
 187
 188   g_return_val_if_fail (dirp != NULL, NULL);
 189
 190   dir = g_new (GDir, 1);
 191   dir->dirp = dirp;
 192
 193   return dir;
 194 #else
 195   g_assert_not_reached ();
 196
 197   return NULL;
 198 #endif
 199 }
 200
 201 /**
 202  * g_dir_read_name:
 203  * @dir: a #GDir* created by g_dir_open()
 204  *
 205  * Retrieves the name of another entry in the directory, or %NULL.
 206  * The order of entries returned from this function is not defined,
 207  * and may vary by file system or other operating-system dependent
 208  * factors.
 209  *
 210  * %NULL may also be returned in case of errors. On Unix, you can
 211  * check `errno` to find out if %NULL was returned because of an error.
 212  *
 213  * On Unix, the '.' and '..' entries are omitted, and the returned
 214  * name is in the on-disk encoding.
 215  *
 216  * On Windows, as is true of all GLib functions which operate on
 217  * filenames, the returned name is in UTF-8.
 218  *
 219  * Returns: (type filename): The entry's name or %NULL if there are no
 220  *   more entries. The return value is owned by GLib and
 221  *   must not be modified or freed.
 222  **/
 223 const gchar *
 224 g_dir_read_name (GDir *dir)
 225 {
 226 #ifdef G_OS_WIN32
 227   gchar *utf8_name;
 228   struct _wdirent *wentry;
 229 #else
 230   struct dirent *entry;
 231 #endif
 232
 233   g_return_val_if_fail (dir != NULL, NULL);
 234
 235 #ifdef G_OS_WIN32
 236   while (1)
 237     {
 238       wentry = _wreaddir (dir->wdirp);
 239       while (wentry
 240              && (0 == wcscmp (wentry->d_name, L".") ||
 241                  0 == wcscmp (wentry->d_name, L"..")))
 242         wentry = _wreaddir (dir->wdirp);
 243
 244       if (wentry == NULL)
 245         return NULL;
 246
 247       utf8_name = g_utf16_to_utf8 (wentry->d_name, -1, NULL, NULL, NULL);
 248
 249       if (utf8_name == NULL)
 250         continue;               /* Huh, impossible? Skip it anyway */
 251
 252       strcpy (dir->utf8_buf, utf8_name);
 253       g_free (utf8_name);
 254
 255       return dir->utf8_buf;
 256     }
 257 #else
 258   entry = readdir (dir->dirp);
 259   while (entry
 260          && (0 == strcmp (entry->d_name, ".") ||
 261              0 == strcmp (entry->d_name, "..")))
 262     entry = readdir (dir->dirp);
 263
 264   if (entry)
 265     return entry->d_name;
 266   else
 267     return NULL;
 268 #endif
 269 }
 270
 271 /**
 272  * g_dir_rewind:
 273  * @dir: a #GDir* created by g_dir_open()
 274  *
 275  * Resets the given directory. The next call to g_dir_read_name()
 276  * will return the first entry again.
 277  **/
 278 void
 279 g_dir_rewind (GDir *dir)
 280 {
 281   g_return_if_fail (dir != NULL);
 282
 283 #ifdef G_OS_WIN32
 284   _wrewinddir (dir->wdirp);
 285 #else
 286   rewinddir (dir->dirp);
 287 #endif
 288 }
 289
 290 /**
 291  * g_dir_close:
 292  * @dir: a #GDir* created by g_dir_open()
 293  *
 294  * Closes the directory and deallocates all related resources.
 295  **/
 296 void
 297 g_dir_close (GDir *dir)
 298 {
 299   g_return_if_fail (dir != NULL);
 300
 301 #ifdef G_OS_WIN32
 302   _wclosedir (dir->wdirp);
 303 #else
 304   closedir (dir->dirp);
 305 #endif
 306   g_free (dir);
 307 }
 308
 309 #ifdef G_OS_WIN32
 310
 311 /* Binary compatibility versions. Not for newly compiled code. */
 312
 313 _GLIB_EXTERN GDir        *g_dir_open_utf8      (const gchar  *path,
 314                                                 guint         flags,
 315                                                 GError      **error);
 316 _GLIB_EXTERN const gchar *g_dir_read_name_utf8 (GDir         *dir);
 317
 318 GDir *
 319 g_dir_open_utf8 (const gchar  *path,
 320                  guint         flags,
 321                  GError      **error)
 322 {
 323   return g_dir_open (path, flags, error);
 324 }
 325
 326 const gchar *
 327 g_dir_read_name_utf8 (GDir *dir)
 328 {
 329   return g_dir_read_name (dir);
 330 }
 331
 332 #endif