Directory Traversal

DIRT is very small library which wraps up several platforms directory traversal routines in a single platform independant package.

Its basically a thin wrapper round opendir, _dos_findfirst, DOSFindFirstFile and similar families of API.

The API

You include dirt.h, which typically looks like this :-

  /*

  dirt.h - Interface to Directory Traversal - UNIX version

  */

  #ifndef DIRT_H
  #define DIRT_H

  #define DIRTE_OK            0
  #define DIRTE_GEN_ERROR     1
  #define DIRTE_NO_MEMORY     2
  #define DIRTE_NOT_FOUND     3
  #define DIRTE_NOT_DIRECTORY 4
  #define DIRTE_NO_ACCESS     5
  #define DIRTE_NO_RESOURCE   6

  #ifndef DIRT_C

  typedef void DIRT;

  extern DIRT *dirt_open(const char *dirname, int *rc);
  extern const char *dirt_next(DIRT *dirt);
  extern void dirt_close(DIRT *dirt);

  extern const char *dirt_error(int rc);

  #endif

  #endif

The DIRTE_ codes are error codes, as returned by dirt_open. These can be mapped to a human readable string by feeding them into dirt_error.

Although the first few error codes are always present, not all are present on all platforms, so a bit of #ifdef-ing may be required. For example, on DOS, there is no such thing as file permissions, so you can't get DIRTE_NO_ACCESS.

Sample code

Here is some sample code using DIRT :-

  #include <stdio.h>
  #include "dirt.h"

  void ls(const char *dirname)
    {
    DIRT *dirt;
    int rc;
    const char *entry;
    if ( (dirt = dirt_open(dirname, &rc)) == NULL )
      {
      fprintf(stderr, "can't open %s: %s\n", dirname, dirt_error(rc));
      exit(1);
      }
    while ( (entry = dirt_next(dirt)) != NULL )
      printf("found %s\n", entry);
    dirt_close(dirt);
    }

You'd probably want to do more with each entry you found.

The FINDERE and FL packages (available from where you got DIRT) are example testcases for DIRT.

The package

This document, and the DIRT package are available from my home page at http://www.nyangau.org/.

The package contains this document and full source to the the DIRT module.

The source code is highly portable C code, and I include makefiles suitable for 16 bit DOS, 32 bit DOS, 16 bit OS/2, 32 bit OS/2, Win32 and UNIX.

When you get the package, you copy the appropriate operating system subdirectory to the main directory before building or using it. You might also clean out any old .o or .obj files that may have accidentally made it into the distributed .zip.

Copying

This DIRT module, including its source code, are public domain. Caveat Emptor.