|
Unlike most of the other file system C functions, fs_rewind_attr_dir() doesn't set errno.
|
| The Storage Kit Table of Contents | The Storage Kit Index |
Declared in: be/kernel/fs_attr.h
Library: libroot.so
The BeOS supports a powerful system of attributes that can be attached to files. Once these attributes are attached, you can query the file system for attributes whose values match certain specifications; this is discussed in the section on the fs_query functions, and in the section on the BQuery class.
Before you can perform these queries, however, you need to attach attributes to the file. There are two ways to do this. The typical mechanism for attaching attributes to files is through the BNode class, which provides a convenient interface for doing this. This section discusses the lower-level way to do this, by calling the C fs_attr functions directly.
This collection of functions also lets you look at the attributes attached to a file, get their names and sizes, and read their contents.
The fs_attr functions make use of directory pointers (DIR *). While these are true directory pointers, the data they hold aren't useful outside the fs_attr API; they're basically magic cookies that represent the file's attribute directory. Likewise, the dirent structures returned by some of these functions are also not useful outside this API.
Before dropping straight into the reference on the fs_attr API, let's have a look at a simple sample of how to use some of its features. The sample code fragment below opens the attribute directory for a file named /boot/home/dirtylaundry and scans through all the attributes in the file, fetching their names and values.
DIR *d;
dirent_t *ent;
attr_info info;
int fd;
char *buffer;
d = fs_open_attr_dir("/boot/home/dirtylaundry");
if (d) {
while (ent = fs_read_attr_dir(d)) {
fd = open("/boot/home/dirtylaundry", O_RDONLY);
fs_stat_attr(fd, ent->d_name, &info);
buffer = (char *) malloc((size_t) info.size);
if (buffer)
fs_read_attr(fd, ent->d_name, info.type, 0, buffer,
info.size);
...
close(fd);
fs_close_attr_dir(d);
}
This snippet begins by opening the attribute directory for the file, using the fs_open_attr_dir() function. If this is successful, it returns a pointer to a directory that contains the list of attributes. A while loop is used to read into ent each attribute from the attribute directory by calling fs_read_attr_dir(). The information this call provides includes the size and type of the attribute, as well as its name.
Once we know the name of the attribute, we can obtain the type and size of the attribute by calling fs_stat_attr(); now we have all the information needed to get the value of the attribute. After allocating a buffer to contain the value of the attribute, we pass the attribute's name (ent->d_name), and the type and size (info.type and info.size) into the fs_read_attr() function. The value of the attribute is stored in the buffer we specify.
This sample skimps a bit on error handling; you'll do better, of course.
|
Closes the specified attribute directory. You should pass into this function the pointer returned when you called fs_open_attr_dir() or fs_fopen_attr_dir().
If successful, this function returns 0; otherwise it returns -1 and sets errno to a descriptive code.
|
Opens the attribute directory for the file specified by pathname or file descriptor.
The attribute directory for a file contains a list of the attributes that are attached to the file. Once the attribute directory is open, you can use the fs_read_attr_dir() function to find out which attributes are present.
If the directory is opened successfully, a pointer to the directory structure is returned. This pointer should be passed to the other fs_attr functions to read entries from the attribute directory, as well as to close the directory when you're finished with it.
If an error occurs while opening the attribute directory, this function returns NULL and sets errno to one of the values listed below.
|
Reads the attribute of the type and name specified by type and attribute from the file descriptor fd. The attribute's data is read starting at the offset pos and stored in the buffer. count specifies the maximum number of bytes to be read.
The type can be any of the standard BeOS type definitions, such as B_STRING_TYPE. See the header file be/support/TypeConstants.h for a complete list of these types. Note that the type of the attribute is a hint only; there's no reason you can't read a B_STRING_TYPE attribute as an integer (except that the data would probably not make any sense if you did).
If the attribute is read successfully, fs_read_attr() returns the actual number of bytes of data read from the attribute into the buffer. If an error occurs, this function returns -1 sets errno to an appropriate value.
|
Reads the current attribute from the specified attribute directory, and bumps the dirp so it points to the next attribute. The dirp pointer that you pass to this function should have been retrieved through a previous call to fs_open_attr_dir() or fs_fopen_attr_dir().
A pointer to a dirent structure is returned. This structure contains information about the attribute. Do not dispose of or alter the data contained by this pointer; it belongs to the operating system.
Once a file's attribute directory has been opened, you can loop over this function to iteratively retrieve the names of all the attributes in the file. An attribute's name is recorded in the d_name field of the dirent structure; see the example in "An Example" on page193.
This function doesn't let you get the type or value of an attribute. For that, use fs_stat_attr().
If you're looking for files that have a particular value for one or more attributes, however, you should try using the fs_query functions, which allow you to more easily establish complex search operations on the values of one or more attributes.
If an error occurs (including reaching the end of the directory), this function returns NULL.
|
Deletes the named attribute from the file given by the file descriptor fd.
If the function is successful, fs_remove_attr() returns 0. Otherwise, it returns -1 and sets errno to an appropriate value.
|
Rewinds the attribute directory to the beginning. This lets you start over again at the top of a file's attribute directory and read your way down toward the bottom.
Returns a result code specifying whether or not the operation was successful.
|
RETURN CODES
|
Returns, in the attr_info structure pointed to by info, the type and size of the specified attribute on the file whose descriptor is specified by fd.
The attr_info structure is defined as follows:
typedef struct attr_info
{
uint32 type;
off_t size;
}
type contains a code defining the format of the data contained by the attribute; standard values for this field are defined in the be/support/TypeConstants.h header file.
size specifies the size of the data the attribute contains.
Upon success, the function returns 0. Otherwise, it returns -1 and sets errno to an appropriate value.
|
Sets the value of the named attribute to the data in the specified buffer. The data's type is specified by type and should be one of the codes defined in be/support/TypeConstants.h. The length of the data to be written is specified by count.
|
If the attribute already has a value, this function wholly replaces that value with the new data—even if the new data is smaller than the existing data.
|
Upon success, the function returns the number of bytes that were actually written. Otherwise, it returns -1 and sets errno to an appropriate value.
| The Storage Kit Table of Contents | The Storage Kit Index |
Copyright © 2000 Be, Inc. All rights reserved..
