bsd/man/man2/searchfs.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 .\"     @(#)searchfs.2
  18 .
  19 .Dd October 13, 2008
  20 .Dt SEARCHFS 2
  21 .Os Darwin
  22 .Sh NAME
  23 .Nm searchfs
  24 .Nd search a volume quickly
  25 .Sh SYNOPSIS
  26 .Fd #include <sys/attr.h>
  27 .Fd #include <unistd.h>
  28 .Ft int
  29 .Fn searchfs "const char* path" "struct fssearchblock* searchBlock" "unsigned int* numMatches" "unsigned int scriptCode" "unsigned int options" "struct searchstate* state"
  30 .
  31 .Sh DESCRIPTION
  32 The
  33 .Fn searchfs
  34 function searches the volume (that is, mounted file system) specified by
  35 .Fa path
  36 for file system objects matching the criteria specified by
  37 .Fa searchBlock ,
  38 .Fa scriptCode ,
  39 and
  40 .Fa options .
  41 The
  42 .Fa numMatches
  43 parameter returns the number of matching file system objects found.
  44 The function also returns attributes of those file system objects in a buffer
  45 specified by
  46 .Fa searchBlock .
  47 The
  48 .Fa searchState
  49 parameter allows you search the volume using multiple calls to
  50 .Fn searchfs ,
  51 resuming the search where it left off.
  52 The routine will only return objects to which you have access (that is, you
  53 have execute permissions on the directories leading to this object from the root).
  54 .Pp
  55 .
  56 .\" path parameter
  57 .
  58 The
  59 .Fa path
  60 parameter must reference a valid file system object on the volume to be searched.
  61 Typically the path is to the volume's root directory.
  62 The entire volume is always searched.
  63 All directories listed in the path name leading to this object must be
  64 searchable.
  65 .Pp
  66 .
  67 .\" searchBlock parameter
  68 .
  69 The
  70 .Fa searchBlock
  71 parameter is a pointer to an
  72 .Vt fssearchblock
  73 structure, as defined by
  74 .Aq Pa sys/attr.h
  75 (shown below).
  76 You are responsible for filling out all fields of this structure before calling the function.
  77 .Bd -literal
  78 struct fssearchblock {
  79     struct attrlist *   returnattrs;
  80     void *              returnbuffer;
  81     size_t              returnbuffersize;
  82     unsigned int        maxmatches;
  83     struct timeval      timelimit;
  84     void *              searchparams1;
  85     size_t              sizeofsearchparams1;
  86     void *              searchparams2;
  87     size_t              sizeofsearchparams2;
  88     struct attrlist     searchattrs;
  89 };
  90 .Ed
  91 .Pp
  92 .
  93 For information about the
  94 .Vt attrlist
  95 structure, see the discussion of
  96 .Xr getattrlist 2 .
  97 .Pp
  98 .
  99 .\" searchBlock elements
 100 .
 101 The fields of the
 102 .Vt fssearchblock
 103 structure are defined as follows.
 104 .Bl -tag -width sizeofsearchparams1
 105 .
 106 .It returnattrs
 107 .Fn searchfs
 108 can return arbitrary attributes of the file system objects that meet the designated
 109 search criteria passed in via
 110 .Vt searchparams1
 111 and
 112 .Vt searchparams2.
 113 This field must point to an
 114 .Vt attrlist
 115 structure that specifies the attributes that you want returned.
 116 To request an attribute you must set the corresponding bit in the appropriate
 117 .Vt attrgroup_t
 118 field of the
 119 .Vt attrlist
 120 structure.
 121 You are responsible for filling out all fields of this structure before calling the function.
 122 You must not request volume attributes.
 123 .
 124 .It returnbuffer
 125 .Fn searchfs
 126 places attributes of the matching file system objects into this returned attributes buffer.
 127 The attributes for any given object are grouped together and
 128 packed in exactly the same way as they would be returned from
 129 .Xr getdirentriesattr 2 .
 130 The initial contents of this buffer are ignored.
 131 .
 132 .It returnbuffersize
 133 Set this field to the size, in bytes, of the buffer pointed to by
 134 .Fa returnbuffer .
 135 .
 136 .It maxmatches
 137 Specifies the maximum number of matches that you want this call to
 138 .Fn searchfs
 139 to return.
 140 .
 141 .It timelimit
 142 Specifies the maximum time that you want this call to
 143 .Fn searchfs
 144 to run.
 145 .Pp
 146 .
 147 If you're implementing a volume format, you should impose your own internal
 148 limit on the duration of this call to prevent a malicious user program
 149 from monopolizing kernel resources.
 150 .Pp
 151 .
 152 .It searchparams1
 153 Specifies the lower bound of the search criteria.
 154 This is discussed in detail below.
 155 You must place attribute values into the buffer in the same
 156 way as they would be returned by
 157 .Xr getattrlist 2 ,
 158 where the
 159 .Fa searchattrs
 160 field determines the exact layout of the attribute values.
 161 .
 162 .It sizeofsearchparams1
 163 Set this field to the size, in bytes, of the buffer pointed to by
 164 .Fa searchparams1 .
 165 .
 166 .It searchparams2
 167 Specifies the upper bound of the search criteria.
 168 This is discussed in detail below.
 169 You must place attribute values into the buffer in the same
 170 way as they would be returned by
 171 .Xr getattrlist 2 ,
 172 where the
 173 .Fa searchattrs
 174 field determines the exact layout of the attribute values.
 175 .
 176 .It sizeofsearchparams2
 177 Set this field to the size, in bytes, of the buffer pointed to by
 178 .Fa searchparams2 .
 179 .
 180 .It searchattrs
 181 Specifies the attributes that you want you use for your search criteria.
 182 You are responsible for filling out all fields of this structure before calling the function.
 183 To search for an attribute you must set the corresponding bit in the appropriate
 184 .Vt attrgroup_t
 185 field of the
 186 .Vt attrlist
 187 structure, and place the appropriate values into the
 188 .Fa searchparam1
 189 and
 190 .Fa searchparam2
 191 buffers.
 192 The attributes specified here determine the format of those buffers.
 193 This is discussed in detail below.
 194 .
 195 .El
 196 .Pp
 197 .
 198 .\" numMatches parameter
 199 .
 200 The
 201 .Fa numMatches
 202 parameter points to an
 203 .Vt unsigned int
 204 variable.
 205 The initial value of this variable is ignored.
 206 On return, this variable contains the number of matching file system objects found.
 207 The is always less than or equal to the
 208 .Fa maxmatches
 209 field of the
 210 .Fa searchBlock
 211 parameter.
 212 The attributes for the matching objects have been placed into the returned attributes buffer.
 213 .Pp
 214 .
 215 .\" scriptCode parameter
 216 .
 217 The
 218 .Fa scriptCode
 219 parameter is currently ignored.
 220 You should always pass in the value 0x08000103, which corresponds to the
 221 UTF-8 text encoding value defined by
 222 .Aq Pa CarbonCore/TextCommon.h .
 223 .Pp
 224 .
 225 .\" options parameter
 226 .
 227 The
 228 .Fa options
 229 parameter is a bit set that controls the behaviour of
 230 .Fn searchfs .
 231 The following option bits are defined.
 232 .
 233 .Bl -tag -width SRCHFS_MATCHPARTIALNAMES
 234 .
 235 .It SRCHFS_START
 236 If this bit is set,
 237 .Fn searchfs
 238 will ignore the
 239 .Fa state
 240 parameter and start a new search.
 241 Otherwise
 242 .Fn searchfs
 243 assumes that
 244 .Fa searchstate
 245 is valid and attempts to resume a previous search based on that state.
 246 .
 247 .It SRCHFS_MATCHPARTIALNAMES
 248 If this bit is set,
 249 .Fn searchfs
 250 will consider substrings to be successful matches when evaluating the
 251 .Dv ATTR_CMN_NAME
 252 attribute.
 253 .
 254 .It SRCHFS_MATCHDIRS
 255 If this bit is set,
 256 .Fn searchfs
 257 will search for directories that match the search criteria.
 258 To get meaningful results you must specify either this bit or
 259 .Dv SRCHFS_MATCHFILES ,
 260 or both.
 261 .
 262 .It SRCHFS_MATCHFILES
 263 If this bit is set,
 264 .Fn searchfs
 265 will search for files that match the search criteria.
 266 To get meaningful results you must specify either this bit or
 267 .Dv SRCHFS_MATCHDIRS ,
 268 or both.
 269 .
 270 .It SRCHFS_SKIPLINKS
 271 If this bit is set,
 272 .Fn searchfs
 273 will only return one reference for a hard linked file, rather than a reference
 274 for each hard link to the file.
 275 .Pp
 276 This option is not recommended for general development.
 277 Its primary client is the
 278 .Xr quotacheck 2
 279 utility.  Note that not all filesystems that support
 280 .Fn searchfs
 281 support this option and may return EINVAL if it is requested.
 282 .Pp
 283 .
 284 This option is privileged (the caller's effective UID must be 0) and cannot
 285 be used if you request the
 286 .Dv ATTR_CMN_NAME
 287 or
 288 .Dv ATTR_CMN_PAROBJID
 289 attributes.
 290 .Pp
 291 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 292 .
 293 .It SRCHFS_SKIPINVISIBLE
 294 If this bit is set,
 295 .Fn searchfs
 296 will not match any invisible file system objects (that is, objects whose
 297 .Dv ATTR_CMN_FNDRINFO
 298 attribute has bit 6 set in the ninth byte) or any objects within
 299 invisible directories.
 300 .Pp
 301 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 302 .
 303 .It SRCHFS_SKIPPACKAGES
 304 If this bit is set,
 305 .Fn searchfs
 306 will not match any file system objects that are inside a package.
 307 A package is defined as a directory whose extension matches one
 308 of the extensions that are configured into the kernel by Launch Services.
 309 .Pp
 310 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 311 .
 312 .It SRCHFS_SKIPINAPPROPRIATE
 313 If this bit is set,
 314 .Fn searchfs
 315 will not match any file system objects that are within an inappropriate directory.
 316 The current list of inappropriate directories contains one item: /System.
 317 .Pp
 318 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 319 .
 320 .It SRCHFS_NEGATEPARAMS
 321 If this bit is set,
 322 .Fn searchfs
 323 will return all the file system objects that do not match the search criteria.
 324 .Pp
 325 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 326 .
 327 .El
 328 .Pp
 329 .
 330 .\" state parameter
 331 .
 332 The
 333 .Fa state
 334 parameter is a pointer to an opaque data structure that
 335 .Fn searchfs
 336 uses to maintain the state of a search between successive calls.
 337 In your first call to
 338 .Fn searchfs ,
 339 you specify the
 340 .Dv SRCHFS_START
 341 flag in the
 342 .Fa options
 343 parameter.
 344 This tells
 345 .Fn searchfs
 346 that the search state is invalid and that it should start a new search.
 347 When this call completes, it may have only returned partial results;
 348 in that case, it will have updated the structure pointed to by
 349 .Fa state .
 350 If you call
 351 .Fn searchfs
 352 again, this time without specifying the
 353 .Dv SRCHFS_START
 354 flag in the
 355 .Fa options
 356 parameter, it will resume the search where it left off, using the search state
 357 that it previously stored in the state structure.
 358 You do not need to explicitly dispose of this state.
 359 .Pp
 360 .
 361 The
 362 .Fn searchfs
 363 function returns significant errors in the followings cases.
 364 .
 365 .Bl -bullet
 366 .
 367 .It
 368 If it has found as many objects as you requested in the
 369 .Fa maxmatches
 370 field of the
 371 .Fa searchBlock
 372 parameter, it will return
 373 .Dv EAGAIN .
 374 .
 375 .It
 376 If there is not enough space in the returned attributes buffer for the first match,
 377 it will return
 378 .Dv ENOBUFS .
 379 You should allocate a larger returned attributes buffer and try again.
 380 .Fa numMatches
 381 will be zero in this case.
 382 .
 383 .It
 384 If the timeout expires it will return
 385 .Dv EAGAIN .
 386 .
 387 .It
 388 If you attempt to resume a search (that is,
 389 .Dv SRCHFS_START
 390 is not specified in the
 391 .Fa options
 392 parameter) and the catalog has changed since the last search,
 393 the function will return
 394 .Dv EBUSY .
 395 You must start your search again from the beginning.
 396 .
 397 .El
 398 .Pp
 399 .
 400 If
 401 .Fn searchfs
 402 returns
 403 .Dv EAGAIN ,
 404 the value in
 405 .Fa numMatches
 406 may be greater than zero.
 407 This is known as a partial result.
 408 You should be sure to process these matches before calling
 409 .Fn searchfs
 410 again.
 411 .
 412 .Sh SEARCH CRITERIA
 413 .
 414 You specify the search criteria using a combination of the
 415 .Fa searchattrs ,
 416 .Fa searchparams1 ,
 417 .Fa sizeofsearchparams1,
 418 .Fa searchparams2 ,
 419 and
 420 .Fa sizeofsearchparams2
 421 fields of the
 422 .Fa searchBlock
 423 parameter, and various flags in the
 424 .Fa options
 425 parameter.
 426 The
 427 .Fa searchattrs
 428 field determines the attributes considered when comparing a file system object to
 429 the search criteria.
 430 You can specify that an attribute should be considered by setting the corresponding
 431 bit in the appropriate
 432 .Vt attrgroup_t
 433 field of the
 434 .Vt attrlist
 435 structure.
 436 See the discussion of
 437 .Xr getattrlist 2
 438 for a detailed description of this structure.
 439 .Pp
 440 .
 441 The
 442 .Fa searchparams1 ,
 443 .Fa sizeofsearchparams1 ,
 444 .Fa searchparams2 ,
 445 and
 446 .Fa sizeofsearchparams2
 447 fields specify the attribute values that must be matched.
 448 The format of each of these buffers is determined by the attributes that you're searching for.
 449 The values are packed in exactly the same way as they would be returned from
 450 .Xr getattrlist 2 ,
 451 including the leading
 452 .Vt u_int32_t
 453 length value.  Note that the size of these buffers must be bounded by SEARCHFS_MAX_SEARCHPARMS bytes,
 454 which is defined in <sys/attr.h>.
 455 .Pp
 456 .
 457 The attribute values in the first and second search buffers form a lower and upper bound for
 458 the search, respectively.
 459 These have different meanings depending on the type of attribute.
 460 .
 461 .Bl -bullet
 462 .
 463 .It
 464 For string attributes (specifically
 465 .Dv ATTR_CMN_NAME ,
 466 the object name), the value in the first search
 467 buffer is significant and the value in the second search buffer is ignored.
 468 The string comparison is either an exact match or a substring match depending on
 469 the
 470 .Dv SRCHFS_MATCHPARTIALNAMES
 471 flag in the
 472 .Fa options
 473 parameter.
 474 .
 475 .It
 476 For structured attributes (specifically
 477 .Dv ATTR_CMN_FNDRINFO ,
 478 the Finder information), the value from the
 479 file system object is masked (logical AND) with the value in the second search buffer and then
 480 compared, byte for byte, against the value in the first search buffer.
 481 If it is equal, the object is a match.
 482 .
 483 .It
 484 For scalar attributes (all other attributes, for example,
 485 .Dv ATTR_CMN_MODTIME ,
 486 the modification date), the values in the first and second search
 487 buffers are literally a lower and upper bound.
 488 An object matches the criteria if its value is greater than or equal to the value in
 489 the first buffer and less than or equal to the value in the second.
 490 .
 491 .El
 492 .
 493 .Sh RETURN VALUES
 494 Upon successful completion, a value of 0 is returned.
 495 This means that the entire volume has been searched and all matches returned.
 496 Otherwise, a value of -1 is returned and
 497 .Va errno
 498 is set to indicate the error.
 499 .Pp
 500 .
 501 See the discussion of the
 502 .Dv EAGAIN ,
 503 .Dv ENOBUFS ,
 504 and
 505 .Dv EBUSY
 506 error codes above.
 507 .
 508 .Sh COMPATIBILITY
 509 Not all volumes support
 510 .Fn searchfs .
 511 You can test whether a volume supports
 512 .Fn searchfs
 513 by using
 514 .Xr getattrlist 2
 515 to get the volume capabilities attribute
 516 .Dv ATTR_VOL_CAPABILITIES ,
 517 and then testing the
 518 .Dv VOL_CAP_INT_SEARCHFS
 519 flag.
 520 .Pp
 521 .
 522 The
 523 .Fn searchfs
 524 function has been undocumented for more than two years.
 525 In that time a number of volume format implementations have been created without
 526 a proper specification for the behaviour of this routine.
 527 You may encounter volume format implementations with slightly different
 528 behaviour than what is described here.
 529 Your program is expected to be tolerant of this variant behaviour.
 530 .Pp
 531 .
 532 If you're implementing a volume format that supports
 533 .Fn searchfs ,
 534 you should be careful to support the behaviour specified by this document.
 535 .Pp
 536 .
 537 A bug in systems prior to Darwin 7.0 (Mac OS X version 10.3) makes searching for the
 538 .Dv ATTR_CMN_BKUPTIME
 539 attribute tricky.
 540 The bug causes the attribute to consume two items in the search attribute buffers, the
 541 first in the proper place and the second between
 542 .Dv ATTR_CMN_FNDRINFO
 543 and
 544 .Dv ATTR_CMN_OWNERID .
 545 .
 546 .Sh ERRORS
 547 .Fn searchfs
 548 will fail if:
 549 .Bl -tag -width Er
 550 .
 551 .It Bq Er ENOTSUP
 552 The volume does not support
 553 .Fn searchfs .
 554 .
 555 .It Bq Er ENOTDIR
 556 A component of the path prefix is not a directory.
 557 .
 558 .It Bq Er ENAMETOOLONG
 559 A component of a path name exceeded
 560 .Dv NAME_MAX
 561 characters, or an entire path name exceeded
 562 .Dv PATH_MAX
 563 characters.
 564 .
 565 .It Bq Er ENOENT
 566 The file system object does not exist.
 567 .
 568 .It Bq Er EACCES
 569 Search permission is denied for a component of the path prefix.
 570 .
 571 .It Bq Er ELOOP
 572 Too many symbolic links were encountered in translating the pathname.
 573 .
 574 .It Bq Er EFAULT
 575 One of the pointer parameters points to an invalid address.
 576 .
 577 .It Bq Er EINVAL
 578 The
 579 .Fa options
 580 parameter contains an invalid flag or sizeofsearchparams1/2 is greater than
 581 SEARCHFS_MAX_SEARCHPARMS (see attr.h).  Additionally, filesystems that do
 582 not support SRCHFS_SKIPLINKS may return EINVAL if this search option
 583 is requested. EINVAL may also be returned if you request attributes for either
 584 searching or to be returned for matched entries if the filesystem does not support
 585 vending that particular attribute.
 586 .
 587 .It Bq Er EAGAIN
 588 The search terminated with partial results, either because
 589 .Fa numMatches
 590 has hit the limit specified by
 591 .Fa maxmatches
 592 or because the timeout expired.
 593 Process the matches returned so far and then call
 594 .Fn searchfs
 595 again to look for more.
 596 .Pp
 597 .
 598 .It Bq Er ENOBUFS
 599 The returned attributes buffer is too small for the first match.
 600 You should allocate a larger returned attributes buffer and try again.
 601 .Fa numMatches
 602 will be zero in this case.
 603 .
 604 .It Bq Er EBUSY
 605 The search could not be resumed because the volume has changed.
 606 .
 607 .It Bq Er EIO
 608 An I/O error occurred while reading from or writing to the file system.
 609 .El
 610 .Pp
 611 .
 612 .Sh CAVEATS
 613
 614 The list of attributes valid for searching and returning to the caller may
 615 be substantially smaller than that of the
 616 .Xr getattrlist 2
 617 system call. See the following lists for the currently available search criteria.
 618 In general, a filesystem that supports
 619 .Fn searchfs
 620 will typically supply per-item attributes for matched objects that are also
 621 supported by the
 622 .Xr getdirentries 2
 623 system call.  This varies from filesystem to filesystem.
 624
 625
 626 .Sh SEARCH ATTRIBUTES
 627
 628 The list of attributes that are valid as search criteria currently includes the
 629 following list of attributes for a particular filesystem object.
 630
 631 .Pp
 632 .
 633 .Bl -item -compact
 634 .It
 635 ATTR_CMN_NAME
 636 .It
 637 ATTR_CMN_OBJID
 638 .It
 639 ATTR_CMN_PAROBJID
 640 .It
 641 ATTR_CMN_CRTIME
 642 .It
 643 ATTR_CMN_MODTIME
 644 .It
 645 ATTR_CMN_CHGTIME
 646 .It
 647 ATTR_CMN_ACCTIME
 648 .It
 649 ATTR_CMN_BKUPTIME
 650 .It
 651 ATTR_CMN_FNDRINFO
 652 .It
 653 ATTR_CMN_BKUPTIME
 654 .It
 655 ATTR_CMN_OWNERID
 656 .It
 657 ATTR_CMN_GRPID
 658 .It
 659 ATTR_CMN_ACCESSMASK
 660 .It
 661 ATTR_CMN_FILEID
 662 .It
 663 ATTR_CMN_PARENTID
 664 .Pp
 665 .
 666 .It
 667 ATTR_DIR_ENTRYCOUNT
 668 .Pp
 669 .
 670 .It
 671 ATTR_FILE_DATALENGTH
 672 .It
 673 ATTR_FILE_DATAALLOCSIZE
 674 .It
 675 ATTR_FILE_RSRCLENGTH
 676 .It
 677 ATTR_FILE_RSRCALLOCSIZE
 678 .El
 679 .
 680
 681 .Sh RETURN ATTRIBUTES
 682
 683 As mentioned above, the list of attributes that are available to be returned to the caller
 684 vary by filesystem, but should include the following attributes, in the following order.
 685 The buffer should be assumed to be packed similar to the output buffer of the
 686 .Xr getattrlist 2
 687 system call. Note that again, this list may be substantially smaller than what is available via
 688 .Xr getattrlist 2
 689
 690 .Pp
 691 .
 692 .Bl -item -compact
 693 .It
 694 ATTR_CMN_NAME
 695 .It
 696 ATTR_CMN_DEVID
 697 .It
 698 ATTR_CMN_FSID
 699 .It
 700 ATTR_CMN_OBJTYPE
 701 .It
 702 ATTR_CMN_OBJTAG
 703 .It
 704 ATTR_CMN_OBJID
 705 .It
 706 ATTR_CMN_OBJPERMANENTID
 707 .It
 708 ATTR_CMN_PAROBJID
 709 .It
 710 ATTR_CMN_SCRIPT
 711 .It
 712 ATTR_CMN_CRTIME
 713 .It
 714 ATTR_CMN_MODTIME
 715 .It
 716 ATTR_CMN_CHGTIME
 717 .It
 718 ATTR_CMN_ACCTIME
 719 .It
 720 ATTR_CMN_BKUPTIME
 721 .It
 722 ATTR_CMN_FNDRINFO
 723 .It
 724 ATTR_CMN_OWNERID
 725 .It
 726 ATTR_CMN_GRPID
 727 .It
 728 ATTR_CMN_ACCESSMASK
 729 .It
 730 ATTR_CMN_FLAGS
 731 .It
 732 ATTR_CMN_USERACCESS
 733 .It
 734 ATTR_CMN_FILEID
 735 .It
 736 ATTR_CMN_PARENTID
 737 .Pp
 738 .
 739 .It
 740 ATTR_DIR_LINKCOUNT
 741 .It
 742 ATTR_DIR_ENTRYCOUNT
 743 .It
 744 ATTR_DIR_MOUNTSTATUS
 745 .Pp
 746 .
 747 .It
 748 ATTR_FILE_LINKCOUNT
 749 .It
 750 ATTR_FILE_TOTALSIZE
 751 .It
 752 ATTR_FILE_ALLOCSIZE
 753 .It
 754 ATTR_FILE_IOBLOCKSIZE
 755 .It
 756 ATTR_FILE_CLUMPSIZE
 757 .It
 758 ATTR_FILE_DEVTYPE
 759 .It
 760 ATTR_FILE_DATALENGTH
 761 .It
 762 ATTR_FILE_DATAALLOCSIZE
 763 .It
 764 ATTR_FILE_RSRCLENGTH
 765 .It
 766 ATTR_FILE_RSRCALLOCSIZE
 767 .El
 768 .
 769
 770
 771 .Sh EXAMPLES
 772 .
 773 The following code searches a volume for files of the specified type and creator.
 774 .
 775 .Bd -literal
 776 #include <assert.h>
 777 #include <stdio.h>
 778 #include <stddef.h>
 779 #include <string.h>
 780 #include <sys/attr.h>
 781 #include <sys/errno.h>
 782 #include <unistd.h>
 783 .Pp
 784 .
 785 typedef struct attrlist         attrlist_t;
 786 typedef struct fssearchblock    fssearchblock_t;
 787 typedef struct searchstate      searchstate_t;
 788 .Pp
 789 .
 790 struct SearchAttrBuf {
 791     u_int32_t       length;
 792     char            finderInfo[32];
 793 };
 794 typedef struct SearchAttrBuf SearchAttrBuf;
 795 .Pp
 796 .
 797 struct ResultAttrBuf {
 798     u_int32_t       length;
 799     attrreference_t name;
 800     fsobj_id_t      parObjID;
 801 };
 802 typedef struct ResultAttrBuf ResultAttrBuf;
 803 .Pp
 804 .
 805 enum {
 806     kMatchesPerCall = 16
 807 };
 808 .Pp
 809 .
 810 static int SearchFSDemo(
 811     const char *volPath,
 812     const char *type,
 813     const char *creator
 814 )
 815 {
 816     int             err;
 817     fssearchblock_t searchBlock;
 818     SearchAttrBuf   lower;
 819     SearchAttrBuf   upper;
 820     static const unsigned char kAllOnes[4] = { 0xFF, 0xFF, 0xFF, 0xFF };
 821     unsigned int    matchCount;
 822     unsigned int    matchIndex;
 823     unsigned int    options;
 824     searchstate_t   state;
 825     ResultAttrBuf * thisEntry;
 826     attrlist_t      returnAttrList;
 827     char            resultAttrBuf[  kMatchesPerCall
 828                                   * (sizeof(ResultAttrBuf) + 64)];
 829 .Pp
 830 .
 831     // resultAttrBuf is big enough for kMatchesPerCall entries,
 832     // assuming that the average name length is less than 64.
 833 .Pp
 834 .
 835     assert(strlen(type)    == 4);
 836     assert(strlen(creator) == 4);
 837 .Pp
 838
 839     memset(&searchBlock, 0, sizeof(searchBlock));
 840     searchBlock.searchattrs.bitmapcount = ATTR_BIT_MAP_COUNT;
 841     searchBlock.searchattrs.commonattr  = ATTR_CMN_FNDRINFO;
 842 .Pp
 843
 844     memset(&lower, 0, sizeof(lower));
 845     memset(&upper, 0, sizeof(upper));
 846     lower.length = sizeof(lower);
 847     upper.length = sizeof(upper);
 848     memcpy(&lower.finderInfo[0], type,     4);
 849     memcpy(&lower.finderInfo[4], creator,  4);
 850     memcpy(&upper.finderInfo[0], kAllOnes, 4);
 851     memcpy(&upper.finderInfo[4], kAllOnes, 4);
 852     searchBlock.searchparams1       = &lower;
 853     searchBlock.sizeofsearchparams1 = sizeof(lower);
 854     searchBlock.searchparams2       = &upper;
 855     searchBlock.sizeofsearchparams2 = sizeof(lower);
 856 .Pp
 857
 858     searchBlock.timelimit.tv_sec  = 0;
 859     searchBlock.timelimit.tv_usec = 100 * 1000;
 860 .Pp
 861
 862     searchBlock.maxmatches = kMatchesPerCall;
 863 .Pp
 864
 865     memset(&returnAttrList, 0, sizeof(returnAttrList));
 866     returnAttrList.bitmapcount = ATTR_BIT_MAP_COUNT;
 867     returnAttrList.commonattr  = ATTR_CMN_NAME | ATTR_CMN_PAROBJID;
 868 .Pp
 869 .
 870     searchBlock.returnattrs = &returnAttrList;
 871     searchBlock.returnbuffer = resultAttrBuf;
 872     searchBlock.returnbuffersize = sizeof(resultAttrBuf);
 873 .Pp
 874
 875     options = SRCHFS_START | SRCHFS_MATCHFILES;
 876 .Pp
 877
 878     do {
 879         err = searchfs(
 880             volPath,
 881             &searchBlock,
 882             &matchCount,
 883             0x08000103,
 884             options,
 885             &state
 886         );
 887         if (err != 0) {
 888             err = errno;
 889         }
 890         if ( (err == 0) || (err == EAGAIN) ) {
 891             thisEntry = (ResultAttrBuf *) resultAttrBuf;
 892 .Pp
 893
 894             for (matchIndex = 0; matchIndex < matchCount; matchIndex++) {
 895                 printf("%08x ", thisEntry->parObjID.fid_objno);
 896                 printf(
 897                     "%s\en",
 898                     ((char *) &thisEntry->name)
 899                         + thisEntry->name.attr_dataoffset
 900                 );
 901 .
 902                 // Advance to the next entry.
 903 .
 904                 ((char *) thisEntry) += thisEntry->length;
 905             }
 906         }
 907 .Pp
 908
 909         options &= ~SRCHFS_START;
 910     } while (err == EAGAIN);
 911 .Pp
 912
 913     return err;
 914 }
 915 .Ed
 916 .
 917 .Sh SEE ALSO
 918 .
 919 .Xr getattrlist 2
 920 .
 921 .Sh HISTORY
 922 A
 923 .Fn searchfs
 924 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
 925 .