![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to NOTES 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 NOTES CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / dirent |
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.