readdir()--Read Directory Entry

 #include <sys/types.h>
 #include <dirent.h>

 struct dirent *readdir(DIR *dirp);  

The readdir() function returns a pointer to a dirent structure describing the next directory entry in the directory stream associated with dirp.

A call to readdir() overwrites data produced by a previous call to readdir() on the same directory stream. Calls for different directory streams do not overwrite the data of each other.

If the call to readdir() actually reads the directory, the access time of the directory is updated.

readdir() performs translation if necessary to convert the directory entry name into the CCSID (coded character set identifier) of the job at the time of the call to opendir(). If the directory entry name cannot be represented in that CCSID, then that directory entry will not be returned by readdir() and no error indication will occur.

Parameters

dirp

(Input) A pointer to a DIR that refers to the open directory stream to be read. This pointer is returned by opendir() (see opendir()--Open Directory).

See QlgReaddir()--Read Directory Entry for a description and an example of supplying the dirp in any CCSID, using a dirent_lg structure.

A dirent structure has the following contents:

Authorities

No authorization is required. Authorization is verified during opendir().

Note: When reading the contents of the /QSYS.LIB directory, user profile (*USRPRF) objects to which the caller does not have any authority (i.e., *EXCLUDE) will not be returned from readdir().

Return Value

value

readdir() was successful. The value returned is a pointer to a dirent structure describing the next directory entry in the directory stream.

NULL pointer

One of the following has occurred:

• readdir() reached the end of the directory stream. The errno global variable is not changed.
• readdir() was not successful. The errno is set.

Error Conditions

If readdir() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. The readdir_r() API should be used to read a directory when running in a multithreaded job.
   
   
2. Save the data from readdir(), if required, before calling closedir(), because closedir() frees the data.
   
   
3. If the dirp argument passed to readdir() does not refer to an open directory stream, readdir() returns the [EBADF] error.
   
   
4. readdir() buffers multiple directory entries to improve performance. This means the directory is not actually read on each call to readdir(). As a result, files that are added to the directory after opendir() or rewinddir() may not be returned on calls to readdir(), and files that are removed may still be returned on calls to readdir().
   
   
5. readdir() also returns directory entries for dot (.) and dot-dot (..) subdirectories.
   
   
6. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

   Calls to readdir() that update the access time of the directory use the normal rules that apply to libraries and database files. At most, the access time is updated once per day.

7. QDLS File System Differences

   The access time of the directory is updated on opendir(). The access time is not affected by readdir().

   When objects in QDLS are accessed, the country or region ID and language ID of the directory entry name are always set to the country or region ID and language ID of the system.

   When a readdir() operation specifies the /QDLS directory, the user must have *USE authority to each child object of the /QDLS directory (that is, *USE authority to each object immediately below QDLS in the directory hierarchy). A directory entry is returned only for those objects for which the user has *USE authority. If the readdir() operation specifies a directory below QDLS, a directory entry is returned for all objects, even if the user does not have *USE authority for some of the objects.

8. QOPT File System Differences

   The access time of the directory is not updated on a readdir() operation.

Related Information

• The <sys/types.h> file (see Header Files for UNIX^®-Type Functions)
• The <dirent.h> file see Header Files for UNIX-Type Functions)
• opendir()--Open Directory
• QlgReaddir()--Read Directory Entry
• rewinddir()--Reset Directory Stream to Beginning
• closedir()--Close Directory
• pathconf()--Get Configurable Path Name Variables

Example

The following example reads the contents of the "root" (/) directory.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <sys/types.h>
#include <dirent.h>
#include <errno.h>
#include <stdio.h>

main() {
  DIR *dir;
  struct dirent *entry;

  if ((dir = opendir("/")) == NULL)
    perror("opendir() error");
  else {
    puts("contents of root:");
    while ((entry = readdir(dir)) != NULL)
      printf("  %s\n", entry->d_name);
    closedir(dir);
  }
}

Output:

contents of root:
  .
  ..
  QSYS.LIB
  QDLS
  QOpenSys
  QOPT
  home

[ Back to top | UNIX-Type APIs | APIs by category ]