Retrieve Directory Entry Attributes (QHFRTVAT) API

The Retrieve Directory Entry Attributes (QHFRTVAT) API retrieves attribute information from a specified directory entry for a directory or file. The QHFRTVAT API might be faster and more efficient than explicitly opening, reading, and then closing the directory, even if your file system automatically opens and closes the directory during its retrieve operation.

You can use the QHFRTVAT API to determine whether a specific directory entry exists, as well as to get one or more attributes of a specific directory entry. The QHFRTVAT API works with only one directory entry at a time. To retrieve the attributes of several directory entries at once, see Read Directory Entries (QHFRDDR) API and Open Directory (QHFOPNDR) API.

Authorities and Locks

None.

Required Parameter Group

Path name

INPUT; CHAR(*)

The path name of the directory or file to retrieve attributes from. The directory or file must exist, and the path name must have more than one element. You cannot retrieve directory entry attributes for a file system.

Path name length

INPUT; BINARY(4)

The length of the path name, in bytes.

Attribute selection table

INPUT; CHAR(*)

The table specifying the attributes to be returned in the attribute information table. The file system determines which standard and extended attributes you can specify. For descriptions of the standard attributes, see HFS Directory Entry Attributes-. For the format of the table, see HFS Attribute Selection Table.

Length of the attribute selection table

INPUT; BINARY(4)

The length of the attribute selection table, in bytes, or a special value indicating which attributes are returned. Valid values are:

length	The attribute selection table parameter contains the attributes the application wants to make available.
0	No attributes are returned. You can use this to see whether the directory entry exists.
-1	All attributes are returned.

Attribute information table

OUTPUT; CHAR(*)

The directory entry information returned, as specified in the attribute selection table parameter. For the format of the table containing the returned information, see HFS Attribute Information Table.

Length of the attribute information table

INPUT; BINARY(4)

The length of the attribute information table. The table must be large enough to hold all the attributes requested. If it is too small, the retrieve operation fails and no attribute information is returned; however, the length of data returned parameter contains the number of bytes the file system tried to return for that directory entry. The application should increase the attribute information table's length to at least that size and try the request again.

Length of data returned

OUTPUT; BINARY(4)

If the retrieve operation is successful, this field contains the total number of bytes returned in the attribute information table.

If the retrieve operation fails because the attribute information table is too small to hold all of the attributes requested, this field contains the number of bytes required to hold the requested attributes.

Error code

I/O; CHAR(*)

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

Error Messages