![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to directory.3c CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / dirent|
Return to directory.3c CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / dirent |
1.1 root 1: .TH DIRECTORY 3C "Standard Extension"
2: .SH NAME
3: opendir, readdir, telldir, seekdir, rewinddir, closedir \- directory operations
4: .SH SYNOPSIS
5: .B "#include <sys/types.h>"
6: .br
7: .B "#include <isode/usr.dirent.h>"
8: .P
9: .B "DIR \(**opendir (dirname)"
10: .br
11: .B "char \(**dirname;"
12: .P
13: .B "struct dirent \(**readdir (dirp)"
14: .br
15: .B "DIR \(**dirp;"
16: .P
17: .B "off_t telldir (dirp)"
18: .br
19: .B "DIR \(**dirp;"
20: .P
21: .B "void seekdir (dirp, loc)"
22: .br
23: .B "DIR \(**dirp;"
24: .br
25: .B "off_t loc;"
26: .P
27: .B "void rewinddir (dirp)"
28: .br
29: .B "DIR \(**dirp;"
30: .P
31: .B "int closedir (dirp)"
32: .br
33: .B "DIR \(**dirp;"
34: .SH DESCRIPTION
35: .I Opendir
36: establishes a connection between
37: the directory named by
38: .I dirname
39: and a unique object of type
40: .SM DIR
41: known as a
42: .I "directory stream"
43: that it creates.
44: .I Opendir
45: returns a pointer to be used to identify the
46: directory stream
47: in subsequent operations.
48: A
49: .SM NULL
50: pointer is returned if
51: .I dirname
52: cannot be accessed or is not a directory,
53: or if
54: .I opendir
55: is unable to create the
56: .SM DIR
57: object
58: (perhaps due to insufficient memory).
59: .P
60: .I Readdir
61: returns a pointer to an internal structure
62: containing information about the next active directory entry.
63: No inactive entries are reported.
64: The internal structure may be overwritten by
65: another operation on the same
66: directory stream;
67: the amount of storage needed to hold a copy
68: of the internal structure is given by the value of a macro,
69: .IR DIRENTSIZ(strlen(direntp\->d_name)) ,
70: not by
71: .I "sizeof(struct\ dirent)"
72: as one might expect.
73: A
74: .SM NULL
75: pointer is returned
76: upon reaching the end of the directory,
77: upon detecting an invalid location in the directory,
78: or upon occurrence of an error while reading the directory.
79: .P
80: .I Telldir
81: returns the current position associated with the named
82: directory stream
83: for later use as an argument to
84: .IR seekdir .
85: .P
86: .I Seekdir
87: sets the position of the next
88: .I readdir
89: operation on the named
90: directory stream.
91: The new position reverts to the one associated with the
92: directory stream
93: when the
94: .I telldir
95: operation from which
96: .I loc
97: was obtained was performed.
98: .P
99: .I Rewinddir
100: resets the position of the named
101: directory stream
102: to the beginning of the directory.
103: All buffered data for the directory stream is discarded,
104: thereby guaranteeing that the actual
105: file system directory will be referred to for the next
106: .I readdir
107: on the
108: directory stream.
109: .P
110: .I Closedir
111: closes the named
112: directory stream;
113: internal resources used for the
114: directory stream are liberated,
115: and subsequent use of the associated
116: .SM DIR
117: object is no longer valid.
118: .I Closedir
119: returns a value of zero if no error occurs,
120: \-1 otherwise.
121: .P
122: There are several possible errors that can occur
123: as a result of these operations;
124: the external integer variable
125: .I errno
126: is set to indicate the specific error.
127: .RI ( Readdir 's
128: detection of the normal end of a directory
129: is not considered to be an error.)
130: .SH EXAMPLE
131: Sample code which searches the current working directory for entry
132: .IR name :
133: .sp
134: .P
135: .ft B
136: dirp = opendir( "." );
137: .br
138: while ( (dp = readdir( dirp )) != NULL )
139: .br
140: if ( strcmp( dp\->d_name, name ) == 0 )
141: .br
142: {
143: .br
144: (void) closedir( dirp );
145: .br
146: return FOUND;
147: .br
148: }
149: .br
150: (void) closedir( dirp );
151: .br
152: return NOT_FOUND;
153: .ft P
154: .sp
155: .SH "SEE ALSO"
156: getdents(2), dirent(4).
157: .SH WARNINGS
158: Entries for "." and ".."
159: may not be reported for some file system types.
160: .P
161: The value returned by
162: .I telldir
163: need not have any simple interpretation
164: and should only be used as an argument to
165: .IR seekdir .
166: Similarly,
167: the
168: .I loc
169: argument to
170: .I seekdir
171: must be obtained from a previous
172: .I telldir
173: operation on the same
174: directory stream.
175: .P
176: .I Telldir
177: and
178: .I seekdir
179: are unreliable when used in conjunction with
180: file systems that perform directory compaction or expansion
181: or when the directory stream has been closed and reopened.
182: It is best to avoid using
183: .I telldir
184: and
185: .I seekdir
186: altogether.
187: .P
188: The exact set of
189: .I errno
190: values and meanings may vary among implementations.
191: .P
192: Because directory entries can dynamically
193: appear and disappear,
194: and because directory contents are buffered
195: by these routines,
196: an application may need to continually rescan
197: a directory to maintain an accurate picture
198: of its active entries.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.