Read Directory Entries (QHFRDDR) API

The Read Directory Entries (QHFRDDR) API reads one or more directory entries from a directory opened with the Open Directory (QHFOPNDR) API. The QHFOPNDR API's path name parameter determines which directory entries are read. The QHFOPNDR API's attribute selection table determines what information is returned for each directory entry. For details about the QHFOPNDR API, see Open Directory (QHFOPNDR) API.

You must open a directory before reading from it. The open directory handle returned by the QHFOPNDR API is needed as input to the QHFRDDR API.

The QHFRDDR API reads directory entries sequentially. Each time the QHFRDDR API is called, the directory pointer is advanced by the number of directory entries returned in the data buffer. Subsequent calls of the QHFRDDR API return additional directory entries, until there are no more to return.

Authorities and Locks

None.

Required Parameter Group

Open directory handle

INPUT; CHAR(16)

The directory handle obtained when the directory was opened with the QHFOPNDR API.

Data buffer

OUTPUT; CHAR(*)

The buffer to hold the directory entry information returned. For the format, see Data Buffer.

Data buffer length

INPUT; BINARY(4)

The length of the data buffer described in Data Buffer. The buffer must be large enough to hold the requested attributes for at least one directory entry. If it is too small, the read operation fails and no data is returned. However, the length of data returned parameter contains the total number of bytes the file system tried to return for the next directory entry. The application should increase the data buffer size to at least that number and try the request again.

Number of directory entries to read

INPUT; BINARY(4)

The number of directory entries to place in the data buffer.

Number of directory entries read

OUTPUT; BINARY(4)

The number of directory entries actually placed in the data buffer. The value of this field is 0 when there are no more directory entries to read.

Length of data returned

OUTPUT; BINARY(4)

If the read operation is successful, this field contains the total number of bytes returned in the data buffer. If the read operation is not successful because the data buffer is not large enough to hold at least one entry, this field contains the number of bytes required to hold the requested attributes for the next directory entry.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Data Buffer

The data buffer holds the information returned about each directory entry. What information is returned depends mostly on what attributes are selected in the attribute selection table when the directory is opened with the QHFOPNDR API. However, the QNAME attribute is returned with every directory entry even though it is never specified in the attribute selection table. Thus, the data buffer always contains at least one piece of information about each directory entry found, its name. If the directory entry exists but cannot be read because of damage or a lock by another process, two pieces of information are returned: the name, given in the QNAME attribute, and the error that occurred, given in the QERROR attribute. For details about these attributes, see HFS Directory Entry Attributes.

The data buffer has three logical parts:

1. The first field specifies the number of directory entries returned.
   
   
2. The next fields give the offsets to the directory entries returned. There is one offset field for each directory entry.
   
   
3. Next are the attribute information tables for the directory entries returned. There is one attribute information table for each directory entry.

The following table shows the format of the data buffer. The offset fields are repeated until the offsets for all directory entries are listed; the attribute information table for each directory entry is repeated in the same way.

The format of the data buffer is:

Error Messages