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/SILC 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", silc_dir_entry_name(entry));
37 * silc_dir_close(dir);
44 /****s* silcutil/SilcDirAPI/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/SilcDirAPI/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 /****d* silcutil/SilcDirAPI/SilcDirEntryMode
76 * typedef enum { ... } SilcDirEntryMode;
80 * The directory entry mode bits. These bits specify the entry mode,
81 * type and protection.
86 SILC_DIR_ENTRY_IFDIR = 0x00000001, /* Entry is directory */
87 SILC_DIR_ENTRY_IFCHR = 0x00000002, /* Entry is character device */
88 SILC_DIR_ENTRY_IFBLK = 0x00000004, /* Entry is block device */
89 SILC_DIR_ENTRY_IFREG = 0x00000008, /* Entry is regular file */
90 SILC_DIR_ENTRY_IFIFO = 0x00000010, /* Entry is FIFO */
91 SILC_DIR_ENTRY_IFLNK = 0x00000020, /* Entry is symbolic link */
92 SILC_DIR_ENTRY_IFSOCK = 0x00000040, /* Entry is socket */
95 SILC_DIR_ENTRY_IRUSR = 0x00000080, /* Owner has read permission */
96 SILC_DIR_ENTRY_IWUSR = 0x00000100, /* Owner has write permission */
97 SILC_DIR_ENTRY_IXUSR = 0x00000200, /* Owner has execute permission */
98 SILC_DIR_ENTRY_IRGRP = 0x00000400, /* Group has read permission */
99 SILC_DIR_ENTRY_IWGRP = 0x00000800, /* Group has write permission */
100 SILC_DIR_ENTRY_IXGRP = 0x00001000, /* Group has execute permission */
101 SILC_DIR_ENTRY_IROTH = 0x00002000, /* Others have read permission */
102 SILC_DIR_ENTRY_IWOTH = 0x00004000, /* Others have write permission */
103 SILC_DIR_ENTRY_IXOTH = 0x00008000, /* Others have execute permission */
106 /****s* silcutil/SilcDirAPI/SilcDirEntryStat
110 * typedef struct SilcDirEntryObject { ... } *SilcDirEntryStat,
111 * SilcDirEntryStatStruct;
115 * The directory entry status information structure. The structure
116 * contains various information about the entry in the directory.
117 * This context is returned by silc_dir_read or silc_dir_entry_stat.
120 typedef struct SilcDirEntryStatObject {
121 SilcTimeStruct last_access; /* Time of last access */
122 SilcTimeStruct last_mod; /* Time of last modification */
123 SilcTimeStruct last_change; /* Time of last status change */
124 SilcUInt64 size; /* Entry size in bytes */
125 SilcUInt32 uid; /* Owner ID of the entry */
126 SilcUInt32 gid; /* Group owner ID of the entry */
127 SilcUInt32 dev; /* Entry device number */
128 SilcUInt32 nlink; /* Number of hard links */
129 SilcDirEntryMode mode; /* Entry mode */
130 } *SilcDirEntryStat, SilcDirEntryStatStruct;
132 /****f* silcutil/SilcDirAPI/silc_dir_open
136 * SilcDir silc_dir_open(const char *name);
140 * Opens the directory named `name' and returns its context. Returns NULL
141 * on error and sets the silc_errno. This function must be called before
142 * being able to read the directory and its contents.
145 SilcDir silc_dir_open(const char *name);
147 /****f* silcutil/SilcDirAPI/silc_dir_close
151 * void silc_dir_close(SilcDir dir);
155 * Closes the directory `dir'.
158 void silc_dir_close(SilcDir dir);
160 /****f* silcutil/SilcDirAPI/silc_dir_read
164 * SilcDirEntry silc_dir_read(SilcDir dir, SilcDirEntryStat *status);
168 * Reads next entry (file) from the directory `dir'. The silc_dir_open
169 * must be called first before reading from the directory. Returns the
170 * next entry context or NULL if there are no more entries or error occurs.
171 * In case of error the silc_errno is also set.
173 * If the `status' is non-NULL this will also call silc_dir_entry_stat
174 * and returns the status into the `status' pointer.
176 * The returned context remains valid until the silc_dir_read is called
180 SilcDirEntry silc_dir_read(SilcDir dir, SilcDirEntryStat *status);
182 /****f* silcutil/SilcDirAPI/silc_dir_rewind
186 * void silc_dir_rewind(SilcDir dir);
190 * Rewinds the directory `dir' to the beginning of the directory. Calling
191 * silc_dir_read after this will return the first entry in the directory.
194 void silc_dir_rewind(SilcDir dir);
196 /****f* silcutil/SilcDirAPI/silc_dir_name
200 * const char *silc_dir_name(SilcDir dir);
204 * Returns the name of the directory from `dir' context.
207 const char *silc_dir_name(SilcDir dir);
209 /****f* silcutil/SilcDirAPI/silc_dir_entry_name
213 * const char *silc_dir_entry_name(SilcDirEntry entry);
217 * Returns the name of the entry (file) `entry'. The returned pointer
218 * remains valid until the silc_dir_read is called again.
221 const char *silc_dir_entry_name(SilcDirEntry entry);
223 /****f* silcutil/SilcDirAPI/silc_dir_entry_stat
227 * SilcDirEntryStat silc_dir_entry_stat(SilcDir dir, SilcDirEntry entry);
231 * Returns the status of the entry. The status context contains details
232 * of the entry (file) in the directory. Returns NULL on error and sets
235 * The returned contest is valid until the silc_dir_read is called again.
238 SilcDirEntryStat silc_dir_entry_stat(SilcDir dir, SilcDirEntry entry);
240 #endif /* SILCDIR_H */