/** @file  ../include/dirent.h

@internalComponent

*/

/** @fn getdirentries(int x, char *ptr, int y, long *lptr) 

getdirentries(int fd, char *buf, int nbytes, long *basep)

@param x

@param ptr

@param y

@param lptr

@return   If successful, the number of bytes actually transferred is returned.

Otherwise, -1 is returned and the global variable errno is set to indicate the error.

  The getdirentries system call reads directory entries from the directory 

referenced by the file descriptor x into the buffer pointed to by ptr, in a file system independent format. Up to y of data will be transferred. The y argument must be greater than or equal to the block size associated 

with the file, see stat. Some file systems may not support these system 

calls with buffers smaller than this size.

 The data in the buffer is a series of dirent

@code

structures each containing the following entries: u_int32_t d_fileno;

u_int16_t d_reclen;

u_int8_t  d_type;

u_int8_t  d_namlen;

char  d_name[MAXNAMELEN + 1];/* see below */

@endcode

 The d_fileno entry is a number which is unique for each distinct file in 

  the file system. Files that are linked by hard links (see link ) have the same d_fileno. The d_reclen entry is the length, in bytes, of the directory record. The d_type entry is the type of the file pointed to by the directory record. 

  The file type values are defined in \<sys/dirent.h\>. Presently, however, file type is not supported 

  and d_type is set to 0. The d_name entry contains a null terminated file name. The d_namlen entry specifies the length of the file name excluding the null 

  byte. Thus the actual size of d_name may vary from 1 to MAXNAMELEN + 1.

 Entries may be separated by extra space.

The d_reclen entry may be used as an offset from the start of a dirent structure to the next structure, if any.

 The actual number of bytes transferred is returned. The current position pointer 

  associated with x is set to point to the next block of entries. The pointer may not 

  advance by the number of bytes returned by getdirentries . A value of zero is returned when the end of the directory 

  has been reached.

 The getdirentries system call writes the position of the block read into 

  the location pointed to by lptr. Alternatively, the current position pointer may be set and retrieved 

  by lseek. The current position pointer should only 

  be set to a value returned by lseek, a value returned in the location pointed 

  to by basep ( (getdirentries); only) or zero.

Examples:

@code

/* reading directory stream using getdirenttries */ 

/* considering directory c:    emp already exists */

#include <stdio.h>

int main()

{

        int retval;

        long basep=(off_t) 0;

        char buf[1024];

        struct dirent * d;

        char * dname="C:\       emp\

        char * fname="C:\       emp\input.txt";

        int fd,fd1;

        fd1=open(fname,O_WRONLY|O_CREAT);

        if(fd==-1)

                {

                printf("file creation failed");

                return -1;

                }

        fd=open(dname,O_RDONLY);

        if(fd==-1)

                {

                printf("directory opening failed");

                return -1;

                }

        retval = getdirentries (fd, buf,(unsigned int)sizeof (buf),&basep);

        if(retval == -1)

        {

                printf("getdirentries call failed");

                return -1;

        }               

        d=(struct dirent *)buf;

        printf("name of the file in the newly created directory is \"%s\",d-d_name);

        close(fd1);

        close(fd);

        return 0;

}

@endcode

 Output

@code

name of the file in the newly created directory is "input.txt"

@endcode

@see lseek()

@see open()

@publishedAll

@externallyDefinedApi

*/

/** @fn  opendir(const char *_path)

@param _path

Note: This description also covers the following functions -

 readdir()  readdir_r()  telldir()  seekdir()  rewinddir()  closedir()  dirfd() 

@return   closedir function returns 0 on success or -1 on failure.

  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 .

@code

 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;

@endcode

Examples:

@code

/* 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;

}

@endcode

@code

Output 

Directory Test opened

@endcode

Limitations:

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

@see close()

@see lseek()

@see open()

@see read()

@publishedAll

@externallyDefinedApi

*/

/** @fn  readdir(DIR *dp)

@param dp

Refer to opendir() for the documentation

@see close()

@see lseek()

@see open()

@see read()

@publishedAll

@externallyDefinedApi

*/

/** @fn  rewinddir(DIR *dp)

@param dp

Refer to opendir() for the documentation

@see close()

@see lseek()

@see open()

@see read()

@publishedAll

@externallyDefinedApi

*/

/** @fn  alphasort(const void *d1, const void *d2)

@param d1

@param d2

Refer to scandir() for the documentation

@see directory()

@see malloc()

@see qsort()

@see dir()

@publishedAll

@externallyDefinedApi

*/

/** @fn  scandir(const char *dirname, struct dirent ***namelist, int(*)(struct dirent *), int(*)(const void *, const void *))

@param dirname

@param namelist

Note: This description also covers the following functions -

 alphasort() 

  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:

@code

//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);

        }

       }

     }

@endcode

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 directory()

@see malloc()

@see qsort()

@see dir()

@publishedAll

@externallyDefinedApi

*/

/** @fn  seekdir(DIR *dp, long index)

@param dp

@param index

Refer to opendir() for the documentation

@see close()

@see lseek()

@see open()

@see read()

@publishedAll

@externallyDefinedApi

*/

/** @fn  telldir(DIR *dp)

@param dp

Refer to opendir() for the documentation

@see close()

@see lseek()

@see open()

@see read()

@publishedAll

@externallyDefinedApi

*/

/** @fn  closedir(DIR *dp)

@param dp

Refer to opendir() for the documentation

@see close()

@see lseek()

@see open()

@see read()

@publishedAll

@externallyDefinedApi

*/

/** @typedef typedef struct _dirdesc  DIR

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

@publishedAll

@externallyDefinedApi

*/

/** @def dirfd(dirp)

get directory stream file descriptor

@publishedAll

@released

*/

/** @def DTF_HIDEW

flags for opendir2. hide whiteout entries.

@publishedAll

@released

*/

/** @def DTF_NODUP

flags for opendir2. don't return duplicate names.

@publishedAll

@released

*/

/** @def DTF_REWIND

flags for opendir2. rewind after reading union stack.

@publishedAll

@released

*/

/** @def __DTF_READALL

flags for opendir2. everything has been read.

@publishedAll

@released

*/