NAME
ggeettddiirreennttrriieessaattttrr - get file system attributes for multiple directory
entriesSYNOPSIS
##iinncclluuddee <
> ##iinncclluuddee <
int ggeettddiirreennttrriieessaattttrr(int fd, struct attrlist * attrList, void * attrBuf, sizet attrBufSize, unsigned long * count, unsigned long * basep, unsigned long * newState, unsigned long options);> DESCRIPTION
The ggeettddiirreennttrriieessaattttrr() function reads directory entries and returnstheir attributes (that is, metadata). You can think of it as a combina-
tion of getdirentries(2) and getattrlist(2). The function reads direc-
tory entries from the directory referenced by the file descriptor fd.Attributes of those directory entries are placed into the buffer speci-
fied 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 beenmodified while you were reading it. The options parameter lets you con-
trol specific aspects of the function's behaviour.The ggeettddiirreennttrriieessaattttrr() function is only supported by certain volume for-
mat implementations. For maximum compatibility, client programs shoulduse high-level APIs (such as the Carbon File Manager) to access file sys-
tem attributes. These high-level APIs include logic to emulate file sys-
tem attributes on volumes that don't support ggeettddiirreennttrriieessaattttrr(). 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 attrgroupt 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 unsigned long that contains the overall length of the group, you can step from onegroup to the next by simply adding this length to your pointer. The sam-
ple code (below) shows how to do this. The initial contents of this buffer are ignored.The count parameter points to a unsigned long variable. You should ini-
tialise 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 toreset a directory iteration to a known position using lseek(2). The ini-
tial 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 ggeettddiirreennttrriieessaattttrr(), 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 ggeettddiirreennttrriieessaattttrr(). The following option bits are defined.FSOPTNOINMEMUPDATE This tells ggeettddiirreennttrriieessaattttrr() to return the direc-
tory entries from disk rather than taking the extrastep of looking at data structures in-memory which
may contain changes that haven't been flushed to disk.This option allowed for specific performance opti-
mizations 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 ATTRCMNOBJTYPE attribute to parse the resulting attribute buffer.RETURN VALUES
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 entryin the directory. On error, a value of -1 is returned and errno is set
to indicate the error. CCOOMMPPAATTIIBBIILLIITTYYNot all volumes support ggeettddiirreennttrriieessaattttrr(). You can test whether a vol-
ume supports ggeettddiirreennttrriieessaattttrr() by using getattrlist(2) to get the vol-
ume capabilities attribute ATTRVOLCAPABILITIES, and then testing the VOLCAPINTREADDIRATTR flag. The ggeettddiirreennttrriieessaattttrr() 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 ggeettddiirreennttrriieessaattttrr(),you should be careful to support the behaviour specified by this docu-
ment. EERRRROORRSS ggeettddiirreennttrriieessaattttrr() will fail if: [ENOTSUP] The volume does not support ggeettddiirreennttrriieessaattttrr(). [EBADF] fd is not a valid file descriptor for a directory open for reading. [EFAULT] attrList or attrBuf points to an invalid address. [EINVAL] The bitmapcount field of attrList is not ATTRBITMAPCOUNT. [EINVAL] You requested an invalid attribute. [EINVAL] You requested volume attributes. [EINVAL] The options parameter contains an invalid flag. [EIO] An I/O error occurred while reading from or writing to the file system. EEXXAAMMPPLLEESS The following code lists the contents of a directory using ggeettddiirreennttrriieessaattttrr(). The listing includes the file type and creator for files.#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
typedef struct attrlist attrlistt; struct FInfoAttrBuf { unsigned long length; attrreferencet name; fsobjtypet objType; char finderInfo[32]; }; typedef struct FInfoAttrBuf FInfoAttrBuf; enum { kEntriesPerCall = 10 }; static int FInfoDemo(const char *dirPath) { int err; int junk; int dirFD; attrlistt attrList; unsigned long index; unsigned long count; unsigned long junkBaseP; bool oldStateValid; unsigned long oldState; unsigned long newState; 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 = ATTRBITMAPCOUNT;attrList.commonattr = ATTRCMNNAME
| ATTRCMNOBJTYPE | ATTRCMNFNDRINFO; err = 0; dirFD = open(dirPath, ORDONLY, 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: printf("directory "); break; default: printf("objType = %-2d ",
thisEntry->objType
); break; } printf("%s\n",
((char *) &thisEntry->name)
+ thisEntry->name.attrdataoffset
); // Advance to the next entry.((char *) thisEntry) += thisEntry->length;
} } } while ( err == 0 && ! done ); }if (dirFD != -1) {
junk = close(dirFD); assert(junk == 0); } return err; }SEE ALSO
getattrlist(2), getdirentries(2), lseek(2) HISTORY A ggeettddiirreennttrriieessaattttrr() function call appeared in Darwin 1.3.1 (Mac OS X version 10.0). Darwin December 15, 2003 Darwin