HFS Directory Entry Attributes

Every file and directory in a file system has a corresponding directory entry. The directory entry is created automatically by the file system when the stream file is opened or the directory is created. It is stored in the directory in which the file or directory is located and contains descriptive information, such as the item's creation date and whether it is a file or directory. The items of information are called directory entry attributes or simply attributes. Each attribute has a name and a value.

Standard HFS directory entry attributes

Some directory entry attributes are created automatically when the directory entry is created. These attributes are called standard attributes. Their names start with the letter Q so you can identify them easily. Each file system determines which standard attributes you can specify when working with directory entries.

The standard attributes for directory entries are:

QNAME

CHAR(*)

The current name of a file or directory.

Do not specify this attribute in the attribute information table or attribute selection table used with some APIs. The name is either already specified or disallowed, as follows:

• When you create a directory (or open a stream file) and when you retrieve directory entry attributes, the object's name is already specified in the API's path name parameter.
• The Read Directory Entries (QHFRDDR) API always returns the QNAME attribute to identify the name of the directory entry.
• You cannot use the Change Directory Entry Attributes (QHFCHGAT) AP I to change this attribute and rename the object. You must use the Rename Directory (QHFRNMDR) or Rename Stream File (QHFRNMSF) API to rename the object.

QFILSIZE

BINARY(4) UNSIGNED

The size of a file's data, in bytes.

This attribute applies only to files. Thus, for directories, it has a value of zero. If you specify it for a directory, it is ignored.

QALCSIZE

BINARY(4) UNSIGNED

For a file, the allocated size of the file in bytes. The allocated size is the amount of space the file system actually uses to store the file.

This attribute applies only to files. Thus, for directories, it has a value of zero. If you specify it for a directory, it is ignored.

QCRTDTTM

CHAR(13)

The date and time of day the file or directory was created, in CYYMMDDHHMMSS format.

You cannot specify this attribute when creating a directory or file. However, you can specify it on calls to the Retrieve Directory Entry Attributes (QHFRTVAT) and Change Directory Entry Attributes (QHFCHGAT) APIs.

QACCDTTM

CHAR(13)

The date and time of day the file or directory was last accessed, in CYYMMDDHHMMSS format.

You can specify this attribute on any API call, but your file system might ignore it in some APIs.

QWRTDTTM

CHAR(13)

The date and time of day the file or directory was last written to, in CYYMMDDHHMMSS format.

Changes to this attribute may not be supported by all file systems. See the file system's documentation for any restrictions.

QFILATTR

CHAR(10)

The type of item the directory entry is for. You can specify this attribute on any API call, except as noted in the following list of character descriptions.

Each character in the QFILATTR attribute has a specific meaning. Characters 6-10 must be set to blanks. Characters 1-5 must have a value of either 0 or 1:

0	No
1	Yes

The characters and their meanings are:

1	Read-only file. This applies only to files; it is ignored for directories. You can change it only by using the Change Directory Entry Attributes (QHFCHGAT) API. When a file has this attribute, the file cannot be accessed in write mode. It cannot be opened with write or read/write access, it cannot be the target file in a copy stream file operation, and it cannot be deleted.
2	Hidden file or directory. You can change this attribute by using the Change Directory Entry Attributes (QHFCHGAT) API.
3	System file or directory. You can change this attribute by using the Change Directory Entry Attributes (QHFCHGAT) API.
4	Entry is a directory (not a file). You cannot change this attribute. If you specify it on the Change Directory Entry Attributes (QHFCHGAT) API, it is ignored.
5	Changed file. This applies only to files. It indicates that the file has been changed and is usually used to determine when a file needs to be moved to safe, permanent storage. It is set to Yes when the file is created or written to. You can set it to No only by using the Change Directory Entry Attributes (QHFCHGAT) API.
6-10	Reserved. Must be set to blanks.

QERROR

CHAR(7)

A special attribute that can be returned in the attribute data buffer by the Read Directory (QHFRDDR) API when it encounters an error in retrieving the attributes of a directory entry. These values can be returned:

Message ID	Error Message Text
CPF1F06	Directory in use.
CPF1F06	Directory in use.
CPF1F08	Damaged directory.
CPF1F26	File in use.
CPF1F28	Damaged file.
CPF1F62	Requested function failed.
CPF1F71	File system unique exception occurred.

For details about calling the QHFRDDR API from an application, see the Read Directory Entries (QHFRDDR) API. For details about the interface between the QHFRDDR API and a new file system, see the Exit Program for Read Directory Entries (QHFRDDR) API.

Other HFS directory entry attributes

File systems can define their own unique attributes for files and directories in addition to the standard ones. The file system's documentation defines the attributes' names and values, and explains how to access and use them.

An application can also define its own directory entry attributes. These attributes are sometimes called extended attributes. They resemble the extended attributes in the IBM^® OS/2^® file system and supply additional information relevant to the application. The application must define the names and values of these attributes.

Hfs attribute information table

The HFS APIs use a common attribute information table to pass all types of directory entry attributes between the application and the file system. Thus, the information is returned in the same format regardless of which file system the application is using. Different file systems can use different attributes, so the contents of the table can vary from one file system to another.

The file system must use the attribute information table when communicating with the application. It must accept and return attributes in that format. For its own use, however, the file system can store the attribute information in whatever format is most convenient.

The table consists of zero or more attributes and varies in length.

The attribute information table is used by these HFS APIs:

• Create Directory (QHFCRTDR)
• Retrieve Directory Entry Attributes (QHFRTVAT)
• Change Directory Entry Attributes (QHFCHGAT)
• Read Directory Entries (QHFRDDR)
• Open Stream File (QHFOPNSF)

The attribute information table has three logical parts:

1. The first field specifies the number of attributes defined in the table.
2. The next fields give the offsets to the attributes defined in the table. There is one offset field for each attribute.
3. Next are groups of fields describing the attributes being defined or retrieved. There is one group of descriptive fields for each attribute.

The format of the attribute information table is:

Hfs attribute selection table

The HFS APIs use a common attribute selection table to choose which directory entry attributes to retrieve or to make available for reading. The attribute selection table specifies which attributes the file system should return to the application. The file system must read the table, determine which attributes have been selected, and return those attributes to the application in the attribute information table.

The attribute selection table varies in length.

The attribute selection table is used by these HFS APIs:

• Open Directory (QHFOPNDR)
• Retrieve Directory Entry Attributes (QHFRTVAT)

The attribute selection table contains an entry for every attribute the application selects. If a selected attribute does not exist for the directory entry, no error is signaled. The attribute name is returned, and the length of the attribute value is zero.

The attribute selection table has three logical parts:

1. The first field specifies the number of attributes specified in the table.
2. The next fields give the offsets to the attributes specified in the table. There is one offset field for each attribute.
3. Next are pairs of fields describing the attributes specified. There is one pair of descriptive fields for each attribute.

The format of the attribute selection table is:

[ Back to top | Hierarchical File System APIs | APIs by category ]