man/man3/directory.3

   1 .TH DIRECTORY 3
   2 .SH NAME
   3 directory, opendir, readdir, rewinddir, closedir, telldir, seekdir \- directory routines
   4 .SH SYNOPSIS
   5 .nf
   6 .ft B
   7 #include <sys/types.h>
   8 #include <dirent.h>
   9
  10 DIR *opendir(const char *\fIdirname\fP)
  11 struct dirent *readdir(DIR *\fIdirp\fP)
  12 void rewinddir(DIR *\fIdirp\fP)
  13 int closedir(DIR *\fIdirp\fP)
  14
  15 #define _MINIX  1
  16 #include <sys/types.h>
  17 #include <dirent.h>
  18
  19 long telldir(DIR *\fIdirp\fP)
  20 int seekdir(DIR *\fIdirp\fP, long \fIpos\fP)
  21 .SH DESCRIPTION
  22 These routines form a system independent interface to access directories.
  23 .PP
  24 .B Opendir()
  25 opens the directory
  26 .I dirname
  27 and returns a pointer to this open directory stream.
  28 .PP
  29 .B Readdir()
  30 reads one entry from the directory as a pointer to a structure containing
  31 the field
  32 .BR d_name ,
  33 a character array containing the null-terminated name of the entry.
  34 .PP
  35 .B Rewinddir()
  36 allows the directory to be read again from the beginning.
  37 .PP
  38 .B Closedir()
  39 closes the directory and releases administrative data.
  40 .PP
  41 The MINIX 3 specific functions
  42 .B telldir()
  43 and
  44 .B seekdir()
  45 allow one to get the current position in the directory file and to return
  46 there later.
  47 .B Seekdir()
  48 may only be called with a position returned by
  49 .B telldir()
  50 or 0 (rewind).  These functions should not be used in portable programs.
  51 .SH "SEE ALSO"
  52 .BR dir (5).
  53 .SH DIAGNOSTICS
  54 .B Opendir()
  55 returns a null pointer if
  56 .I dirname
  57 can't be opened, or if it can't allocate enough memory for the
  58 .B DIR
  59 structure.
  60 .PP
  61 .B Readdir()
  62 returns null if there are no more directory entries or on error.
  63 .PP
  64 .B Closedir()
  65 and
  66 .B seekdir()
  67 returns 0 on success, -1 on error.
  68 .PP
  69 .B Telldir()
  70 returns -1 on error.
  71 .PP
  72 All of them set
  73 .B errno
  74 appropriately.
  75 .B Readdir()
  76 will only set
  77 .B errno
  78 on error, not on end-of-dir, so you should set
  79 .B errno
  80 to zero beforehand, and check its value if
  81 .B readdir()
  82 returns null.
  83 .SH NOTES
  84 The return value of
  85 .B readdir()
  86 needs to be copied before the next operation on the same directory if it is
  87 to be saved.
  88 .SH AUTHOR
  89 Kees J. Bot (kjb@cs.vu.nl)