531 lines
16 KiB
HTML
531 lines
16 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>HFS Directory Entry Attributes</title>
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!--File Edited November 2001 -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body><!--End Header Records -->
|
|
<!--Java sync-link-->
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
|
</script>
|
|
|
|
<h2>HFS Directory Entry Attributes</h2>
|
|
|
|
<p>Every file and directory in a file system has a corresponding directory
|
|
entry. The <strong>directory entry</strong> 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 <strong>directory entry
|
|
attributes</strong> or simply <strong>attributes.</strong> Each attribute has a
|
|
name and a value.</p>
|
|
|
|
<br>
|
|
|
|
<h3>Standard HFS Directory Entry Attributes</h3>
|
|
|
|
<p>Some directory entry attributes are created automatically when the directory
|
|
entry is created. These attributes are called <strong>standard
|
|
attributes.</strong> 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.</p>
|
|
|
|
<p>The standard attributes for directory entries are:</p>
|
|
|
|
<dl>
|
|
<dt><strong>QNAME</strong></dt>
|
|
|
|
<dd>CHAR(*)
|
|
|
|
<p>The current name of a file or directory.</p>
|
|
|
|
<p>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:</p>
|
|
|
|
<ul>
|
|
<li>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.</li>
|
|
|
|
<li>The Read Directory Entries (QHFRDDR) API always returns the QNAME attribute
|
|
to identify the name of the directory entry.</li>
|
|
|
|
<li>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.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>QFILSIZE</strong></dt>
|
|
|
|
<dd>BINARY(4) UNSIGNED
|
|
|
|
<p>The size of a file's data, in bytes.</p>
|
|
|
|
<p>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.</p>
|
|
</dd>
|
|
|
|
<dt><strong>QALCSIZE</strong></dt>
|
|
|
|
<dd>BINARY(4) UNSIGNED
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
</dd>
|
|
|
|
<dt><strong>QCRTDTTM</strong></dt>
|
|
|
|
<dd>CHAR(13)
|
|
|
|
<p>The date and time of day the file or directory was created, in CYYMMDDHHMMSS
|
|
format.</p>
|
|
|
|
<p>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.</p>
|
|
</dd>
|
|
|
|
<dt><strong>QACCDTTM</strong></dt>
|
|
|
|
<dd>CHAR(13)
|
|
|
|
<p>The date and time of day the file or directory was last accessed, in
|
|
CYYMMDDHHMMSS format.</p>
|
|
|
|
<p>You can specify this attribute on any API call, but your file system might
|
|
ignore it in some APIs.</p>
|
|
</dd>
|
|
|
|
<dt><strong>QWRTDTTM</strong></dt>
|
|
|
|
<dd>CHAR(13)
|
|
|
|
<p>The date and time of day the file or directory was last written to, in
|
|
CYYMMDDHHMMSS format.</p>
|
|
|
|
<p>Changes to this attribute may not be supported by all file systems. Refer to
|
|
the file system's documentation for any restrictions.</p>
|
|
</dd>
|
|
|
|
<dt><strong>QFILATTR</strong></dt>
|
|
|
|
<dd>CHAR(10)
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="10 90" -->
|
|
<tr>
|
|
<td valign="top"><em>0</em></td>
|
|
<td valign="top">No</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>1</em></td>
|
|
<td valign="top">Yes</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The characters and their meanings are:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td valign="top"><em>1</em></td>
|
|
<td valign="top">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.
|
|
|
|
<p>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.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>2</em></td>
|
|
<td valign="top">Hidden file or directory. You can change this attribute by
|
|
using the Change Directory Entry Attributes (QHFCHGAT) API.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>3</em></td>
|
|
<td valign="top">System file or directory. You can change this attribute by
|
|
using the Change Directory Entry Attributes (QHFCHGAT) API.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>4</em></td>
|
|
<td valign="top">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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>5</em></td>
|
|
<td valign="top">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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>6-10</em></td>
|
|
<td valign="top">Reserved. Must be set to blanks.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>QERROR</strong></dt>
|
|
|
|
<dd>CHAR(7)
|
|
|
|
<p>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:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<th align="left" valign="top">Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1F06</td>
|
|
<td valign="top">Directory in use.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1F06</td>
|
|
<td valign="top">Directory in use.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1F08</td>
|
|
<td valign="top">Damaged directory.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1F26</td>
|
|
<td valign="top">File in use.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1F28</td>
|
|
<td valign="top">Damaged file.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1F62</td>
|
|
<td valign="top">Requested function failed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1F71</td>
|
|
<td valign="top">File system unique exception occurred.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>For details about calling the QHFRDDR API from an application, see the <a
|
|
href="qhfrddr.htm">Read Directory Entries (QHFRDDR) API</a>. For details about
|
|
the interface between the QHFRDDR API and a new file system, see the <a href=
|
|
"xhfrddr.htm">Exit Program for Read Directory Entries (QHFRDDR) API</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3><a name="HDRHOTATT">Other HFS Directory Entry Attributes</a></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>An application can also define its own directory entry attributes. These
|
|
attributes are sometimes called <strong>extended attributes.</strong> They
|
|
resemble the extended attributes in the IBM<SUP>(R)</SUP> OS/2<SUP>(R)</SUP> file system and supply
|
|
additional information relevant to the application. The application must define
|
|
the names and values of these attributes.</p>
|
|
|
|
<br>
|
|
<h3><a name="HDRATTTAB">HFS Attribute Information Table</a></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The table consists of zero or more attributes and varies in length.</p>
|
|
|
|
<p>The attribute information table is used by these HFS APIs:</p>
|
|
|
|
<dl>
|
|
<dd>Create Directory (QHFCRTDR)</dd>
|
|
<dd>Retrieve Directory Entry Attributes (QHFRTVAT)</dd>
|
|
<dd>Change Directory Entry Attributes (QHFCHGAT)</dd>
|
|
<dd>Read Directory Entries (QHFRDDR)</dd>
|
|
<dd>Open Stream File (QHFOPNSF)</dd>
|
|
</dl>
|
|
|
|
<p>The attribute information table has three logical parts:</p>
|
|
|
|
<ol>
|
|
<li>The first field specifies the number of attributes defined in the
|
|
table.</li>
|
|
|
|
<li>The next fields give the offsets to the attributes defined in the table.
|
|
There is one offset field for each attribute.</li>
|
|
|
|
<li>Next are groups of fields describing the attributes being defined or
|
|
retrieved. There is one group of descriptive fields for each attribute.</li>
|
|
</ol>
|
|
|
|
<p>The format of the attribute information table is:</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="left" valign="top">Type</th>
|
|
<th align="left" valign="top">Field</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="30%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="70%">The number of attributes defined in
|
|
the table. This is the number of attributes being defined for or retrieved from
|
|
the directory entry.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="2"><em>Offsets:</em></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">The offset to the first attribute</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">The offset to the next attribute, if more than
|
|
one is being defined or retrieved. This field is repeated to list the offset to
|
|
each attribute being defined or retrieved.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="2"><em>Description of the first
|
|
attribute:</em></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of attribute name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of attribute value</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Reserved; currently set to zero</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Attribute name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Attribute value<sup>1</sup></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="2"><em>Description of the next attribute
|
|
(repeated for each attribute after the first):</em></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of attribute name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of attribute value</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Reserved; currently set to zero</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Attribute name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Attribute value<sup>1</sup></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="2"><br>
|
|
<strong>Note:</strong><br>
|
|
<br>
|
|
<sup>1</sup>The attribute value is either a character or the character
|
|
representation of a binary field.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
<h3><a name="HDRATTSEL">HFS Attribute Selection Table</a></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The attribute selection table varies in length.</p>
|
|
|
|
<p>The attribute selection table is used by these HFS APIs:</p>
|
|
|
|
<dl>
|
|
<dd>Open Directory (QHFOPNDR)</dd>
|
|
<dd>Retrieve Directory Entry Attributes (QHFRTVAT)</dd>
|
|
</dl>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The attribute selection table has three logical parts:</p>
|
|
|
|
<ol>
|
|
<li>The first field specifies the number of attributes specified in the
|
|
table.</li>
|
|
|
|
<li>The next fields give the offsets to the attributes specified in the table.
|
|
There is one offset field for each attribute.</li>
|
|
|
|
<li>Next are pairs of fields describing the attributes specified. There is one
|
|
pair of descriptive fields for each attribute.</li>
|
|
</ol>
|
|
|
|
<p>The format of the attribute selection table is:</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="left" valign="top">Type</th>
|
|
<th align="left" valign="top">Field</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="30%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="70%">The number of attributes specified in
|
|
this table</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="2"><em>Offsets:</em></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">The offset to the first attribute</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">The offset to the next attribute, if more than
|
|
one is specified. This field is repeated for each attribute.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="2"><em>Description of the first
|
|
attribute:</em></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of attribute name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Attribute name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="2"><em>Description of the next attribute
|
|
(repeated for each attribute specified):</em></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of attribute name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Attribute name</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"hfs1.htm">Hierarchical File System APIs</a> | <a href="aplist.htm">APIs by
|
|
category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<br>
|
|
</body>
|
|
</html>
|
|
|