git.marmaro.de Git - mmh/blob - 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.