KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
dirent.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  dirent.h
4  Copyright (C) 2003 Dan Potter
5 
6 */
7 
8 /** \file dirent.h
9  \brief Directory entry functionality.
10 
11  This partially implements the standard POSIX dirent.h functionality.
12 
13  \author Dan Potter
14 */
15 
16 #ifndef __SYS_DIRENT_H
17 #define __SYS_DIRENT_H
18 
19 #include <unistd.h>
20 #include <arch/types.h>
21 #include <kos/fs.h>
22 
23 /** \brief POSIX directory entry structure.
24 
25  This structure contains information about a single entry in a directory in
26  the VFS.
27 
28  \headerfile sys/dirent.h
29  */
30 struct dirent {
31  int d_ino; /**< \brief File unique identifier. */
32  off_t d_off; /**< \brief File offset */
33  uint16 d_reclen; /**< \brief Record length */
34  uint8 d_type; /**< \brief File type */
35  char d_name[256]; /**< \brief Filename */
36 };
37 
38 /** \brief Type representing a directory stream.
39 
40  This type represents a directory stream and is used by the directory reading
41  functions to trace their position in the directory.
42 
43  The values in this function are all private and subject to change. Do not
44  attempt to use any of them directly.
45 
46  \headerfile sys/dirent.h
47 */
48 typedef struct {
49  file_t fd; /**< \brief File descriptor for the directory */
50  struct dirent d_ent; /**< \brief Current directory entry */
51 } DIR;
52 
53 // Standard UNIX dir functions. Not all of these are fully functional
54 // right now due to lack of support in KOS.
55 
56 /** \brief Open a directory based on the specified name.
57 
58  The directory specified is opened if it exists. A directory stream object is
59  returned for accessing the entries of the directory.
60 
61  \param name The name of the directory to open.
62  \return A directory stream object to be used with readdir() on
63  success, NULL on failure. Sets errno as appropriate.
64  \note As with other functions for opening files on the VFS,
65  relative paths are permitted for the name parameter of
66  this function.
67  \see closedir
68  \see readdir
69 */
70 DIR *opendir(const char *name);
71 
72 /** \brief Closes a directory that was previously opened.
73 
74  This function is used to close a directory stream that was previously opened
75  with the opendir() function. You must do this to clean up any resources
76  associated with the directory stream.
77 
78  \param dir The directory stream to close.
79  \return 0 on success. -1 on error, setting errno as appropriate.
80 */
81 int closedir(DIR *dir);
82 
83 /** \brief Read an entry from a directory stream.
84 
85  This function reads the next entry from the directory stream provided,
86  returning the directory entry associated with the next object in the
87  directory.
88 
89  \param dir The directory stream to read from.
90  \return A pointer to the next directory entry in the directory
91  or NULL if there are no other entries in the directory.
92  If an error is incurred, NULL will be returned and errno
93  set to indicate the error.
94 
95  \note Do not free the returned dirent!
96 */
97 struct dirent *readdir(DIR *dir);
98 
99 /** \brief Retrieve the file descriptor of an opened directory stream.
100 
101  This function retrieves the file descriptor of a directory stream that was
102  previously opened with opendir().
103 
104  \param dirp The directory stream to retrieve the descriptor of.
105  \return The file descriptor from the directory stream on success
106  or -1 on failure (sets errno as appropriate).
107 
108  \note Do not close() the returned file descriptor. It will be
109  closed when closedir() is called on the directory
110  stream.
111 */
112 int dirfd(DIR *dirp);
113 
114 /** \brief Rewind a directory stream to the start of the directory.
115 
116  This function rewinds the directory stream so that the next call to the
117  readdir() function will return the first entry in the directory.
118 
119  \param dir The directory stream to rewind.
120 
121  \note Some filesystems do not support this call. Notably, none
122  of the dcload filesystems support it. Error values will
123  be returned in errno (so set errno to 0, then check
124  after calling the function to see if there was a problem
125  anywhere).
126 */
127 void rewinddir(DIR *dir);
128 
129 /** \brief Not implemented */
130 int scandir(const char *dir, struct dirent ***namelist,
131  int(*filter)(const struct dirent *),
132  int(*compar)(const struct dirent **, const struct dirent **));
133 /** \brief Not implemented */
134 void seekdir(DIR *dir, off_t offset);
135 /** \brief Not implemented */
136 off_t telldir(DIR *dir);
137 
138 #endif
Common integer types.
DIR * opendir(const char *name)
Open a directory based on the specified name.
void rewinddir(DIR *dir)
Rewind a directory stream to the start of the directory.
Virtual filesystem support.
POSIX directory entry structure.
Definition: dirent.h:30
struct dirent * readdir(DIR *dir)
Read an entry from a directory stream.
uint16 d_reclen
Record length.
Definition: dirent.h:33
char d_name[256]
Filename.
Definition: dirent.h:35
int dirfd(DIR *dirp)
Retrieve the file descriptor of an opened directory stream.
Type representing a directory stream.
Definition: dirent.h:48
file_t fd
File descriptor for the directory.
Definition: dirent.h:49
uint8 d_type
File type.
Definition: dirent.h:34
unsigned short uint16
16-bit unsigned integer
Definition: types.h:29
off_t telldir(DIR *dir)
Not implemented.
int closedir(DIR *dir)
Closes a directory that was previously opened.
void seekdir(DIR *dir, off_t offset)
Not implemented.
unsigned char uint8
8-bit unsigned integer
Definition: types.h:30
int file_t
File descriptor type.
Definition: fs.h:86
int d_ino
File unique identifier.
Definition: dirent.h:31
off_t d_off
File offset.
Definition: dirent.h:32
int scandir(const char *dir, struct dirent ***namelist, int(*filter)(const struct dirent *), int(*compar)(const struct dirent **, const struct dirent **))
Not implemented.