![[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 [MW Coherent from dump] / coherent / d / usr / lib / ndir / libndir|
Return to directory.3c CVS log | Up to [MW Coherent from dump] / coherent / d / usr / lib / ndir / libndir |
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 <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: .P
134: .ft B
135: dirp = opendir( "." );
136: .br
137: while ( (dp = readdir( dirp )) != NULL )
138: .br
139: if ( strcmp( dp\->d_name, name ) == 0 )
140: .br
141: {
142: .br
143: (void) closedir( dirp );
144: .br
145: return FOUND;
146: .br
147: }
148: .br
149: (void) closedir( dirp );
150: .br
151: return NOT_FOUND;
152: .ft P
153: .SH "SEE ALSO"
154: getdents(2), dirent(4).
155: .SH WARNINGS
156: Entries for "." and ".."
157: may not be reported for some file system types.
158: .P
159: The value returned by
160: .I telldir
161: need not have any simple interpretation
162: and should only be used as an argument to
163: .IR seekdir .
164: Similarly,
165: the
166: .I loc
167: argument to
168: .I seekdir
169: must be obtained from a previous
170: .I telldir
171: operation on the same
172: directory stream.
173: .P
174: .I Telldir
175: and
176: .I seekdir
177: are unreliable when used in conjunction with
178: file systems that perform directory compaction or expansion
179: or when the directory stream has been closed and reopened.
180: It is best to avoid using
181: .I telldir
182: and
183: .I seekdir
184: altogether.
185: .P
186: The exact set of
187: .I errno
188: values and meanings may vary among implementations.
189: .P
190: Because directory entries can dynamically
191: appear and disappear,
192: and because directory contents are buffered
193: by these routines,
194: an application may need to continually rescan
195: a directory to maintain an accurate picture
196: of its active entries.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.