dirent.h File Reference

d_ino

Typedef DIR

typedef void *DIR

defines DIR data type through typedef. A type representing a directory stream.

opendir ( const char * )

IMPORT_C DIR *opendir(const char *)

The opendir function opens the directory named by _path , associates a directory stream with it and returns a pointer to be used to identify the directory stream in subsequent operations. The pointer NULL is returned if filename cannot be accessed, or if it cannot malloc enough memory to hold the whole thing.

The readdir function returns a pointer to the next directory entry. It returns NULL upon reaching the end of the directory or detecting an invalid seekdir operation.

The readdir_r function provides the same functionality as readdir , but the caller must provide a directory entry buffer to store the results in. If the read succeeds, result is pointed at the entry ; upon reaching the end of the directory result is set to NULL . The readdir_r function returns 0 on success or an error number to indicate failure.

The telldir function returns the current location associated with the named directory stream . Values returned by telldir are good only for the lifetime of the DIR pointer, dirp , from which they are derived. If the directory is closed and then reopened, prior values returned by telldir will no longer be valid.

The seekdir function sets the position of the next readdir operation on the directory stream . The new position reverts to the one associated with the directory stream when the telldir operation was performed.

The rewinddir function resets the position of the named directory stream to the beginning of the directory.

The closedir function closes the named directory stream and frees the structure associated with the dirp pointer, returning 0 on success. On failure, -1 is returned and the global variable errno is set to indicate the error.

The dirfd function returns the integer file descriptor associated with the named directory stream , see open .

 Sample code which searches a directory for entry name is: len = strlen(name);
dirp = opendir(".");
while ((dp = readdir(dirp)) != NULL)
        if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
                (void)closedir(dirp);
                return FOUND;
        }
(void)closedir(dirp);
return NOT_FOUND;
Examples:
/* Detailed description: This test code demonstrates usage of opendir system call, open directory name test.
 Preconditions: Expects Test directory to be present in the current working directory.
*/
 #include <sys/types.h>
 #include <dirent.h>
int main()
{
  DIR *DirHandle;
  if(!(DirHandle = opendir("Test") ) ) 
  {
     printf("Failed to open directory Test\n");
     return -1;
  }
  printf("Directory Test opened \n");
  return 0;
}
Output 
Directory Test opened

Limitations:

The filename parameter of the opendir() function should not exceed 256 characters in length.

See also: close() lseek() open() read()

Parameters
Note: This description also covers the following functions - readdir() readdir_r() telldir() seekdir() rewinddir() closedir() dirfd()
Return Value
closedir function returns 0 on success or -1 on failure.

readdir ( DIR * )

IMPORT_C struct dirent *readdir(DIR *)

See also: close() lseek() open() read()

Parameters
Refer to opendir() for the documentation

rewinddir ( DIR * )

IMPORT_C voidrewinddir(DIR *)

See also: close() lseek() open() read()

Parameters
Refer to opendir() for the documentation

alphasort ( const void *, const void * )

IMPORT_C intalphasort(const void *,
const void *
)

See also: directory() malloc() qsort() dir()

Parameters
Refer to scandir() for the documentation

scandir ( const char *, struct dirent ***, int(*)(struct dirent *), int(*)(const void *, const void *) )

IMPORT_C intscandir(const char *,
struct dirent ***,
int(*)(struct dirent *),
int(*)(const void *, const void *)
)

The scandir function reads the directory dirname and builds an array of pointers to directory entries using malloc It returns the number of entries in the array. A pointer to the array of directory entries is stored in the location referenced by namelist.

The select argument is a pointer to a user supplied subroutine which is called by scandir to select which entries are to be included in the array. The select routine is passed a pointer to a directory entry and should return a non-zero value if the directory entry is to be included in the array. If select is null, then all the directory entries will be included.

The compar argument is a pointer to a user supplied subroutine which is passed to qsort to sort the completed array. If this pointer is null, the array is not sorted.

The alphasort function is a routine which can be used for the compar argument to sort the array alphabetically.

The memory allocated for the array can be deallocated with free , by freeing each pointer in the array and then the array itself.

Examples:
//Illustrates how to use scandir API.
#include <dirent.h>
Void  scandirTest()
    {
       struct dirent **namelist;
       int n;
       // Function call to get the dir entries into the namelist.
       n = scandir("\home\manjus\GETTEXT", &namelist;, 0, 0);
      
       if(n > 0) // if scandir is successful it retuns the number of entries greater than 0
       {
             // print all the entries in the directory.
        while(n--)
        {
                printf("dir name @ pos %d is %s",n,namelist[n]->d_name);
        }
       }
     }
Diagnostics: Returns -1 if the directory cannot be opened for reading or if malloc cannot allocate enough memory to hold all the data structures.

Limitations:

The dirname parameter in scandir() should not exceed 256 characters in length.

See also: directory() malloc() qsort() dir()

Parameters
Note: This description also covers the following functions - alphasort()

seekdir ( DIR *, long )

IMPORT_C voidseekdir(DIR *,
long
)

See also: close() lseek() open() read()

Parameters
Refer to opendir() for the documentation

telldir ( DIR * )

IMPORT_C longtelldir(DIR *)

See also: close() lseek() open() read()

Parameters
Refer to opendir() for the documentation

closedir ( DIR * )

IMPORT_C intclosedir(DIR *)

See also: close() lseek() open() read()

Parameters
Refer to opendir() for the documentation