X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/91447636331957f3d9b5ca5b508f07c526b0074d..813fb2f63a553c957e917ede5f119b021d6ce391:/bsd/man/man2/getdirentriesattr.2 diff --git a/bsd/man/man2/getdirentriesattr.2 b/bsd/man/man2/getdirentriesattr.2 index 9c59e22ae..6be39ee87 100644 --- a/bsd/man/man2/getdirentriesattr.2 +++ b/bsd/man/man2/getdirentriesattr.2 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2003 Apple Computer, Inc. All rights reserved. +q.\" Copyright (c) 2003 Apple Computer, Inc. All rights reserved. .\" .\" The contents of this file constitute Original Code as defined in and .\" are subject to the Apple Public Source License Version 1.1 (the @@ -20,13 +20,19 @@ .Dt GETDIRENTRIESATTR 2 .Os Darwin .Sh NAME -.Nm getdirentriesattr +.Nm getdirentriesattr(NOW DEPRECATED) .Nd get file system attributes for multiple directory entries .Sh SYNOPSIS .Fd #include .Fd #include +.Pp +.Fd #if __LP64__ +.Ft int +.Fn getdirentriesattr "int fd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned int * count" "unsigned int * basep" "unsigned int * newState" "unsigned int options" +.Fd #else .Ft int .Fn getdirentriesattr "int fd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long * count" "unsigned long * basep" "unsigned long * newState" "unsigned long options" +.Fd #endif . . .Sh DESCRIPTION @@ -37,6 +43,15 @@ You can think of it as a combination of .Xr getdirentries 2 and .Xr getattrlist 2 . +.Fn getdirentriesattr +iterates over the items in a directory like +.Xr getdirentries 2 , +and returns information about each directory entry like +.Xr getattrlist 2 . +Note: when +.Fn getdirentriesattr +returns information about a symbolic link, the information returned is about the link itself, not the target of the link. +.Pp The function reads directory entries from the directory referenced by the file descriptor .Fa fd . @@ -111,7 +126,7 @@ packed in exactly the same way as they are returned from .Xr getattrlist 2 . These groups are then placed into the buffer, one after another. As each group starts with a leading -.Vt unsigned long +.Vt 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. @@ -123,8 +138,10 @@ The initial contents of this buffer are ignored. . The .Fa count -parameter points to a -.Vt unsigned long +parameter points to an +.Vt unsigned long +or +.Vt unsigned int variable. You should initialise this variable to be the number of directory entries for which you wish to get attributes. @@ -142,6 +159,11 @@ manner identical to You can use this value to reset a directory iteration to a known position using .Xr lseek 2 . +However, since the variable is too small to hold an +.Vt off_t , +you should use +.Xr lseek 2 +to get the directory's current position instead of using this parameter. The initial value of the variable is ignored. .Pp . @@ -185,7 +207,14 @@ It is typical to ask for a combination of common, file, and directory attributes and then use the value of the .Dv ATTR_CMN_OBJTYPE attribute to parse the resulting attribute buffer. -. +.Sh NOTES +As of Mac OS X 10.10, +.Fn getdirentriesattr +is deprecated. It is replaced by +.Nm getattrlistbulk(2). +Continued use of +.Fn getdirentriesattr +is strongly discouraged as comprehensive results are not guaranteed. .Sh RETURN VALUES Upon successful completion a value of 0 or 1 is returned. The value 0 indicates that the routine completed successfully. @@ -223,6 +252,16 @@ If you're implementing a volume format that supports .Fn getdirentriesattr , you should be careful to support the behaviour specified by this document. . +.Pp +If the directory contains a mount point, then +.Dv DIR_MNTSTATUS_MNTPOINT +will be set in the +.Dv 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). +.Xr getattrlist 2 +should be used to get the attributes for the mount point. .Sh ERRORS .Fn getdirentriesattr will fail if: @@ -289,11 +328,12 @@ typedef struct attrlist attrlist_t; .Pp . struct FInfoAttrBuf { - unsigned long length; + 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; .Pp . @@ -308,12 +348,20 @@ static int FInfoDemo(const char *dirPath) 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; - bool oldStateValid; unsigned long oldState; unsigned long newState; +#endif + bool oldStateValid; bool done; FInfoAttrBuf * thisEntry; char attrBuf[kEntriesPerCall * (sizeof(FInfoAttrBuf) + 64)]; @@ -328,6 +376,7 @@ static int FInfoDemo(const char *dirPath) attrList.commonattr = ATTR_CMN_NAME | ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO; + attrList.dirattr = ATTR_DIR_MOUNTSTATUS; .Pp err = 0; @@ -381,7 +430,10 @@ static int FInfoDemo(const char *dirPath) ); break; case VDIR: - printf("directory "); + if (thisEntry->dirStatus & DIR_MNTSTATUS_MNTPOINT) + printf("mount-point "); + else + printf("directory "); break; default: printf( @@ -398,7 +450,7 @@ static int FInfoDemo(const char *dirPath) .Pp // Advance to the next entry. .Pp - ((char *) thisEntry) += thisEntry->length; + thisEntry = (FInfoAttrBuf*)((char*)thisEntry + thisEntry->length); } } } while ( err == 0 && ! done );