sl@0: /** @file  ../include/dirent.h
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: /** @fn getdirentries(int x, char *ptr, int y, long *lptr) 
sl@0: getdirentries(int fd, char *buf, int nbytes, long *basep)
sl@0: @param x
sl@0: @param ptr
sl@0: @param y
sl@0: @param lptr
sl@0: @return   If successful, the number of bytes actually transferred is returned.
sl@0: Otherwise, -1 is returned and the global variable errno is set to indicate the error.
sl@0: 
sl@0:   The getdirentries system call reads directory entries from the directory 
sl@0: 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 
sl@0: with the file, see stat. Some file systems may not support these system 
sl@0: calls with buffers smaller than this size.
sl@0: 
sl@0:  The data in the buffer is a series of dirent
sl@0: @code
sl@0: structures each containing the following entries: u_int32_t d_fileno;
sl@0: u_int16_t d_reclen;
sl@0: u_int8_t  d_type;
sl@0: u_int8_t  d_namlen;
sl@0: char  d_name[MAXNAMELEN + 1];/* see below */
sl@0: @endcode
sl@0: 
sl@0:  The d_fileno entry is a number which is unique for each distinct file in 
sl@0:   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. 
sl@0:   The file type values are defined in \<sys/dirent.h\>. Presently, however, file type is not supported 
sl@0:   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 
sl@0:   byte. Thus the actual size of d_name may vary from 1 to MAXNAMELEN + 1.
sl@0: 
sl@0:  Entries may be separated by extra space.
sl@0: The d_reclen entry may be used as an offset from the start of a dirent structure to the next structure, if any.
sl@0: 
sl@0:  The actual number of bytes transferred is returned. The current position pointer 
sl@0:   associated with x is set to point to the next block of entries. The pointer may not 
sl@0:   advance by the number of bytes returned by getdirentries . A value of zero is returned when the end of the directory 
sl@0:   has been reached.
sl@0: 
sl@0:  The getdirentries system call writes the position of the block read into 
sl@0:   the location pointed to by lptr. Alternatively, the current position pointer may be set and retrieved 
sl@0:   by lseek. The current position pointer should only 
sl@0:   be set to a value returned by lseek, a value returned in the location pointed 
sl@0:   to by basep ( (getdirentries); only) or zero.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: /* reading directory stream using getdirenttries */ 
sl@0: /* considering directory c:    emp already exists */
sl@0: #include <stdio.h>
sl@0: int main()
sl@0: {
sl@0:         int retval;
sl@0:         long basep=(off_t) 0;
sl@0:         char buf[1024];
sl@0:         struct dirent * d;
sl@0:         char * dname="C:\       emp\
sl@0:         char * fname="C:\       emp\input.txt";
sl@0:         int fd,fd1;
sl@0:         fd1=open(fname,O_WRONLY|O_CREAT);
sl@0:         if(fd==-1)
sl@0:                 {
sl@0:                 printf("file creation failed");
sl@0:                 return -1;
sl@0:                 }
sl@0:         fd=open(dname,O_RDONLY);
sl@0:         if(fd==-1)
sl@0:                 {
sl@0:                 printf("directory opening failed");
sl@0:                 return -1;
sl@0:                 }
sl@0:         retval = getdirentries (fd, buf,(unsigned int)sizeof (buf),&basep);
sl@0:         if(retval == -1)
sl@0:         {
sl@0:                 printf("getdirentries call failed");
sl@0:                 return -1;
sl@0:         }               
sl@0:        
sl@0:         d=(struct dirent *)buf;
sl@0:         
sl@0:         printf("name of the file in the newly created directory is \"%s\",d-d_name);
sl@0:         
sl@0:         close(fd1);
sl@0:         close(fd);
sl@0:         return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  Output
sl@0: @code
sl@0: name of the file in the newly created directory is "input.txt"
sl@0: 
sl@0: @endcode
sl@0: @see lseek()
sl@0: @see open()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  opendir(const char *_path)
sl@0: @param _path
sl@0: 
sl@0: Note: This description also covers the following functions -
sl@0:  readdir()  readdir_r()  telldir()  seekdir()  rewinddir()  closedir()  dirfd() 
sl@0: 
sl@0: @return   closedir function returns 0 on success or -1 on failure.
sl@0: 
sl@0:   The opendir function
sl@0: opens the directory named by _path ,
sl@0: associates a directory stream with it
sl@0: and
sl@0: returns a pointer to be used to identify the directory stream in subsequent operations.
sl@0: The pointer NULL is returned if filename cannot be accessed, or if it cannot malloc enough memory to hold the whole thing.
sl@0: 
sl@0:  The readdir function
sl@0: returns a pointer to the next directory entry.
sl@0: It returns NULL upon reaching the end of the directory or detecting an invalid seekdir operation.
sl@0: 
sl@0:  The readdir_r function
sl@0: provides the same functionality as readdir ,
sl@0: but the caller must provide a directory entry buffer to store the results in.
sl@0: If the read succeeds, result is pointed at the entry ;
sl@0: upon reaching the end of the directory result is set to NULL .
sl@0: The readdir_r function
sl@0: returns 0 on success or an error number to indicate failure.
sl@0: 
sl@0:  The telldir function
sl@0: returns the current location associated with the named directory stream .
sl@0: Values returned by telldir are good only for the lifetime of the DIR pointer, dirp ,
sl@0: from which they are derived.
sl@0: If the directory is closed and then
sl@0: reopened, prior values returned by telldir will no longer be valid.
sl@0: 
sl@0:  The seekdir function
sl@0: sets the position of the next readdir operation on the directory stream .
sl@0: The new position reverts to the one associated with the directory stream when the telldir operation was performed.
sl@0: 
sl@0:  The rewinddir function
sl@0: resets the position of the named directory stream to the beginning of the directory.
sl@0: 
sl@0:  The closedir function
sl@0: closes the named directory stream and frees the structure associated with the dirp pointer,
sl@0: returning 0 on success.
sl@0: On failure, -1 is returned and the global variable errno is set to indicate the error.
sl@0: 
sl@0:  The dirfd function
sl@0: returns the integer file descriptor associated with the named directory stream ,
sl@0: see open .
sl@0: 
sl@0: @code
sl@0:  Sample code which searches a directory for entry ‘‘name’’ is: len = strlen(name);
sl@0: dirp = opendir(".");
sl@0: while ((dp = readdir(dirp)) != NULL)
sl@0:         if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
sl@0:                 (void)closedir(dirp);
sl@0:                 return FOUND;
sl@0:         }
sl@0: (void)closedir(dirp);
sl@0: return NOT_FOUND;
sl@0: @endcode
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: /* Detailed description: This test code demonstrates usage of opendir system call, open directory name test.
sl@0:  Preconditions: Expects Test directory to be present in the current working directory.
sl@0: */
sl@0:  #include <sys/types.h>
sl@0:  #include <dirent.h>
sl@0: int main()
sl@0: {
sl@0:   DIR *DirHandle;
sl@0:   if(!(DirHandle = opendir("Test") ) ) 
sl@0:   {
sl@0:      printf("Failed to open directory Test\n");
sl@0:      return -1;
sl@0:   }
sl@0:   printf("Directory Test opened \n");
sl@0:   return 0;
sl@0: }
sl@0: @endcode
sl@0: @code
sl@0: Output 
sl@0: Directory Test opened
sl@0: @endcode
sl@0: 
sl@0: Limitations:
sl@0: 
sl@0: The filename parameter of the opendir() function should not exceed 256 characters in length.
sl@0: 
sl@0: @see close()
sl@0: @see lseek()
sl@0: @see open()
sl@0: @see read()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  readdir(DIR *dp)
sl@0: @param dp
sl@0: Refer to opendir() for the documentation
sl@0: @see close()
sl@0: @see lseek()
sl@0: @see open()
sl@0: @see read()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @fn  rewinddir(DIR *dp)
sl@0: @param dp
sl@0: Refer to opendir() for the documentation
sl@0: @see close()
sl@0: @see lseek()
sl@0: @see open()
sl@0: @see read()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  alphasort(const void *d1, const void *d2)
sl@0: @param d1
sl@0: @param d2
sl@0: Refer to scandir() for the documentation
sl@0: @see directory()
sl@0: @see malloc()
sl@0: @see qsort()
sl@0: @see dir()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  scandir(const char *dirname, struct dirent ***namelist, int(*)(struct dirent *), int(*)(const void *, const void *))
sl@0: @param dirname
sl@0: @param namelist
sl@0: 
sl@0: Note: This description also covers the following functions -
sl@0:  alphasort() 
sl@0: 
sl@0:   The scandir function
sl@0: reads the directory dirname and builds an array of pointers to directory
sl@0: entries using malloc It returns the number of entries in the array.
sl@0: A pointer to the array of directory entries is stored in the location
sl@0: referenced by namelist.
sl@0: 
sl@0:  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.
sl@0: The select routine is passed a
sl@0: pointer to a directory entry and should return a non-zero
sl@0: value if the directory entry is to be included in the array.
sl@0: If select is null, then all the directory entries will be included.
sl@0: 
sl@0:  The compar argument is a pointer to a user supplied subroutine which is passed to qsort to sort the completed array.
sl@0: If this pointer is null, the array is not sorted.
sl@0: 
sl@0:  The alphasort function
sl@0: is a routine which can be used for the compar argument to sort the array alphabetically.
sl@0: 
sl@0:  The memory allocated for the array can be deallocated with free ,
sl@0: by freeing each pointer in the array and then the array itself.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: //Illustrates how to use scandir API.
sl@0: #include <dirent.h>
sl@0: Void  scandirTest()
sl@0:     {
sl@0:        struct dirent **namelist;
sl@0:        int n;
sl@0:        // Function call to get the dir entries into the namelist.
sl@0:        n = scandir("\home\manjus\GETTEXT", &namelist;, 0, 0);
sl@0:       
sl@0:        if(n > 0) // if scandir is successful it retuns the number of entries greater than 0
sl@0:        {
sl@0:              // print all the entries in the directory.
sl@0:         while(n--)
sl@0:         {
sl@0:                 printf("dir name @ pos %d is %s",n,namelist[n]->d_name);
sl@0:         }
sl@0:        }
sl@0:      }
sl@0: 
sl@0: @endcode
sl@0: Diagnostics:
sl@0:  Returns -1 if the directory cannot be opened for reading or if malloc cannot allocate enough memory to hold all the data structures.
sl@0: 
sl@0: Limitations:
sl@0: 
sl@0: The dirname parameter in scandir() should not exceed 256 characters in length.
sl@0: 
sl@0: @see directory()
sl@0: @see malloc()
sl@0: @see qsort()
sl@0: @see dir()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  seekdir(DIR *dp, long index)
sl@0: @param dp
sl@0: @param index
sl@0: Refer to opendir() for the documentation
sl@0: @see close()
sl@0: @see lseek()
sl@0: @see open()
sl@0: @see read()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  telldir(DIR *dp)
sl@0: @param dp
sl@0: Refer to opendir() for the documentation
sl@0: @see close()
sl@0: @see lseek()
sl@0: @see open()
sl@0: @see read()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @fn  closedir(DIR *dp)
sl@0: @param dp
sl@0: Refer to opendir() for the documentation
sl@0: @see close()
sl@0: @see lseek()
sl@0: @see open()
sl@0: @see read()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @typedef typedef struct _dirdesc  DIR
sl@0: 
sl@0: defines DIR  data type through typedef. A type representing a directory stream.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @def dirfd(dirp)
sl@0: 
sl@0: get directory stream file descriptor
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @def DTF_HIDEW
sl@0: 
sl@0: flags for opendir2. hide whiteout entries.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @def DTF_NODUP
sl@0: 
sl@0: flags for opendir2. don't return duplicate names.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @def DTF_REWIND
sl@0: 
sl@0: flags for opendir2. rewind after reading union stack.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @def __DTF_READALL
sl@0: 
sl@0: flags for opendir2. everything has been read.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: