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

 */