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