📄 readdir.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><!-- Copyright 1997 The Open Group, All Rights Reserved --><title>readdir</title></head><body bgcolor=white><center><font size=2>The Single UNIX ® Specification, Version 2<br>Copyright © 1997 The Open Group</font></center><hr size=2 noshade><h4><a name = "tag_000_007_1906"> </a>NAME</h4><blockquote>readdir, readdir_r - read directory</blockquote><h4><a name = "tag_000_007_1907"> </a>SYNOPSIS</h4><blockquote><pre><code>#include <<a href="systypes.h.html">sys/types.h</a>>#include <<a href="dirent.h.html">dirent.h</a>>struct dirent *readdir(DIR *<i>dirp</i>);int readdir_r(DIR *<i>dirp</i>, struct dirent *<i>entry</i>, struct dirent **<i>result</i>);</code></pre></blockquote><h4><a name = "tag_000_007_1908"> </a>DESCRIPTION</h4><blockquote>The type<b>DIR</b>,which is defined in the header<i><a href="dirent.h.html"><dirent.h></a></i>,represents a<i>directory stream</i>,which is an ordered sequence of all the directory entries in aparticular directory.Directory entries represent files; files may be removed from adirectory or added to a directory asynchronously to the operation of<i>readdir()</i>.<p>The<i>readdir()</i>function returns a pointer to a structure representing the directory entry atthe current position in the directory stream specified by the argument<i>dirp</i>,and positions the directory stream at the next entry.It returns a null pointer upon reaching the end of the directory stream.The structure<i>dirent</i>defined by the<i><a href="dirent.h.html"><dirent.h></a></i>header describes a directory entry.<p>If entries for dot or dot-dot exist, one entry will be returnedfor dot and one entry will be returned for dot-dot; otherwisethey will not be returned.<p>The pointer returned by<i>readdir()</i>points to data which may be overwritten by another call to<i>readdir()</i>on the same directory stream.This data is not overwritten by another call to<i>readdir()</i>on a different directory stream.<p>If a file is removed from or added to the directory after the mostrecent call to<i><a href="opendir.html">opendir()</a></i>or<i><a href="rewinddir.html">rewinddir()</a></i>,whether a subsequent call to<i>readdir()</i>returns an entry for that file is unspecified.<p>The<i>readdir()</i>function may buffer several directory entries per actual readoperation;<i>readdir()</i>marks for update the<i>st_atime</i>field of the directory each time the directory is actually read.<p>After a call to<i><a href="fork.html">fork()</a></i>,either the parent or child (but not both) may continue processingthe directory stream using<i>readdir()</i>,<i><a href="rewinddir.html">rewinddir()</a></i>or<i><a href="seekdir.html">seekdir()</a></i>. If both the parent and child processes use these functions, the result isundefined.<p>If the entry names a symbolic link, the value of the<b>d_ino</b>member is unspecified.<p>The<i>readdir()</i>interface need not be reentrant.<p>The<i>readdir_r()</i>function initialises the<b>dirent</b>structure referenced by<i>entry</i>to represent the directory entry at the current positionin the directory stream referred to by<i>dirp</i>,store a pointer to this structure at the location referenced by<i>result</i>,and positions the directory stream at the next entry.<p>The storage pointed to by<i>entry</i>will be large enough for a<b>dirent</b>with an array of<b>char</b><i>d_name</i>member containing at least {NAME_MAX} plus one elements.<p>On successful return, the pointer returned at *<i>result</i>will have the same value as the argument<i>entry</i>.Upon reaching the end of the directory stream,this pointer will have the value NULL.<p>The<i>readdir_r()</i>function will not return directory entries containing empty names.It is unspecified whether entries are returned for dot or dot-dot.<p>If a file is removed from or added to the directoryafter the most recent call to<i><a href="opendir.html">opendir()</a></i>or<i><a href="rewinddir.html">rewinddir()</a></i>,whether a subsequent call to<i>readdir_r()</i>returns an entry for that file is unspecified.<p>The<i>readdir_r()</i>function may buffer several directory entries per actual read operation;the<i>readdir_r()</i>function marks for update the<i>st_atime</i>field of the directory each time the directory is actually read.<p>Applications wishing to check for error situations should set<i>errno</i>to 0 before calling<i>readdir()</i>.If<i>errno</i>is set to non-zero on return, an error occurred.</blockquote><h4><a name = "tag_000_007_1909"> </a>RETURN VALUE</h4><blockquote>Upon successful completion,<i>readdir()</i>returns a pointer to an object of type<b>struct dirent</b>.When an error is encountered, a null pointer is returned and<i>errno</i>is set to indicate the error. When the end of the directory is encountered, anull pointer is returned and<i>errno</i>is not changed.<p>If successful, the<i>readdir_r()</i>function returns zero.Otherwise, an error number is returned to indicate the error.</blockquote><h4><a name = "tag_000_007_1910"> </a>ERRORS</h4><blockquote>The<i>readdir()</i>function will fail if:<dl compact><dt>[EOVERFLOW]<dd>One of the values in the structure to be returned cannot berepresented correctly.</dl><p>The<i>readdir()</i>function may fail if:<dl compact><dt>[EBADF]<dd>The<i>dirp</i>argument does not refer to an open directory stream.<dt>[ENOENT]<dd>The current position of the directory stream is invalid.</dl><p>The <i>readdir_r()</i>function may fail if:<dl compact><dt>[EBADF]<dd>The<i>dirp</i>argument does not refer to an open directory stream.</dl></blockquote><h4><a name = "tag_000_007_1911"> </a>EXAMPLES</h4><blockquote>The following sample code will search the current directory for theentry<i>name</i>:<pre><code>dirp = opendir(".");while (dirp) { errno = 0; if ((dp = readdir(dirp)) != NULL) { if (strcmp(dp->d_name, name) == 0) { closedir(dirp); return FOUND; } } else { if (errno == 0) { closedir(dirp); return NOT_FOUND; } closedir(dirp); return READ_ERROR; }}return OPEN_ERROR;</code></pre></blockquote><h4><a name = "tag_000_007_1912"> </a>APPLICATION USAGE</h4><blockquote>The<i>readdir()</i>function should be used in conjunction with<i><a href="opendir.html">opendir()</a></i>,<i><a href="closedir.html">closedir()</a></i>and<i><a href="rewinddir.html">rewinddir()</a></i>to examine the contents of the directory.</blockquote><h4><a name = "tag_000_007_1913"> </a>FUTURE DIRECTIONS</h4><blockquote>None.</blockquote><h4><a name = "tag_000_007_1914"> </a>SEE ALSO</h4><blockquote><i><a href="closedir.html">closedir()</a></i>,<i><a href="lstat.html">lstat()</a></i>,<i><a href="opendir.html">opendir()</a></i>,<i><a href="rewinddir.html">rewinddir()</a></i>,<i><a href="symlink.html">symlink()</a></i>,<i><a href="dirent.h.html"><dirent.h></a></i>,<i><a href="systypes.h.html"><sys/types.h></a></i>.</blockquote><h4>DERIVATION</h4><blockquote><i>readdir_r()</i> derived from the POSIX Threads Extension (1003.1c-1995).</blockquote><hr size=2 noshade><center><font size=2>UNIX ® is a registered Trademark of The Open Group.<br>Copyright © 1997 The Open Group<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]</font></center><hr size=2 noshade></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -