readdir2 (BPX1RD2, BPX4RD2) — Read an entry from a directory

Function

The readdir2 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).

UIO

Supplied and returned parameter

Type:

Structure

Length:

Fuio#Len (from the BPXYFUIO macro)

The name of an area that contains the user input and output block. This area is mapped by the BPXYFUIO macro (see BPXYFUIO — Map file system user I/O block).

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the readdir2 service returns the number of directory entries that have been read into the buffer that is pointed to by the UIO, or -1 if the request 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 readdir2 service stores the return code. The readdir2 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 readdir2 service can return one of the following values in the Return_code parameter:

Return code	Explanation
EACCES	The FuioChkAcc bit was set to request that an access check be performed, but the calling process does not have permission to read the specified directory.
EBADF	The Directory_file_descriptor argument does not refer to an open directory.
EINVAL	There was a parameter error; for example, a supplied area was too small. The following reason codes can accompany the return code: JRInvalidFuio,JrBytes2RWZero, JRRddPlusNoCursorSupp

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the readdir2 service stores the reason code. The readdir2 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, and 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, which is mapped by BPXYDIRE (see 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 charcter.
   • 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 end of the directory is indicated when a Return_value of 0 entries is returned.

   In addition, 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 readdir2 service should check for both conditions.

5. Two protocols are supported for reading through large directories with successive calls:
   • Cursor protocol. The cursor, or offset, that is returned in the UIO by the readdir2 service contains file-system-specific information that locates the next directory entry. The cursor and buffer must be preserved by the caller from one readdir2 call to the next, and reading proceeds based on the cursor. The buffer must not be altered between calls, unless the directory has been rewound.
   • Index protocol. The index that is set in the UIO by the caller determines which entry to start reading from. To read through the directory, the caller increments the index by the number of entries that were returned on the previous call.

     Because this index represents the number of entries into the directory, the caller should be aware that if entries are being added or deleted in the directory while the call is being done, duplicate or missing entries could result.

     The cursor protocol is preferred for better performance.

6. The cursor information that is returned from a call to readdir2() can be used on successive calls to readdir().
7. If the contents of the directory have changed (files have been added or removed) since a previous call to the readdir2 service, a call should be made to the rewinddir service so that the updated contents of the directory can be read.
8. The following UIO fields should be set to specify the details of the read directory request:

   FuioID

   Contains Fuio#ID (from the BPXYFUIO macro).

   FuioLen

   Contains the length of the UIO structure.

   FuioChkAcc

   Requests that the PFS perform required access checking before performing the requested readdir2 operation.

   FuioBufferAddr

   Contains the address of a buffer where the directory entries are to be returned.

   FuioBufferAlet

   Contains the ALET of the buffer where the directory entries are to be returned.

   FuioIBytesRW

   Specifies the maximum number of bytes that can be written to the output buffer.

   FuioRDIndex

   Specifies the first directory entry that is to be returned when the index protocol is used. The directory can be thought of as a 1–based array, and the index specifies which entry in the directory to begin reading from. When the FuioRDIndex is set to any nonzero value it will override any value in the FuioCursor field. To begin reading at the first directory entry, set the FuioRDIndex to 1.

   FuioCursor

   When the cursor protocol is used, this specifies a value, returned on the previous readdir2 call, that indicates the next entry to be read; or 0 on the first call. The FuioRDIndex must be set to 0 when the cursor protocol is being used. To begin reading at the first directory entry, both the FuioRDIndex and the FuioCursor should be set to 0.

   FuioRddPlus

   Indicates that the request is for the ReaddirPlus function. The attributes for each entry should be included in the output. If FuioRddPlus is specified then the Index protocol is used.

9. Some addresses in the UIO structure are doublewords, and some are not. If the buffer address is a 64-bit address, the caller must set the FUIOADDR64 flag in BPXYFUIO, and the FUIOBUFF64VADDR must contain the 64-bit virtual buffer address. When FUIOADDR64 is not set, the FUIOBUFFERADDR must contain the 31-bit virtual buffer address.
10. The following UIO fields are returned by the readdir2 service:

    FuioPSWKey

    This field is set to the caller's key.

    FuioCursor

    This field is set to the current cursor position after the readdir2 has occurred.

    FuioAsid

    This field is set to the caller's ASID.

    FuioCVerRet

    This field indicates that the Cookie Verifier (FuioCVer) is being returned.

    FuioCVer

    When FuioCVerRet is on, this field is set to the Cookie Verifier for the directory that is being read. When a directory is being read with multiple reads, you can use the FuioCVer that is returned to compare each Cookie Verifier with the previous one. If the directory has been modified between reads, you can reject the request, because the results will not be valid.

11. The buffer contents that are returned by the readdir2 service are mapped by the BPXYDIRE macro (see BPXYDIRE — Map directory entries for readdir).

Related services

• closedir (BPX1CLD, BPX4CLD) — Close a directory
• opendir (BPX1OPD, BPX4OPD) — Open a directory
• readdir (BPX1RDD, BPX4RDD) — Read an entry from a directory
• rewinddir (BPX1RWD, BPX4RWD) — Reposition a directory stream to the beginning

Characteristics and restrictions

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