home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 1 / 1689 / README < prev    next >
Encoding:
Text File  |  1990-12-28  |  3.2 KB  |  102 lines
  1.  
  2. This code implements the Berkeley Unix "readdir" package.  Readdir is an
  3. abstract interface for reading entries out of directories, and getting the
  4. names of the files (and directories, etc.) contained therein.  Versions
  5. exist for all Unix systems, MS-DOS, Amiga, and no doubt others as well.
  6.  
  7. This code was written by Rich $alz, <rsalz@bbn.com> in August, 1990, and
  8. has no copyright.
  9.  
  10.     #include <dirent.h>
  11. This header file must be included by any files that use any of the routines
  12. described here.  You must also #include <descrip.h> first.
  13.  
  14.     DIR *
  15.     opendir(name)
  16.     char    *name;
  17. NAME is a filespec that names a directory.  It does not have to be in
  18. strict canonical form -- logicals such as "sys$login:" will be expanded.
  19. Once the directory has been opened, any of the other routines described
  20. here can be used on the handle that is returned.
  21.  
  22.  
  23.     void
  24.     vmsreaddirversions(dd, flag)
  25.     DIR        *dd;
  26.     int        flag;
  27. By default, READDIR() ignores file versions, and returns a file name once,
  28. no matter how many versions it has.  This routine can be used to collect
  29. the version numbers in an that is returned with each file.  The FLAG
  30. argument should be non-zero to collect version information, or zero to
  31. ignore it.  This routine can be called any number of times while the
  32. directory is open.
  33.  
  34.  
  35.     void
  36.     closedir(dd)
  37.     DIR        *dd;
  38. Once you are finished reading the contents of a directory, the CLOSEDIR()
  39. routine frees up all the storage associated with it, and invalidates the
  40. handle.
  41.  
  42.  
  43.     struct dirent *
  44.     readdir(dd)
  45.     DIR        *dd;
  46. The READDIR() routine takes a handle returned by OPENDIR() and returns the
  47. name of the next file in the directory, or a NULL pointer when there are
  48. no more files.  The STRUCT DIRENT returned by this routine will have the
  49. following fields that may be accessed by user code:
  50.     d_name[]        A C character string with the file name
  51.     vms_verscount    The number of versions the file has
  52.     vms_versions[]    An array of the version numbers; the number -1
  53.             indicates a file-parsing error.
  54. Note that the fields starting with "vms_" are not part of the standard
  55. READDIR() library available on other systems, so strictly portable code
  56. should take care to avoid using them except on VMS machines.
  57.  
  58.     long
  59.     telldir(dd)
  60.     DIR        *dd;
  61. This routine returns a "magic cookie" that can be used in a later
  62. SEEKDIR() call.  This allows you to remember one or more spots while
  63. reading through a directory and return to them later.
  64.  
  65.  
  66.     void
  67.     seekdir(dd, pos)
  68.     DIR        *dd;
  69.     long        pos;
  70. The SEEKDIR() routine takes the "cookie" returned by a previous call to
  71. TELLDIR() and sets the internal state so that the next READDIR() call will
  72. return the file read just after the TELLDIR() call.
  73.  
  74.     void
  75.     rewinddir(dd)
  76.     DIR        *dd;
  77. The REWINDDIR() routine resets the internal state of the DD handle so that
  78. READDIR() starts reading over from the beginning of the directory.
  79.  
  80. Here is a sample routine showing how to use the package:
  81.     main()
  82.     {
  83.     DIR        *dd;
  84.     struct dirent    *dp;
  85.     int        i;
  86.  
  87.     if ((dd = opendir("sys$login")) == NULL) {
  88.         perror(buff);
  89.         continue;
  90.     }
  91.     vmsreaddirversions(dd, 1);
  92.  
  93.     while (dp = readdir(dd)) {
  94.         printf("%s", dp->d_name);
  95.         for (i = 0; i < dp->vms_verscount; i++)
  96.         printf("  %d", dp->vms_versions[i]);
  97.         printf("\n");
  98.     }
  99.     closedir(dd);
  100.     exit(0);
  101.     }
  102.