readdir()--Read Directory Entry
Syntax
#include <sys/types.h> #include <dirent.h> struct dirent *readdir(DIR *dirp);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: No; see Usage Notes.
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.
The readdir() function converts the directory entry name into the CCSID (coded character set identifier) of the job at the time of the call to opendir(), or to the CCSID specified on the call to QlgOpendir(). 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.
QlgOpendir() allows the CCSID to be specified in the Qlg_Path_Name_T structure. See QlgOpendir()--Open Directory (using NLS-enabled path name) for more information.
Parameters
- dirp
- (Input) A pointer to a DIR that refers to the open directory stream to be read. This pointer is returned by opendir() or QlgOpendir() (see opendir()--Open Directory or QlgOpendir()--Open Directory (using NLS-enabled path name)).
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.
A dirent structure has the following contents:
char d_reserved1[16] Reserved. unsigned int d_fileno_gen_id The generation ID associated with the file ID. ino_t d_fileno The file ID of the file. This number uniquely identifies the object within a file system. unsigned int d_reclen The length of the directory entry in bytes. int d_reserved3 Reserved. char d_reserved4[6] Reserved. char d_reserved5[2] Reserved. qlg_nls_t d_nlsinfo National language information about d_name. The following fields are defined: - int ccsid
- CCSID of the characters in the d_name field.
- char country_id[2]
- Country or region identifier associated with the d_name field.
- char language_id[3]
- Language identifier associated with the d_name field.
- char nls_reserved[3]
- Reserved.
unsigned int d_namelen The length of the name in bytes, excluding the null terminator. char d_name[640] A string that gives the name of a file in the directory. This string ends in a terminating null, and has a maximum length of {NAME_MAX} bytes, not including the terminating NULL (see pathconf()--Get Configurable Path Name Variables). - 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.
Error condition | Additional information |
---|---|
[EACCES] |
If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. |
[EAGAIN] | |
[EBADFID] | |
[EBADF] | |
[EBUSY] | |
[EDAMAGE] | |
[EFAULT] | |
[EINVAL] | |
[EIO] | |
[ENOSPC] | |
[ENOTAVAIL] | |
[ENOTSAFE] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNKNOWN] |
If interaction with a file server is required to access the object, errno could indicate one of the following errors:
Error condition | Additional information |
---|---|
[EADDRNOTAVAIL] | |
[ECONNABORTED] | |
[ECONNREFUSED] | |
[ECONNRESET] | |
[EHOSTDOWN] | |
[EHOSTUNREACH] | |
[ENETDOWN] | |
[ENETRESET] | |
[ENETUNREACH] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[ETIMEDOUT] | |
[EUNATCH] |
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPFA0D4 E | File system error occurred. Error number &1. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- The readdir_r(), readdir_r_ts64(), or
QlgReaddir_r() API should be used to read a directory
when running in a multithreaded job.
- Save the data from readdir(), if required, before calling
closedir(), because closedir() frees the
data.
- If the dirp argument passed to readdir() does not
refer to an open directory stream, readdir() returns the
[EBADF] error.
- 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().
- readdir() also returns directory entries for dot (.) and
dot-dot (..) subdirectories.
- 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.
- 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.
- 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
- QlgOpendir()--Open Directory (using NLS-enabled path name)
- QlgReaddir()--Read Directory Entry (using NLS-enabled path name)
- readdir_r()--Read Directory Entry
- QlgReaddir_r()--Read Directory Entry (using NLS-enabled path name)
- readdir_r_ts64()--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
API introduced: V3R1