1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * gdir.c: Simplified wrapper around the DIRENT functions.
6 * Copyright 2001 Hans Breuer
7 * Copyright 2004 Tor Lillqvist
9 * SPDX-License-Identifier: LGPL-2.1-or-later
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.
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.
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/>.
33 #include <sys/types.h>
40 #include "gfileutils.h"
41 #include "gstrfuncs.h"
42 #include "gtestutils.h"
45 #if defined (_MSC_VER) && !defined (HAVE_DIRENT_H)
46 #include "dirent/dirent.h"
49 #include "glib-private.h" /* g_dir_open_with_errno, g_dir_new_from_dirp */
54 * An opaque structure representing an opened directory.
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];
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.
76 * Opens a directory for reading.
78 * This function is equivalent to g_dir_open() except in the error case,
79 * errno will be set accordingly.
81 * This is useful if you want to construct your own error message.
83 * Returns: a newly allocated #GDir on success, or %NULL on failure,
84 * with errno set accordingly.
89 g_dir_open_with_errno (const gchar *path,
98 g_return_val_if_fail (path != NULL, NULL);
101 wpath = g_utf8_to_utf16 (path, -1, NULL, NULL, NULL);
103 g_return_val_if_fail (wpath != NULL, NULL);
105 dir.wdirp = _wopendir (wpath);
110 if (dir.wdirp == NULL)
113 dir.dirp = opendir (path);
115 if (dir.dirp == NULL)
119 return g_memdup2 (&dir, sizeof dir);
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.
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.
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.
140 g_dir_open (const gchar *path,
147 dir = g_dir_open_with_errno (path, flags);
155 utf8_path = g_filename_to_utf8 (path, -1, NULL, NULL, NULL);
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));
166 * g_dir_new_from_dirp:
167 * @dirp: a #DIR* created by opendir() or fdopendir()
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.
173 * @dirp must not be %NULL.
175 * This function never fails.
177 * Returns: a newly allocated #GDir, which should be closed using
183 g_dir_new_from_dirp (gpointer dirp)
188 g_return_val_if_fail (dirp != NULL, NULL);
190 dir = g_new (GDir, 1);
195 g_assert_not_reached ();
203 * @dir: a #GDir* created by g_dir_open()
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
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.
213 * On Unix, the '.' and '..' entries are omitted, and the returned
214 * name is in the on-disk encoding.
216 * On Windows, as is true of all GLib functions which operate on
217 * filenames, the returned name is in UTF-8.
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.
224 g_dir_read_name (GDir *dir)
228 struct _wdirent *wentry;
230 struct dirent *entry;
233 g_return_val_if_fail (dir != NULL, NULL);
238 wentry = _wreaddir (dir->wdirp);
240 && (0 == wcscmp (wentry->d_name, L".") ||
241 0 == wcscmp (wentry->d_name, L"..")))
242 wentry = _wreaddir (dir->wdirp);
247 utf8_name = g_utf16_to_utf8 (wentry->d_name, -1, NULL, NULL, NULL);
249 if (utf8_name == NULL)
250 continue; /* Huh, impossible? Skip it anyway */
252 strcpy (dir->utf8_buf, utf8_name);
255 return dir->utf8_buf;
258 entry = readdir (dir->dirp);
260 && (0 == strcmp (entry->d_name, ".") ||
261 0 == strcmp (entry->d_name, "..")))
262 entry = readdir (dir->dirp);
265 return entry->d_name;
273 * @dir: a #GDir* created by g_dir_open()
275 * Resets the given directory. The next call to g_dir_read_name()
276 * will return the first entry again.
279 g_dir_rewind (GDir *dir)
281 g_return_if_fail (dir != NULL);
284 _wrewinddir (dir->wdirp);
286 rewinddir (dir->dirp);
292 * @dir: a #GDir* created by g_dir_open()
294 * Closes the directory and deallocates all related resources.
297 g_dir_close (GDir *dir)
299 g_return_if_fail (dir != NULL);
302 _wclosedir (dir->wdirp);
304 closedir (dir->dirp);
311 /* Binary compatibility versions. Not for newly compiled code. */
313 _GLIB_EXTERN GDir *g_dir_open_utf8 (const gchar *path,
316 _GLIB_EXTERN const gchar *g_dir_read_name_utf8 (GDir *dir);
319 g_dir_open_utf8 (const gchar *path,
323 return g_dir_open (path, flags, error);
327 g_dir_read_name_utf8 (GDir *dir)
329 return g_dir_read_name (dir);