bsd/man/man2/getdirentriesattr.2

   1 .\" Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
   2 .\"
   3 .\" The contents of this file constitute Original Code as defined in and
   4 .\" are subject to the Apple Public Source License Version 1.1 (the
   5 .\" "License").  You may not use this file except in compliance with the
   6 .\" License.  Please obtain a copy of the License at
   7 .\" http://www.apple.com/publicsource and read it before using this file.
   8 .\"
   9 .\" This Original Code and all software distributed under the License are
  10 .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  11 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  12 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  13 .\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  14 .\" License for the specific language governing rights and limitations
  15 .\" under the License.
  16 .\"
  17 .\"     @(#)getdirentriesattr.2
  18 .
  19 .Dd December 15, 2003
  20 .Dt GETDIRENTRIESATTR 2
  21 .Os Darwin
  22 .Sh NAME
  23 .Nm getdirentriesattr
  24 .Nd get file system attributes for multiple directory entries
  25 .Sh SYNOPSIS
  26 .Fd #include <sys/attr.h>
  27 .Fd #include <unistd.h>
  28 .Ft int
  29 .Fn getdirentriesattr "int fd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long * count" "unsigned long * basep" "unsigned long * newState" "unsigned long options"
  30 .
  31 .
  32 .Sh DESCRIPTION
  33 The
  34 .Fn getdirentriesattr
  35 function reads directory entries and returns their attributes (that is, metadata).
  36 You can think of it as a combination of
  37 .Xr getdirentries 2
  38 and
  39 .Xr getattrlist 2 .
  40 The function reads directory entries from the directory referenced by the
  41 file descriptor
  42 .Fa fd .
  43 Attributes of those directory entries are placed into the buffer specified by
  44 .Fa attrBuf
  45 and
  46 .Fa attrBufSize .
  47 The
  48 .Fa attrList
  49 parameter determines what attributes are returned for each entry.
  50 The
  51 .Fa count
  52 parameter contains the number of directory entries requested and returned.
  53 The
  54 .Fa basep
  55 parameter returns the directory offset in a manner similar to
  56 .Xr getdirentries 2 .
  57 The
  58 .Fa newState
  59 parameter allows you to check whether the directory has been modified while
  60 you were reading it.
  61 The
  62 .Fa options
  63 parameter lets you control specific aspects of the function's behaviour.
  64 .Pp
  65 .
  66 The
  67 .Fn getdirentriesattr
  68 function is only supported by certain volume format implementations.
  69 For maximum compatibility, client programs should use high-level APIs
  70 (such as the Carbon File Manager) to access file system attributes.
  71 These high-level APIs include logic to emulate file system attributes
  72 on volumes that don't support
  73 .Fn getdirentriesattr .
  74 .Pp
  75 .
  76 .\" fd parameter
  77 .
  78 The
  79 .Fa fd
  80 parameter must be a file descriptor that references a directory that you have opened for reading.
  81 .Pp
  82 .
  83 .\" attrList parameter
  84 .
  85 The
  86 .Fa attrList
  87 parameter is a pointer to an
  88 .Vt attrlist
  89 structure.
  90 You are responsible for filling out all fields of this structure before calling the function.
  91 See the discussion of the
  92 .Xr getattrlist 2
  93 function for a detailed description of this structure.
  94 To get an attribute you must set the corresponding bit in the appropriate
  95 .Vt attrgroup_t
  96 field of the
  97 .Vt attrlist
  98 structure.
  99 You must not request volume attributes.
 100 .Pp
 101 .
 102 .\" attrBuf and attrBufSize parameters
 103 .
 104 The
 105 .Fa attrBuf
 106 and
 107 .Fa attrBufSize
 108 parameters specify a buffer into which the function places attribute values.
 109 The attributes for any given directory entry are grouped together and
 110 packed in exactly the same way as they are returned from
 111 .Xr getattrlist 2 .
 112 These groups are then placed into the buffer, one after another.
 113 As each group starts with a leading
 114 .Vt unsigned long
 115 that contains the
 116 overall length of the group, you can step from one group to the next
 117 by simply adding this length to your pointer.
 118 The sample code (below) shows how to do this.
 119 The initial contents of this buffer are ignored.
 120 .Pp
 121 .
 122 .\" count parameter
 123 .
 124 The
 125 .Fa count
 126 parameter points to a
 127 .Vt unsigned long
 128 variable.
 129 You should initialise this variable to be the number of directory entries for which
 130 you wish to get attributes.
 131 On return, this variable contains the number of directory entries whose attributes
 132 have been placed into the attribute buffer.
 133 This may be smaller than the number that you requested.
 134 .Pp
 135 .
 136 .\" basep parameter
 137 The
 138 .Fa basep
 139 parameter returns the offset of the last directory entry read, in a
 140 manner identical to
 141 .Xr getdirentries 2 .
 142 You can use this value to reset a directory iteration to a known position
 143 using
 144 .Xr lseek 2 .
 145 The initial value of the variable is ignored.
 146 .Pp
 147 .
 148 .\" newState parameter
 149 .
 150 The
 151 .Fa newState
 152 parameter returns a value that changes if the directory has been modified.
 153 If you're iterating through the directory by making repeated calls to
 154 .Fn getdirentriesattr ,
 155 you can compare subsequent values of
 156 .Fa newState
 157 to determine whether the directory has been modified (and thus restart
 158 your iteration at the beginning).
 159 The initial value of the variable is ignored.
 160 .Pp
 161 .
 162 .\" options parameter
 163 .
 164 The
 165 .Fa options
 166 parameter is a bit set that controls the behaviour of
 167 .Fn getdirentriesattr .
 168 The following option bits are defined.
 169 .
 170 .Bl -tag -width FSOPT_NOINMEMUPDATE
 171 .
 172 .It FSOPT_NOINMEMUPDATE
 173 This tells
 174 .Fn getdirentriesattr
 175 to return the directory entries from disk rather than taking the extra step of looking
 176 at data structures in-memory which may contain changes that haven't been flushed to disk.
 177 .Pp
 178 This option allowed for specific performance optimizations for specific clients on older systems.
 179 We currently recommend that clients not set this option and that file system
 180 implementations ignore it.
 181 .
 182 .El
 183 .Pp
 184 It is typical to ask for a combination of common, file, and directory
 185 attributes and then use the value of the
 186 .Dv ATTR_CMN_OBJTYPE
 187 attribute to parse the resulting attribute buffer.
 188 .
 189 .Sh RETURN VALUES
 190 Upon successful completion a value of 0 or 1 is returned.
 191 The value 0 indicates that the routine completed successfully.
 192 The value 1 indicates that the routine completed successfully and has
 193 returned the last entry in the directory.
 194 On error, a value of -1 is returned and
 195 .Va errno
 196 is set to indicate the error.
 197 .
 198 .Sh COMPATIBILITY
 199 Not all volumes support
 200 .Fn getdirentriesattr .
 201 You can test whether a volume supports
 202 .Fn getdirentriesattr
 203 by using
 204 .Xr getattrlist 2
 205 to get the volume capabilities attribute
 206 .Dv ATTR_VOL_CAPABILITIES ,
 207 and then testing the
 208 .Dv VOL_CAP_INT_READDIRATTR
 209 flag.
 210 .Pp
 211 .
 212 The
 213 .Fn getdirentriesattr
 214 function has been undocumented for more than two years.
 215 In that time a number of volume format implementations have been created without
 216 a proper specification for the behaviour of this routine.
 217 You may encounter volume format implementations with slightly different
 218 behaviour than what is described here.
 219 Your program is expected to be tolerant of this variant behaviour.
 220 .Pp
 221 .
 222 If you're implementing a volume format that supports
 223 .Fn getdirentriesattr ,
 224 you should be careful to support the behaviour specified by this document.
 225 .
 226 .Sh ERRORS
 227 .Fn getdirentriesattr
 228 will fail if:
 229 .Bl -tag -width Er
 230 .
 231 .It Bq Er ENOTSUP
 232 The volume does not support
 233 .Fn getdirentriesattr .
 234 .
 235 .It Bq Er EBADF
 236 .Fa fd
 237 is not a valid file descriptor for a directory open for reading.
 238 .
 239 .It Bq Er EFAULT
 240 .Fa attrList
 241 or
 242 .Em attrBuf
 243 points to an invalid address.
 244 .
 245 .It Bq Er EINVAL
 246 The
 247 .Fa bitmapcount
 248 field of
 249 .Fa attrList
 250 is not
 251 .Dv ATTR_BIT_MAP_COUNT .
 252 .
 253 .It Bq Er EINVAL
 254 You requested an invalid attribute.
 255 .
 256 .It Bq Er EINVAL
 257 You requested volume attributes.
 258 .
 259 .It Bq Er EINVAL
 260 The
 261 .Fa options
 262 parameter contains an invalid flag.
 263 .
 264 .It Bq Er EIO
 265 An I/O error occurred while reading from or writing to the file system.
 266 .El
 267 .Pp
 268 .
 269 .Sh EXAMPLES
 270 .
 271 The following code lists the contents of a directory using
 272 .Fn getdirentriesattr .
 273 The listing includes the file type and creator for files.
 274 .
 275 .Bd -literal
 276 #include <assert.h>
 277 #include <stdio.h>
 278 #include <stddef.h>
 279 #include <string.h>
 280 #include <sys/attr.h>
 281 #include <sys/errno.h>
 282 #include <unistd.h>
 283 #include <sys/vnode.h>
 284 #include <stdbool.h>
 285 #include <fcntl.h>
 286 .Pp
 287 .
 288 typedef struct attrlist attrlist_t;
 289 .Pp
 290 .
 291 struct FInfoAttrBuf {
 292     unsigned long   length;
 293     attrreference_t name;
 294     fsobj_type_t    objType;
 295     char            finderInfo[32];
 296 };
 297 typedef struct FInfoAttrBuf FInfoAttrBuf;
 298 .Pp
 299 .
 300 enum {
 301     kEntriesPerCall = 10
 302 };
 303 .Pp
 304 .
 305 static int FInfoDemo(const char *dirPath)
 306 {
 307     int             err;
 308     int             junk;
 309     int             dirFD;
 310     attrlist_t      attrList;
 311     unsigned long   index;
 312     unsigned long   count;
 313     unsigned long   junkBaseP;
 314     bool            oldStateValid;
 315     unsigned long   oldState;
 316     unsigned long   newState;
 317     bool            done;
 318     FInfoAttrBuf *  thisEntry;
 319     char            attrBuf[kEntriesPerCall * (sizeof(FInfoAttrBuf) + 64)];
 320 .Pp
 321 .
 322     // attrBuf is big enough for kEntriesPerCall entries, assuming that
 323     // the average name length is less than 64.
 324 .Pp
 325 .
 326     memset(&attrList, 0, sizeof(attrList));
 327     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
 328     attrList.commonattr  =    ATTR_CMN_NAME
 329                             | ATTR_CMN_OBJTYPE
 330                             | ATTR_CMN_FNDRINFO;
 331 .Pp
 332
 333     err = 0;
 334     dirFD = open(dirPath, O_RDONLY, 0);
 335     if (dirFD < 0) {
 336         err = errno;
 337     }
 338     if (err == 0) {
 339         oldStateValid = false;
 340         done = false;
 341         do {
 342             count = kEntriesPerCall;
 343 .Pp
 344             err = getdirentriesattr(
 345                 dirFD,
 346                 &attrList,
 347                 &attrBuf,
 348                 sizeof(attrBuf),
 349                 &count,
 350                 &junkBaseP,
 351                 &newState,
 352                 0
 353             );
 354             if (err < 0) {
 355                 err = errno;
 356             } else {
 357                 done = err;
 358                 err = 0;
 359             }
 360 .Pp
 361             if (err == 0) {
 362                 if (oldStateValid) {
 363                     if (newState != oldState) {
 364                         printf("*** Directory has changed\en");
 365                         oldState = newState;
 366                     }
 367                 } else {
 368                     oldState = newState;
 369                     oldStateValid = true;
 370                 }
 371 .Pp
 372                 thisEntry = (FInfoAttrBuf *) attrBuf;
 373 .Pp
 374                 for (index = 0; index < count; index++) {
 375                     switch (thisEntry->objType) {
 376                         case VREG:
 377                             printf(
 378                                 "'%4.4s' '%4.4s' ",
 379                                 &thisEntry->finderInfo[0],
 380                                 &thisEntry->finderInfo[4]
 381                             );
 382                             break;
 383                         case VDIR:
 384                             printf("directory     ");
 385                             break;
 386                         default:
 387                             printf(
 388                                 "objType = %-2d  ",
 389                                 thisEntry->objType
 390                             );
 391                             break;
 392                     }
 393                     printf(
 394                         "%s\en",
 395                         ((char *) &thisEntry->name)
 396                             + thisEntry->name.attr_dataoffset
 397                     );
 398 .Pp
 399                     // Advance to the next entry.
 400 .Pp
 401                     ((char *) thisEntry) += thisEntry->length;
 402                 }
 403             }
 404         } while ( err == 0 && ! done );
 405     }
 406 .Pp
 407     if (dirFD != -1) {
 408         junk = close(dirFD);
 409         assert(junk == 0);
 410     }
 411 .Pp
 412     return err;
 413 }
 414 .Ed
 415 .Pp
 416 .
 417 .Sh SEE ALSO
 418 .
 419 .Xr getattrlist 2 ,
 420 .Xr getdirentries 2 ,
 421 .Xr lseek 2
 422 .
 423 .Sh HISTORY
 424 A
 425 .Fn getdirentriesattr
 426 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
 427 .