If heirloom shell is in /usr/lib/heirloom/5bin/sh, use it to run tests.
[mmh] / docs / historical / mh-6.8.5 / miscellany / libndir / directory.3s
1 ..TH DIRECTORY 3  "OGC Revision  8/02/82"
2 .TH DIRECTORY 3X 8/1/82
3 .UC 4.1b Compatability
4 .SH NAME
5 opendir, readdir, telldir, seekdir, rewinddir, closedir \- flexible length directory operations
6 .SH SYNOPSIS
7 .B #include <dir.h>
8 .PP
9 .SM
10 .B DIR
11 .B *opendir(filename)
12 .br
13 .B char *filename;
14 .PP
15 .SM
16 .B struct direct
17 .B *readdir(dirp)
18 .br
19 .B DIR *dirp;
20 .PP
21 .SM
22 .B long
23 .B telldir(dirp)
24 .br
25 .B DIR *dirp;
26 .PP
27 .SM
28 .B seekdir(dirp, loc)
29 .br
30 .B DIR *dirp;
31 .br
32 .B long loc;
33 .PP
34 .SM
35 .B rewinddir(dirp)
36 .br
37 .B DIR *dirp;
38 .PP
39 .SM
40 .B closedir(dirp)
41 .br
42 .B DIR *dirp;
43 .PP
44 .SM
45 .B cc ... -lndir
46 .SH DESCRIPTION
47 The purpose of this library is to simulate
48 the new flexible length directory names of 4.2bsd Unix
49 on top of the old directory structure of 4.1bsd.
50 It allows programs to be converted immediately
51 to the new directory access interface,
52 so that they need only be relinked
53 when 4.2bsd becomes available.
54 .PP
55 .I opendir
56 opens the directory named by
57 .I filename
58 and associates a
59 .I directory stream
60 with it.
61 .I opendir
62 returns a pointer to be used to identify the
63 .I directory stream
64 in subsequent operations.
65 The pointer
66 .SM
67 .B NULL
68 is returned if
69 .I filename
70 cannot be accessed or is not a directory.
71 .PP
72 .I readdir
73 returns a pointer to the next directory entry.
74 It returns
75 .B NULL
76 upon reaching the end of the directory or detecting
77 an invalid
78 .I seekdir
79 operation.
80 .PP
81 .I telldir
82 returns the current location associated with the named
83 .I directory stream.
84 .PP
85 .I seekdir
86 sets the position of the next
87 .I readdir
88 operation on the
89 .I directory stream.
90 The new position reverts to the one associated with the
91 .I directory stream
92 when the
93 .I telldir
94 operation was performed.
95 Values returned by
96 .I telldir
97 are good only for the lifetime of the DIR pointer from 
98 which they are derived.
99 If the directory is closed and then reopened, 
100 the 
101 .I telldir
102 value may be invalidated
103 due to undetected directory compaction.
104 It is safe to use a previous
105 .I telldir
106 value immediately after a call to
107 .I opendir
108 and before any calls to
109 .I readdir.
110 .PP
111 .I rewinddir
112 resets the position of the named
113 .I directory stream
114 to the beginning of the directory.
115 .PP
116 .I closedir
117 causes the named
118 .I directory stream
119 to be closed,
120 and the structure associated with the DIR pointer to be freed.
121 .PP
122 See /usr/include/dir.h for a description of the fields available in
123 a directory entry.
124 The preferred way to search the current directory for entry "name" is:
125 .br
126 .sp
127         len = strlen(name);
128 .br
129         dirp = opendir(".");
130 .br
131         for (dp = readdir(dirp); dp != NULL; dp = readdir(dir))
132 .br
133                 if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
134 .br
135                         closedir(dirp);
136 .br
137                         return FOUND;
138 .br
139                 }
140 .br
141         closedir(dirp);
142 .br
143         return NOT_FOUND;
144 .SH LINKING
145 This library is accessed by specifying "-lndir" as the
146 last argument to the compile line, e.g.:
147 .br
148 .sp
149         cc -o prog prog.c -lndir
150 .SH "SEE ALSO"
151 /usr/include/dir.h,
152 open(2),
153 close(2),
154 read(2),
155 lseek(2)
156 .SH AUTHOR
157 Kirk McKusick.
158 Report problems to mckusick@berkeley or ucbvax!mckusick.