readdir (BPX1RDD, BPX4RDD) — Read an entry from a directory

Function

The readdir callable service reads multiple name entries from a directory.

Requirements

Parameters

Directory_file_descriptor

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the directory file descriptor that was returned when the directory was opened (see opendir (BPX1OPD, BPX4OPD) — Open a directory).

Buffer_address

Parameter supplied and returned

Type:

Address

Length:

Fullword (doubleword)

The name of a fullword (doubleword) that contains the address of the buffer in which readdir is to write the directory entries. This address must be supplied to the readdir call. The directory entries are mapped by the BPXYDIRE macro; see BPXYDIRE — Map directory entries for readdir.

Buffer_ALET

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the ALET for the Buffer_address that identifies the address space or data space where the buffer resides.

You should specify a Buffer_ALET of 0 for the normal case of a buffer in the user's address space (current primary address space). If a value other than 0 is specified for the Buffer_ALET, the value must represent a valid entry in the dispatchable unit access list (DUAL).

Buffer_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length, in bytes, of the buffer that is pointed to by Buffer_address.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the readdir service returns the number of directory entries that have been read into the buffer, or -1 if it is unsuccessful. A value of 0 in Return_value indicates the end of the directory.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the readdir service stores the return code. The readdir service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The readdir service can return one of the following values in the Return_code parameter:

Return code	Explanation
EBADF	The Directory_file_descriptor argument does not refer to an open directory.
EINVAL	The buffer is too small to contain any entries.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the readdir service stores the reason code. The readdir service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

1. This interface differs from the POSIX C high-level-language interface in that it returns more than one directory entry; it also returns the entries in the caller's buffer.
2. The buffer contains a variable number of variable-length directory entries. Only full entries are placed in the buffer, up to the buffer size specified, and the number of entries is returned.
3. Each directory entry that is returned has the following format (as shown on BPXYDIRE — Map directory entries for readdir):
   • 2-byte Entry_length. The total entry length, including itself.
   • 2-byte Name_length. The length of the following Member_name subfield.
   • Member_name. A character field of length Name_length. This name is not terminated by a null character.
   • File system specific data. If Name_length + 4 = Entry_length, this subfield is not present.
   The entries are packed together, and the length fields are not aligned on any particular boundary.
4. The buffer that is returned by one call to the readdir service must be used again on the next call to the readdir service, to continue reading entries from where you left off. The buffer must not be altered between calls, unless the directory has been rewound.
5. If the contents of the directory have changed (files have been added or removed) since a previous call to the readdir service, a call should be made to the rewinddir service so that the updated contents of the directory can be read.
6. The end of the directory is indicated in one of two ways:
   • A Return_value of 0 entries is returned.
   • Some physical file systems may return a null name entry as the last entry in the caller's buffer. A null name entry has an Entry_length of 4 and a Name_length of 0.
   The caller of the readdir service should check for both conditions.
7. HFS returns names in sorted order. Other z/OS® UNIX file systems, such as zFS and TFS, follow the UNIX standard and do not return names in sorted order.

Related services

• closedir (BPX1CLD, BPX4CLD) — Close a directory
• opendir (BPX1OPD, BPX4OPD) — Open a directory
• rewinddir (BPX1RWD, BPX4RWD) — Reposition a directory stream to the beginning

Characteristics and restrictions

There are no restrictions on the use of the readdir service.