Return to NOTES CVS log

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

Annotation of 43BSDReno/contrib/isode-beta/dirent/NOTES, revision 1.1

1.1     ! root        1: 
        !             2: 
        !             3: NOTES FOR NEARLY-POSIX-COMPATIBLE C LIBRARY DIRECTORY-ACCESS ROUTINES
        !             4: 
        !             5: 
        !             6: Older UNIX C libraries lacked support for reading directories, so historically
        !             7: programs had knowledge of UNIX directory structure hard-coded into them.  When
        !             8: Berkeley changed the format of directories for 4.2BSD, it became necessary to
        !             9: change programs to work with the new structure.  Fortunately, Berkeley designed
        !            10: a small set of directory access routines to encapsulate knowledge of the new
        !            11: directory format so that user programs could deal with directory entries as an
        !            12: abstract data type.  (Unfortunately, they didn't get it quite right.)  The
        !            13: interface to these routines was nearly independent of the particular
        !            14: implementation of directories on any given UNIX system; this has become a
        !            15: particularly important requirement with the advent of heterogeneous network
        !            16: filesystems such as NFS.
        !            17: 
        !            18: It has consequently become possible to write portable applications that search
        !            19: directories by restricting all directory access to use these new interface
        !            20: routines.  The sources supplied here are a total rewrite of Berkeley's code,
        !            21: incorporating ideas from a variety of sources and conforming as closely to
        !            22: published standards as possible, and are in the PUBLIC DOMAIN to encourage
        !            23: their widespread adoption.  They support four methods of access to system
        !            24: directories: the original UNIX filesystem via read(), the 4.2BSD filesystem via
        !            25: read(), NFS and native filesystems via getdirentries(), and SVR3 getdents().
        !            26: The other three types are accomplished by appropriate emulation of the SVR3
        !            27: getdents() system call, which attains portability at the cost of slightly more
        !            28: data movement than absolutely necessary for some systems.  These routines
        !            29: should be added to the standard C library on all UNIX systems, and all existing
        !            30: and future applications should be changed to use this interface.  Once this is
        !            31: done, there should be no portability problems due to differences in underlying
        !            32: directory structures among UNIX systems.  (When porting your applications to
        !            33: other UNIX systems, you can always carry this package around with you.)
        !            34: 
        !            35: An additional benefit of these routines is that they buffer directory input,
        !            36: which provides improved access speed over raw read()s of one entry at a time.
        !            37: 
        !            38: One annoying compatibility problem has arisen along the way, namely that the
        !            39: original Berkeley interface used the same name, struct direct, for the new data
        !            40: structure as had been used for the original UNIX filesystem directory record
        !            41: structure.  This name was changed by the IEEE 1003.1 (POSIX) Working Group to
        !            42: "struct dirent" and was picked up for SVR3 under the new name; it is also the
        !            43: name used in this portable package.  I believe it is necessary to bite the
        !            44: bullet and adopt the new non-conflicting name.  Code using a 4.2BSD-compatible
        !            45: package needs to be slightly revised to work with this new package, as follows:
        !            46:        Change
        !            47:                #include <ndir.h>       /* Ninth Edition UNIX */
        !            48:        or
        !            49:                #include <sys/dir.h>    /* 4.2BSD */
        !            50:        or
        !            51:                #include <dir.h>        /* BRL System V emulation */
        !            52:        to
        !            53:                #include <sys/types.h>  /* if not already #included */
        !            54:                #include <dirent.h>
        !            55: 
        !            56:        Change
        !            57:                struct direct
        !            58:        to
        !            59:                struct dirent
        !            60: 
        !            61:        Change
        !            62:                (anything)->d_namlen
        !            63:        to
        !            64:                strlen( (anything)->d_name )
        !            65: 
        !            66: There is a minor compatibility problem in that the closedir() function was
        !            67: originally defined to have type void, but IEEE 1003.1 changed this to type int,
        !            68: which is what this implementation supports (even though I disagree with the
        !            69: change).  However, the difference does not affect most applications.
        !            70: 
        !            71: Another minor problem is that IEEE 1003.1 defined the d_name member of a struct
        !            72: dirent to be an array of maximum length; this does not permit use of compact
        !            73: variable-length entries directly from a directory block buffer.  This part of
        !            74: the specification is incompatible with efficient use of the getdents() system
        !            75: call, and I have therefore chosen to follow the SVID specification instead of
        !            76: IEEE 1003.1 (which I hope is changed for the final-use standard).  This
        !            77: deviation should have little or no impact on sensibly-coded applications, since
        !            78: the relevant d_name length is that given by strlen(), not the declared array
        !            79: size.
        !            80: 
        !            81: Error handling is not completely satisfactory, due to the variety of possible
        !            82: failure modes in a general setting.  For example, the rewinddir() function
        !            83: might fail, but there is no good way to indicate this.  I have tried to
        !            84: follow the specifications in IEEE 1003.1 and the SVID as closely as possible,
        !            85: but there are minor deviations in this regard.  Applications should not rely
        !            86: too heavily on exact failure mode semantics.
        !            87: 
        !            88: Please do not change the new standard interface in any way, as that would
        !            89: defeat the major purpose of this package!  (It's okay to alter the internal
        !            90: implementation if you really have to, although I tried to make this unnecessary
        !            91: for the vast majority of UNIX variants.)
        !            92: 
        !            93: Installation instructions can be found in the file named INSTALL.
        !            94: 
        !            95: This implementation is provided by:
        !            96: 
        !            97:        Douglas A. Gwyn
        !            98:        U.S. Army Ballistic Research Laboratory
        !            99:        SLCBR-VL-V
        !           100:        Aberdeen Proving Ground, MD 21005-5066
        !           101: 
        !           102:        (301)278-6647
        !           103: 
        !           104:        [email protected] or seismo!brl!gwyn
        !           105: 
        !           106: This is UNSUPPORTED, use-at-your-own-risk, free software in the public domain.
        !           107: However, I would appreciate hearing of any actual bugs you find in this
        !           108: implementation and/or any improvements you come up with.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.