xnu-3789.51.2.tar.gz

[apple/xnu.git] / bsd / man / man2 / getdirentriesattr.2

diff --git a/bsd/man/man2/getdirentriesattr.2 b/bsd/man/man2/getdirentriesattr.2
index 9c59e22aee61bcdcd57085e25df9dbf499decb81..6be39ee8726e6fd3a3d4132d88dbb098a85de55c 100644 (file)
--- 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 <sys/attr.h>
 .Fd #include <unistd.h>
+.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 );