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  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 #include "config.h"
  25
  26 #include <errno.h>
  27 #include <string.h> /* strcmp */
  28
  29 #ifdef HAVE_DIRENT_H
  30 #include <sys/types.h>
  31 #include <dirent.h>
  32 #endif
  33
  34 #include "galias.h"
  35 #include "glib.h"
  36 #include "gdir.h"
  37
  38 #include "glibintl.h"
  39
  40 struct _GDir
  41 {
  42   DIR *dir;
  43 };
  44
  45 /**
  46  * g_dir_open:
  47  * @path: the path to the directory you are interested in
  48  * @flags: Currently must be set to 0. Reserved for future use.
  49  * @error: return location for a #GError, or %NULL.
  50  *         If non-%NULL, an error will be set if and only if
  51  *         g_dir_open_fails.
  52  *
  53  * Opens a directory for reading. The names of the files
  54  * in the directory can then be retrieved using
  55  * g_dir_read_name().
  56  *
  57  * Return value: a newly allocated #GDir on success, %NULL on failure.
  58  *   If non-%NULL, you must free the result with g_dir_close()
  59  *   when you are finished with it.
  60  **/
  61 GDir *
  62 g_dir_open (const gchar  *path,
  63             guint         flags,
  64             GError      **error)
  65 {
  66   GDir *dir;
  67   gchar *utf8_path;
  68
  69   g_return_val_if_fail (path != NULL, NULL);
  70
  71   dir = g_new (GDir, 1);
  72
  73   dir->dir = opendir (path);
  74
  75   if (dir->dir)
  76     return dir;
  77
  78   /* error case */
  79   utf8_path = g_filename_to_utf8 (path, -1,
  80                                   NULL, NULL, NULL);
  81   g_set_error (error,
  82                G_FILE_ERROR,
  83                g_file_error_from_errno (errno),
  84                _("Error opening directory '%s': %s"),
  85                utf8_path, g_strerror (errno));
  86
  87   g_free (utf8_path);
  88   g_free (dir);
  89
  90   return NULL;
  91 }
  92
  93 /**
  94  * g_dir_read_name:
  95  * @dir: a #GDir* created by g_dir_open()
  96  *
  97  * Retrieves the name of the next entry in the directory.
  98  * The '.' and '..' entries are omitted. The returned name is in
  99  * the encoding used for filenames. Use g_filename_to_utf8() to
 100  * convert it to UTF-8.
 101  *
 102  * Return value: The entries name or %NULL if there are no
 103  *   more entries. The return value is owned by GLib and
 104  *   must not be modified or freed.
 105  **/
 106 G_CONST_RETURN gchar*
 107 g_dir_read_name (GDir *dir)
 108 {
 109   struct dirent *entry;
 110
 111   g_return_val_if_fail (dir != NULL, NULL);
 112
 113   entry = readdir (dir->dir);
 114   while (entry
 115          && (0 == strcmp (entry->d_name, ".") ||
 116              0 == strcmp (entry->d_name, "..")))
 117     entry = readdir (dir->dir);
 118
 119   if (entry)
 120     return entry->d_name;
 121   else
 122     return NULL;
 123 }
 124
 125 /**
 126  * g_dir_rewind:
 127  * @dir: a #GDir* created by g_dir_open()
 128  *
 129  * Resets the given directory. The next call to g_dir_read_name()
 130  * will return the first entry again.
 131  **/
 132 void
 133 g_dir_rewind (GDir *dir)
 134 {
 135   g_return_if_fail (dir != NULL);
 136
 137   rewinddir (dir->dir);
 138 }
 139
 140 /**
 141  * g_dir_close:
 142  * @dir: a #GDir* created by g_dir_open()
 143  *
 144  * Closes the directory and deallocates all related resources.
 145  **/
 146 void
 147 g_dir_close (GDir *dir)
 148 {
 149   g_return_if_fail (dir != NULL);
 150
 151   closedir (dir->dir);
 152   g_free (dir);
 153 }