readdir2 (BPX1RD2, BPX4RD2) — Read an entry from a directory
Function
The readdir2 callable service reads multiple name entries from a directory.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1RD2): | 31-bit |
AMODE (BPX4RD2): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
Format
CALL BPX1RD2,(Directory_file_descriptor,
UIO,
Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4RD2 with the same parameters. Some of the addresses in the UIO structure are doublewords.
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 of0
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
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. 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 a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.
Usage notes
- 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.
- 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.
- 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.
- 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 of0
. The caller of the readdir2 service should check for both conditions. - 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.
- The cursor information that is returned from a call to readdir2() can be used on successive calls to readdir().
- 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.
- 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.
- 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.
- 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.
- 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
Characteristics and restrictions
There are no restrictions on the use of the readdir2 service.