home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / SH164X.ZIP / DIR.H < prev    next >
C/C++ Source or Header  |  1990-10-28  |  10KB  |  311 lines
  1. /*
  2.  * @(#) dir.h 1.4 87/11/06   Public Domain.
  3.  *
  4.  *  A public domain implementation of BSD directory routines for
  5.  *  MS-DOS.  Written by Michael Rendell ({uunet,utai}michael@garfield),
  6.  *  August 1987
  7.  *
  8.  *  Enhanced and ported to OS/2 by Kai Uwe Rommel; added scandir() prototype
  9.  *  December 1989, February 1990
  10.  *  Change of MAXPATHLEN for HPFS, October 1990
  11.  */
  12.  
  13.  
  14. #define MAXNAMLEN  256
  15. #define MAXPATHLEN 256
  16.  
  17. #define A_RONLY    0x01
  18. #define A_HIDDEN   0x02
  19. #define A_SYSTEM   0x04
  20. #define A_LABEL    0x08
  21. #define A_DIR      0x10
  22. #define A_ARCHIVE  0x20
  23.  
  24.  
  25. struct direct
  26. {
  27.   ino_t    d_ino;                   /* a bit of a farce */
  28.   int      d_reclen;                /* more farce */
  29.   int      d_namlen;                /* length of d_name */
  30.   char     d_name[MAXNAMLEN + 1];   /* null terminated */
  31.   /* nonstandard fields */
  32.   long     d_size;                  /* size in bytes */
  33.   unsigned d_mode;                  /* DOS or OS/2 file attributes */
  34.   unsigned d_time;
  35.   unsigned d_date;
  36. };
  37.  
  38. /* The fields d_size and d_mode are extensions by me (Kai Uwe Rommel).
  39.  * The find_first and find_next calls deliver this data without any extra cost.
  40.  * If this data is needed, these fields save a lot of extra calls to stat() 
  41.  * (each stat() again performs a find_first call !).
  42.  */
  43.  
  44. struct _dircontents
  45. {
  46.   char *_d_entry;
  47.   long _d_size;
  48.   unsigned _d_mode, _d_time, _d_date;
  49.   struct _dircontents *_d_next;
  50. };
  51.  
  52. typedef struct _dirdesc
  53. {
  54.   int  dd_id;                   /* uniquely identify each open directory */
  55.   long dd_loc;                  /* where we are in directory entry is this */
  56.   struct _dircontents *dd_contents;   /* pointer to contents of dir */
  57.   struct _dircontents *dd_cp;         /* pointer to current position */
  58. }
  59. DIR;
  60.  
  61.  
  62. extern int attributes;
  63.  
  64. extern DIR *opendir(char *);
  65. extern struct direct *readdir(DIR *);
  66. extern void seekdir(DIR *, long);
  67. extern long telldir(DIR *);
  68. extern void closedir(DIR *);
  69. #define rewinddir(dirp) seekdir(dirp, 0L)
  70.  
  71. extern int scandir(char *, struct direct ***,
  72.                    int (*)(struct direct *),
  73.                    int (*)(struct direct *, struct direct *));
  74.  
  75. extern int getfmode(char *);
  76. extern int setfmode(char *, unsigned);
  77.  
  78. /*
  79. NAME
  80.      opendir, readdir, telldir, seekdir, rewinddir, closedir -
  81.      directory operations
  82.  
  83. SYNTAX
  84.      #include <sys/types.h>
  85.      #include <sys/dir.h>
  86.  
  87.      DIR *opendir(filename)
  88.      char *filename;
  89.  
  90.      struct direct *readdir(dirp)
  91.      DIR *dirp;
  92.  
  93.      long telldir(dirp)
  94.      DIR *dirp;
  95.  
  96.      seekdir(dirp, loc)
  97.      DIR *dirp;
  98.      long loc;
  99.  
  100.      rewinddir(dirp)
  101.      DIR *dirp;
  102.  
  103.      int closedir(dirp)
  104.      DIR *dirp;
  105.  
  106. DESCRIPTION
  107.      The opendir library routine opens the directory named by
  108.      filename and associates a directory stream with it.  A
  109.      pointer is returned to identify the directory stream in sub-
  110.      sequent operations.  The pointer NULL is returned if the
  111.      specified filename can not be accessed, or if insufficient
  112.      memory is available to open the directory file.
  113.  
  114.      The readdir routine returns a pointer to the next directory
  115.      entry.  It returns NULL upon reaching the end of the direc-
  116.      tory or on detecting an invalid seekdir operation.  The
  117.      readdir routine uses the getdirentries system call to read
  118.      directories. Since the readdir routine returns NULL upon
  119.      reaching the end of the directory or on detecting an error,
  120.      an application which wishes to detect the difference must
  121.      set errno to 0 prior to calling readdir.
  122.  
  123.      The telldir routine returns the current location associated
  124.      with the named directory stream. Values returned by telldir
  125.      are good only for the lifetime of the DIR pointer from which
  126.      they are derived.  If the directory is closed and then reo-
  127.      pened, the telldir value may be invalidated due to
  128.      undetected directory compaction.
  129.  
  130.      The seekdir routine sets the position of the next readdir
  131.      operation on the directory stream. Only values returned by
  132.      telldir should be used with seekdir.
  133.  
  134.      The rewinddir routine resets the position of the named
  135.      directory stream to the beginning of the directory.
  136.  
  137.      The closedir routine closes the named directory stream and
  138.      returns a value of 0 if successful. Otherwise, a value of -1
  139.      is returned and errno is set to indicate the error.  All
  140.      resources associated with this directory stream are
  141.      released.
  142.  
  143. EXAMPLE
  144.      The following sample code searches a directory for the entry
  145.      name.
  146.  
  147.      len = strlen(name);
  148.  
  149.      dirp = opendir(".");
  150.  
  151.      for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))
  152.  
  153.      if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
  154.  
  155.                closedir(dirp);
  156.  
  157.                return FOUND;
  158.  
  159.           }
  160.  
  161.      closedir(dirp);
  162.  
  163.      return NOT_FOUND;
  164.  
  165.  
  166. SEE ALSO
  167.      close(2), getdirentries(2), lseek(2), open(2), read(2),
  168.      dir(5)
  169.  
  170. -----------------------
  171.  
  172. NAME
  173.      scandir - scan a directory
  174.  
  175. SYNTAX
  176.      #include <sys/types.h>
  177.      #include <sys/dir.h>
  178.  
  179.      scandir(dirname, namelist, select, compar)
  180.      char *dirname;
  181.      struct direct *(*namelist[]);
  182.      int (*select)();
  183.      int (*compar)();
  184.  
  185.      alphasort(d1, d2)
  186.      struct direct **d1, **d2;
  187.  
  188. DESCRIPTION
  189.      The scandir subroutine reads the directory dirname and
  190.      builds an array of pointers to directory entries using mal-
  191.      loc(3).  It returns the number of entries in the array and a
  192.      pointer to the array through namelist.
  193.  
  194.      The select parameter is a pointer to a user supplied subrou-
  195.      tine which is called by scandir to select which entries are
  196.      to be included in the array.  The select routine is passed a
  197.      pointer to a directory entry and should return a non-zero
  198.      value if the directory entry is to be included in the array.
  199.      If select is null, then all the directory entries will be
  200.      included.
  201.  
  202.      The compar parameter is a pointer to a user supplied subrou-
  203.      tine which is passed to qsort(3) to sort the completed
  204.      array.  If this pointer is null, the array is not sorted.
  205.      The alphasort is a routine which can be used for the compar
  206.      parameter to sort the array alphabetically.
  207.  
  208.      The memory allocated for the array can be deallocated with
  209.      free by freeing each pointer in the array and the array
  210.      itself.  For further information, see malloc(3).
  211.  
  212. DIAGNOSTICS
  213.      Returns -1 if the directory cannot be opened for reading or
  214.      if malloc(3) cannot allocate enough memory to hold all the
  215.      data structures.
  216.  
  217. SEE ALSO
  218.      directory(3), malloc(3), qsort(3), dir(5)
  219.  
  220. ----------------
  221.  
  222. NAME
  223.      dir - format of directories
  224.  
  225. SYNTAX
  226.      #include <sys/types.h>
  227.      #include <sys/dir.h>
  228.  
  229. DESCRIPTION
  230.      A directory behaves exactly like an ordinary file, except
  231.      that no user may write into a directory.  The fact that a
  232.      file is a directory is indicated by a bit in the flag word
  233.      of its i-node entry.  For further information, see fs(5).
  234.      The structure of a directory entry as given in the include
  235.      file is:
  236.  
  237.      A directory consists of some number of blocks of DIRBLKSIZ
  238.      bytes, where DIRBLKSIZ is chosen such that it can be
  239.      transferred to disk in a single atomic operation (for exam-
  240.      ple, 512 bytes on most machines).
  241.  
  242.      Each DIRBLKSIZ byte block contains some number of directory
  243.      entry structures, which are of variable length.  Each direc-
  244.      tory entry has a struct direct at the front of it, contain-
  245.      ing its inode number, the length of the entry, and the
  246.      length of the name contained in the entry.  These are fol-
  247.      lowed by the name padded to a 4 byte boundary with null
  248.      bytes.  All names are guaranteed null terminated.  The max-
  249.      imum length of a name in a directory is MAXNAMLEN.
  250.  
  251.      The macro DIRSIZ(dp) gives the amount of space required to
  252.      represent a directory entry.  Free space in a directory is
  253.      represented by entries which have dp->d_reclen > DIRSIZ(dp).
  254.      All DIRBLKSIZ bytes in a directory block are claimed by the
  255.      directory entries.  This usually results in the last entry
  256.      in a directory having a large dp->d_reclen.  When entries
  257.      are deleted from a directory, the space is returned to the
  258.      previous entry in the same directory block by increasing its
  259.      dp->d_reclen.  If the first entry of directory block is
  260.      free, then its dp->d_ino is set to 0.  Entries other than
  261.      the first in a directory do not normally have dp->d_ino set
  262.      to 0.
  263.  
  264.           #ifdef KERNEL
  265.           #define DIRBLKSIZ DEV_BSIZE
  266.           #else
  267.           #define   DIRBLKSIZ 512
  268.           #endif
  269.  
  270.           #define MAXNAMLEN 255
  271.  
  272.  
  273.      The DIRSIZ macro gives the minimum record length which will
  274.      hold the directory entry.  This requires the amount of space
  275.      in struct direct without the d_name field, plus enough space
  276.      for the name with a terminating null byte (dp->d_namlen+1),
  277.      rounded up to a 4 byte boundary.
  278.  
  279.  
  280.  
  281.           #undef DIRSIZ
  282.           #define DIRSIZ(dp) \
  283.               ((sizeof (struct direct) - (MAXNAMLEN+1)) + \
  284.               (((dp)->d_namlen+1 + 3) &~ 3))
  285.  
  286.           struct    direct {
  287.                u_long    d_ino;
  288.                short     d_reclen;
  289.                short     d_namlen;
  290.                char d_name[MAXNAMLEN + 1];
  291.                * typically shorter *
  292.           };
  293.  
  294.           struct _dirdesc {
  295.                int  dd_fd;
  296.                long dd_loc;
  297.                long dd_size;
  298.                char dd_buf[DIRBLKSIZ];
  299.           };
  300.  
  301.  
  302.      By convention, the first two entries in each directory are
  303.      for `.' and `..'.  The first is an entry for the directory
  304.      itself.  The second is for the parent directory.  The mean-
  305.      ing of `..' is modified for the root directory of the master
  306.      file system ("/"), where `..' has the same meaning as `.'.
  307.  
  308. SEE ALSO
  309.      fs(5)
  310. */
  311.