5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2008 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program 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
16 GNU General Public License for more details.
20 /****h* silcutil/Directory Interface
24 * The SILC Directory API provides portable way to open and read directories
32 * dir = silc_dir_open("foodir");
34 * while ((entry = silc_dir_read(dir, NULL)))
35 * printf("File name: %s\n", silc_dir_entry_name(entry));
37 * silc_dir_close(dir);
44 /****s* silcutil/SilcDir
48 * typedef struct SilcDirStruct *SilcDir;
52 * The directory context. This is allocated by silc_dir_open and
53 * freed by calling silc_dir_close.
56 typedef struct SilcDirStruct *SilcDir;
58 /****s* silcutil/SilcDirEntry
62 * typedef struct SilcDirEntryStruct *SilcDirEntry;
66 * The directory entry context. The entry is usually a file in the
70 typedef struct SilcDirEntryStruct *SilcDirEntry;
72 /****f* silcutil/silc_dir_open
76 * SilcDir silc_dir_open(const char *name);
80 * Opens the directory named `name' and returns its context. Returns NULL
81 * on error and sets the silc_errno. This function must be called before
82 * being able to read the directory and its contents.
85 SilcDir silc_dir_open(const char *name);
87 /****f* silcutil/silc_dir_close
91 * void silc_dir_close(SilcDir dir);
95 * Closes the directory `dir'.
98 void silc_dir_close(SilcDir dir);
100 /****f* silcutil/silc_dir_read
104 * SilcDirEntry silc_dir_read(SilcDir dir, SilcFileStat status);
108 * Reads next entry (file) from the directory `dir'. The silc_dir_open
109 * must be called first before reading from the directory. Returns the
110 * next entry context or NULL if there are no more entries or error occurs.
111 * In case of error the silc_errno is also set.
113 * If the `status' is non-NULL this will also call silc_file_stat and
114 * returns the status into the `status' pointer.
116 * The returned context remains valid until the silc_dir_read is called
120 SilcDirEntry silc_dir_read(SilcDir dir, SilcFileStat status);
122 /****f* silcutil/silc_dir_rewind
126 * void silc_dir_rewind(SilcDir dir);
130 * Rewinds the directory `dir' to the beginning of the directory. Calling
131 * silc_dir_read after this will return the first entry in the directory.
134 void silc_dir_rewind(SilcDir dir);
136 /****f* silcutil/silc_dir_name
140 * const char *silc_dir_name(SilcDir dir);
144 * Returns the name of the directory from `dir' context.
147 const char *silc_dir_name(SilcDir dir);
149 /****f* silcutil/silc_dir_entry_name
153 * const char *silc_dir_entry_name(SilcDirEntry entry);
157 * Returns the name of the entry (file) `entry'. The returned pointer
158 * remains valid until the silc_dir_read is called again.
161 const char *silc_dir_entry_name(SilcDirEntry entry);
163 #endif /* SILCDIR_H */