IFS - Extended Attributes
| Installable File Systems for OS/2 |
|---|
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
Extended attributes (EAs) are a mechanism whereby an application can attach information to a file system object (directories or files) describing the object to another application, to the operating system, or to the FSD managing that object.
EAs associated with a file object are not part of a file object's data, but are maintained separately and managed by the file system that manages that object.
Each extended attribute consists of a name and a value. An EA name consists of ASCII text, chosen by the application developer, that is used to identify a particular EA. EA names are restricted to the same character set as a filename. An EA value consists of arbitrary data, that is, data of any form. Because of this OS/2 does not check data that is associated with an EA.
So that EA data is understandable to other applications, conventions have been established for:
- Naming EAs
- Indicating the type of data contained in EAs
In addition, a set of standard EAs (SEAs) have been defined. SEAs define a common set of information that can be associated with most files (for example, file type and file purpose). Through SEAs, many applications can access the same, useful information associated with files.
Applications are not limited to using SEAs to associate information with files. They may define their own application-specific extended attributes. Applications define and associate extended attributes with a file object through file system function calls.
See the OS/2 Version 2.0 Programming Guide for a complete description of EA naming conventions and data types and standard extended attributes. See also the OS/2 Version 2.0 Control Program Programming Reference for a complete description of the file system function calls.
EAs may be viewed as a property list attached to file objects. The services for manipulating EAs are: add/replace a series of name/value pairs, return name/value pairs given a list of names, and return the total set of EAs.
There are two formats for EAs as passed to OS/2 Version 2.0 API: Full EAs (FEA) and Get EAs (GEA).
FEAs
FEAs are complete name/value pairs. In order to simplify and speed up scanning and processing of these names, they are represented as length-preceded data. FEAs are defined as follows:
struct FEA {
unsigned char fEA; /* byte of flags */
unsigned char cbName; /* length of name */
unsigned short cbValue; /* length of value */
unsigned char szName[]; /* ASCIIZ name */
unsigned char aValue[]; /* free format value */
};
There is only one flag defined in fEA. That is 0x80 which is fNeedEA. Setting the flag marks this EA as needed for the proper operation on the file to which it is associated. Setting this bit has implications for access to this file by old applications, so it should not be set arbitrarily.
If a file has one or more NEED EAs, old applications are not allowed to open the file. For DOS mode applications to access files with NEED EAs, they must have the EA bit set in their exe header. For OS/2 mode, only applications with the NEWFILES bit set in the exe header may open files with NEED EAs.
Programs that change EAs should preserve the NEED bit in the EAs unless there is a good reason to change it.
The name length does not include the trailing NUL. The maximum EA name length is 255 bytes. The minimum EA name length is 1 byte. The characters that form the name are legal filename characters. Wildcard characters are not allowed. EA names are case-insensitive and should be uppercased. The FSD should call FSH_CHECKEANAME and FSH_UPPERCASE for each EA name it receives to check for invalid characters and correct length, and to uppercase it.
The FSD may not modify the flags.
A list of FEAs is a packed set of FEA structures preceded by a length of the list (including the length itself) as indicated in the following structure:
struct FEAList {
unsigned long cbList; /* length of list */
struct FEA list[]; /* packed set of FEAs */
};
FEA lists are used for adding, deleting, or changing EAs. A particular FSD may store the EAs in whatever format it desires. Certain EAs may be stored to optimize retrieval.
GEAs
A GEA is an attribute name. Its format is:
struct GEA {
unsigned char cbName; /* length of name */
unsigned char szName[]; /* ASCIIZ name */
};
The name length does not include the trailing NUL.
A list of GEAs is a packed set of GEA structures preceded by a length of the list (including the length itself) as indicated in the following structure:
struct GEAList {
unsigned long cbList; /* length of list */
struct GEA list[]; /* packed set of GEAs */
};
GEA lists are used for retrieving the values for a particular set of attributes. A GEA list is used as input only.
Name lengths of 0 are illegal and are considered in error. A value length of 0 has special meaning. Setting an EA with a value length of 0 will cause that attribute to be deleted (if possible). Upon retrieval, a value length of 0 indicates that the attribute is not present.
Setting attributes contained in an FEA list does not treat the entire FEA list as atomic. If an error occurs before the entire list of EAs has been set, all, some, or none of them may actually remain set on the file. No program should depend on an EA set being atomic to force EAs to be consistent with each other. Programs must be careful not to depend on atomicity, since a given file system may provide it.
Manipulation of extended attributes is associated with access permission to the associated file or directory. For querying and setting file EAs, read and write/read permission, respectively, for the associated file is required. No directory create or delete may occur while querying EAs for that directory.
For handle-based operations on extended attributes, access permission is controlled by the sharing/access mode of the associated file. If the file is open for read, querying the extended attributes is allowed. If the file is open for write, setting the extended attributes is allowed. These operations are DosQFileInfo and DosSetFileInfo.
For path-based manipulation of extended attributes, the associated file or directory will be added to the sharing set for the duration of the call. The requested access permission for setting EAs is write/deny-all and for querying EAs is read/deny-write. The path-based API are DosQPathInfo, DosSetPathInfo, and DosFindFirst2/DosFindNext.
For create-only operations of extended attributes, the extended attributes are set without examining the sharing/access mode of the associated file/directory. These operations are DosOpen2 and DosMkDir2.
The routing of EA requests is accomplished by the IFS routing mechanism. EA requests that apply to names are routed to the FSD attached to the specified drive. Those requests that apply to a handle (file or directory) are routed to the FSD attached to the handle. No interpretation of either FEA lists nor GEA lists is performed by the IFS router.
- Note
- It is the responsibility of each FSD to provide support for EAs.
It is expected that some FSDs will be unable to store EAs; for example, UNIX and MVS compatible file systems.
Note: The FAT FSD implementation will provide for the complete implementation of EAs. There will be no special EAs for the FAT FSD.
All EA manipulation is performed using the following structure: The relevance of each field is described within each API.
struct EAOP {
struct GEAList far * fpGEAList; /* GEA set */
struct FEAList far * fpFEAList; /* FEA set */
unsigned long offError; /* offset of FEA err */
};
See the descriptions of the file system function calls in OS/2 Version 2.0 Control Program Programming Reference for the relevance of each field.
In OS/2 Version 2.0, values of cbList greater than (64K-1) are not allowed. This is an implementation-defined limitation which may be raised in the future. Because this limit may change, programs should avoid enumerating the list of all EAs, but instead manipulate only EAs that they know about. For operations such as copying, the DosCopy API should be used. If enumeration is necessary, the DosEnumAttribute API should be used.
A special category of attributes, called create-only attributes, is defined as the set of extended attributes that a file system may only allow to be set at creation time. (Such attributes may be used to control file allocation and structure configuration.) File systems are expected to allow create-only attributes to be set at any time from when the object is created to when it is first modified, that is, data is written into a file or an entry added to a directory. Programs that copy objects should copy all of the EAs for an object before otherwise modifying it in order to assure that any create-only attributes from the source are properly applied to the target. The DosCopy API is the preferred method of copying files or directories.