| GETDIRENTRIESATTR(2) | System Calls Manual | GETDIRENTRIESATTR(2) |
getdirentriesattr(NOW DEPRECATED) —
get file system attributes for multiple directory
entries
#include
<sys/attr.h>
#include <unistd.h>
#if __LP64__
int
getdirentriesattr(int
fd, struct attrlist *
attrList, void *
attrBuf, size_t
attrBufSize, unsigned int
* count, unsigned int *
basep, unsigned int *
newState, unsigned int
options);
#else
int
getdirentriesattr(int
fd, struct attrlist *
attrList, void *
attrBuf, size_t
attrBufSize, unsigned
long * count, unsigned
long * basep, unsigned
long * newState, unsigned
long options);
#endif
The
getdirentriesattr()
function reads directory entries and returns their attributes (that is,
metadata). You can think of it as a combination of
getdirentries(2) and getattrlist(2).
getdirentriesattr() iterates over the items in a
directory like getdirentries(2), and returns information
about each directory entry like getattrlist(2). Note: when
getdirentriesattr() returns information about a
symbolic link, the information returned is about the link itself, not the
target of the link.
The function reads directory entries from the directory referenced by the file descriptor fd. Attributes of those directory entries are placed into the buffer specified by attrBuf and attrBufSize. The attrList parameter determines what attributes are returned for each entry. The count parameter contains the number of directory entries requested and returned. The basep parameter returns the directory offset in a manner similar to getdirentries(2). The newState parameter allows you to check whether the directory has been modified while you were reading it. The options parameter lets you control specific aspects of the function's behaviour.
The
getdirentriesattr()
function is only supported by certain volume format implementations. For
maximum compatibility, client programs should use high-level APIs (such as
the Carbon File Manager) to access file system attributes. These high-level
APIs include logic to emulate file system attributes on volumes that don't
support getdirentriesattr().
The fd parameter must be a file descriptor that references a directory that you have opened for reading.
The attrList parameter is a pointer to an attrlist structure. You are responsible for filling out all fields of this structure before calling the function. See the discussion of the getattrlist(2) function for a detailed description of this structure. To get an attribute you must set the corresponding bit in the appropriate attrgroup_t field of the attrlist structure. You must not request volume attributes.
The attrBuf and attrBufSize parameters specify a buffer into which the function places attribute values. The attributes for any given directory entry are grouped together and packed in exactly the same way as they are returned from getattrlist(2). These groups are then placed into the buffer, one after another. As each group starts with a leading u_int32_t that contains the overall length of the group, you can step from one group to the next by simply adding this length to your pointer. The sample code (below) shows how to do this. The initial contents of this buffer are ignored.
The count parameter points to an unsigned long or unsigned int variable. You should initialise this variable to be the number of directory entries for which you wish to get attributes. On return, this variable contains the number of directory entries whose attributes have been placed into the attribute buffer. This may be smaller than the number that you requested.
The basep parameter returns the offset of the last directory entry read, in a manner identical to getdirentries(2). You can use this value to reset a directory iteration to a known position using lseek(2). However, since the variable is too small to hold an off_t, you should use lseek(2) to get the directory's current position instead of using this parameter. The initial value of the variable is ignored.
The newState
parameter returns a value that changes if the directory has been modified.
If you're iterating through the directory by making repeated calls to
getdirentriesattr(),
you can compare subsequent values of newState to
determine whether the directory has been modified (and thus restart your
iteration at the beginning). The initial value of the variable is
ignored.
The options
parameter is a bit set that controls the behaviour of
getdirentriesattr().
The following option bits are defined.
getdirentriesattr() to return the
directory entries from disk rather than taking the extra step of looking
at data structures in-memory which may contain changes that haven't been
flushed to disk.
This option allowed for specific performance optimizations for specific clients on older systems. We currently recommend that clients not set this option and that file system implementations ignore it.
It is typical to ask for a combination of common, file, and
directory attributes and then use the value of the
ATTR_CMN_OBJTYPE attribute to parse the resulting
attribute buffer.
As of Mac OS X 10.10,
getdirentriesattr()
is deprecated. It is replaced by getattrlistbulk(2).
Continued use of getdirentriesattr() is strongly
discouraged as comprehensive results are not guaranteed.
Upon successful completion a value of 0 or 1 is returned. The value 0 indicates that the routine completed successfully. The value 1 indicates that the routine completed successfully and has returned the last entry in the directory. On error, a value of -1 is returned and errno is set to indicate the error.
Not all volumes support
getdirentriesattr(). You can test whether a volume
supports getdirentriesattr() by using
getattrlist(2) to get the volume capabilities attribute
ATTR_VOL_CAPABILITIES, and then testing the
VOL_CAP_INT_READDIRATTR flag.
The getdirentriesattr() function has been
undocumented for more than two years. In that time a number of volume format
implementations have been created without a proper specification for the
behaviour of this routine. You may encounter volume format implementations
with slightly different behaviour than what is described here. Your program
is expected to be tolerant of this variant behaviour.
If you're implementing a volume format that supports
getdirentriesattr(), you should be careful to
support the behaviour specified by this document.
If the directory contains a mount point, then
“DIR_MNTSTATUS_MNTPOINT” will be set in the
ATTR_DIR_MOUNTSTATUS for that entry; all other
attributes for that entry, however, will be for the underlying file system
(as opposed to the mounted file system). getattrlist(2)
should be used to get the attributes for the mount point.
A directory which is a firmlink will have the
“SF_FIRMLINK” flag set in its ATTR_CMN_FLAGS attribute entry.
However the attributes returned by
getdirentriesattr() will be those from the firmlink,
not the firmlink's target. To get the attributes of the firmlink's target,
call getattrlist(2) on the firmlink.
getdirentriesattr() will fail if:
ENOTSUP]getdirentriesattr().EBADF]EFAULT]EINVAL]ATTR_BIT_MAP_COUNT.EINVAL]EINVAL]EINVAL]EIO]The following code lists the contents of a directory using
getdirentriesattr(). The listing includes the file
type and creator for files.
#include <assert.h>
#include <stdio.h>
#include <stddef.h>
#include <string.h>
#include <sys/attr.h>
#include <sys/errno.h>
#include <unistd.h>
#include <sys/vnode.h>
#include <stdbool.h>
#include <fcntl.h>
typedef struct attrlist attrlist_t;
struct FInfoAttrBuf {
u_int32_t length;
attrreference_t name;
fsobj_type_t objType;
char finderInfo[32];
u_int32_t dirStatus;
} __attribute__((aligned(4), packed));
typedef struct FInfoAttrBuf FInfoAttrBuf;
enum {
kEntriesPerCall = 10
};
static int FInfoDemo(const char *dirPath)
{
int err;
int junk;
int dirFD;
attrlist_t attrList;
#ifdef __LP64__
unsigned int index;
unsigned int count;
unsigned int junkBaseP;
unsigned int oldState;
unsigned int newState;
#else
unsigned long index;
unsigned long count;
unsigned long junkBaseP;
unsigned long oldState;
unsigned long newState;
#endif
bool oldStateValid;
bool done;
FInfoAttrBuf * thisEntry;
char attrBuf[kEntriesPerCall * (sizeof(FInfoAttrBuf) + 64)];
// attrBuf is big enough for kEntriesPerCall entries, assuming that
// the average name length is less than 64.
memset(&attrList, 0, sizeof(attrList));
attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
attrList.commonattr = ATTR_CMN_NAME
| ATTR_CMN_OBJTYPE
| ATTR_CMN_FNDRINFO;
attrList.dirattr = ATTR_DIR_MOUNTSTATUS;
err = 0;
dirFD = open(dirPath, O_RDONLY, 0);
if (dirFD < 0) {
err = errno;
}
if (err == 0) {
oldStateValid = false;
done = false;
do {
count = kEntriesPerCall;
err = getdirentriesattr(
dirFD,
&attrList,
&attrBuf,
sizeof(attrBuf),
&count,
&junkBaseP,
&newState,
0
);
if (err < 0) {
err = errno;
} else {
done = err;
err = 0;
}
if (err == 0) {
if (oldStateValid) {
if (newState != oldState) {
printf("*** Directory has changed\n");
oldState = newState;
}
} else {
oldState = newState;
oldStateValid = true;
}
thisEntry = (FInfoAttrBuf *) attrBuf;
for (index = 0; index < count; index++) {
switch (thisEntry->objType) {
case VREG:
printf(
"'%4.4s' '%4.4s' ",
&thisEntry->finderInfo[0],
&thisEntry->finderInfo[4]
);
break;
case VDIR:
if (thisEntry->dirStatus & DIR_MNTSTATUS_MNTPOINT)
printf("mount-point ");
else
printf("directory ");
break;
default:
printf(
"objType = %-2d ",
thisEntry->objType
);
break;
}
printf(
"%s\n",
((char *) &thisEntry->name)
+ thisEntry->name.attr_dataoffset
);
// Advance to the next entry.
thisEntry = (FInfoAttrBuf*)((char*)thisEntry + thisEntry->length);
}
}
} while ( err == 0 && ! done );
}
if (dirFD != -1) {
junk = close(dirFD);
assert(junk == 0);
}
return err;
}
A getdirentriesattr() function call
appeared in Darwin 1.3.1 (Mac OS X version 10.0).
| December 15, 2003 | Darwin |