Return to directory.3c CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / dirent

Annotation of 43BSDReno/contrib/isode-beta/dirent/directory.3c, revision 1.1

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.