bsd/man/man2/getattrlist.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 .\"     @(#)getattrlist.2
  18 .
  19 .Dd October 14, 2004
  20 .Dt GETATTRLIST 2
  21 .Os Darwin
  22 .Sh NAME
  23 .Nm getattrlist
  24 .Nd get file system attributes
  25 .Sh SYNOPSIS
  26 .Fd #include <sys/attr.h>
  27 .Fd #include <unistd.h>
  28 .Ft int
  29 .Fn getattrlist "const char* path" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"
  30 .
  31 .Sh DESCRIPTION
  32 The
  33 .Fn getattrlist
  34 function returns attributes (that is, metadata) of file system objects.
  35 You can think of
  36 .Fn getattrlist
  37 as a seriously enhanced version of
  38 .Xr stat 2 .
  39 The function returns attributes about the file system object specified by
  40 .Fa path
  41 in the buffer specified by
  42 .Fa attrBuf
  43 and
  44 .Fa attrBufSize .
  45 The
  46 .Fa attrList
  47 parameter determines what attributes are returned.
  48 The
  49 .Fa options
  50 parameter lets you control specific aspects of the function's behavior.
  51 .Pp
  52 .
  53 The
  54 .Fn getattrlist
  55 function is only supported by certain volume format implementations.
  56 For maximum compatibility, client programs should use high-level APIs
  57 (such as the Carbon File Manager) to access file system attributes.
  58 These high-level APIs include logic to emulate file system attributes
  59 on volumes that don't support
  60 .Fn getattrlist .
  61 .Pp
  62 .
  63 Not all volumes support all attributes.
  64 See the discussion of
  65 .Dv ATTR_VOL_ATTRIBUTES
  66 for a discussion of how to determine whether a particular volume supports a
  67 particular attribute.
  68 .Pp
  69 Furthermore, you should only request the attributes that you need.
  70 Some attributes are expensive to calculate on some volume formats.
  71 For example,
  72 .Dv ATTR_DIR_ENTRYCOUNT
  73 is usually expensive to calculate on non-HFS [Plus] volumes.
  74 If you don't need a particular attribute, you should not ask for it.
  75 .Pp
  76 .
  77 .\" path parameter
  78 .
  79 The
  80 .Fa path
  81 parameter must reference a valid file system object.
  82 Read, write or execute permission of the object itself is not required, but
  83 all directories listed in the path name leading to the object must be
  84 searchable.
  85 .Pp
  86 .
  87 .\" attrList parameter
  88 .
  89 The
  90 .Fa attrList
  91 parameter is a pointer to an
  92 .Vt attrlist
  93 structure, as defined by
  94 .Aq Pa sys/attr.h
  95 (shown below).
  96 It determines what attributes are returned by the function.
  97 You are responsible for filling out all fields of this structure before calling the function.
  98 .Bd -literal
  99 typedef u_int32_t attrgroup_t;
 100 .Pp
 101 struct attrlist {
 102     u_short     bitmapcount; /* number of attr. bit sets in list */
 103     u_int16_t   reserved;    /* (to maintain 4-byte alignment) */
 104     attrgroup_t commonattr;  /* common attribute group */
 105     attrgroup_t volattr;     /* volume attribute group */
 106     attrgroup_t dirattr;     /* directory attribute group */
 107     attrgroup_t fileattr;    /* file attribute group */
 108     attrgroup_t forkattr;    /* fork attribute group */
 109 };
 110 #define ATTR_BIT_MAP_COUNT 5
 111 .Ed
 112 .Pp
 113 .
 114 .\" attrlist elements
 115 .
 116 The fields of the
 117 .Vt attrlist
 118 structure are defined as follows.
 119 .Bl -tag -width XXXbitmapcount
 120 .
 121 .It bitmapcount
 122 Number of attribute bit sets in the structure.
 123 In current systems you must set this to
 124 .Dv ATTR_BIT_MAP_COUNT .
 125 .
 126 .It reserved
 127 Reserved.
 128 You must set this to 0.
 129 .
 130 .It commonattr
 131 A bit set that specifies the common attributes that you require.
 132 Common attributes relate to all types of file system objects.
 133 See below for a description of these attributes.
 134 .
 135 .It volattr
 136 A bit set that specifies the volume attributes that you require.
 137 Volume attributes relate to volumes (that is, mounted file systems).
 138 See below for a description of these attributes.
 139 If you request volume attributes,
 140 .Fa path
 141 must reference the root of a volume.
 142 In addition, you can't request volume attributes if you also request
 143 file or directory attributes.
 144 .
 145 .It dirattr
 146 A bit set that specifies the directory attributes that you require.
 147 See below for a description of these attributes.
 148 .
 149 .It fileattr
 150 A bit set that specifies the file attributes that you require.
 151 See below for a description of these attributes.
 152 .
 153 .It forkattr
 154 A bit set that specifies the fork attributes that you require.
 155 Fork attributes relate to the actual data in the file,
 156 which can be held in multiple named contiguous ranges, or forks.
 157 See below for a description of these attributes.
 158 .
 159 .El
 160 .Pp
 161 .
 162 Unless otherwise noted in the lists below, attributes are read-only.
 163 Attributes labelled as read/write can be set using
 164 .Xr setattrlist 2 .
 165 .Pp
 166 .
 167 .\" attrBuf and attrBufSize parameters
 168 .
 169 The
 170 .Fa attrBuf
 171 and
 172 .Fa attrBufSize
 173 parameters specify a buffer into which the function places attribute values.
 174 The format of this buffer is sufficiently complex that its description
 175 requires a separate section (see below).
 176 The initial contents of this buffer are ignored.
 177 .Pp
 178 .
 179 .\" option parameter
 180 .
 181 The
 182 .Fa options
 183 parameter is a bit set that controls the behaviour of
 184 .Fn getattrlist .
 185 The following option bits are defined.
 186 .
 187 .Bl -tag -width XXXbitmapcount
 188 .
 189 .It FSOPT_NOFOLLOW
 190 If this bit is set,
 191 .Fn getattrlist
 192 will not follow a symlink if it occurs as
 193 the last component of
 194 .Fa path .
 195 .
 196 .El
 197 .
 198 .Sh ATTRIBUTE BUFFER
 199 .
 200 The data returned in the buffer described by
 201 .Fa attrBuf
 202 and
 203 .Fa attrBufSize
 204 is formatted as follows.
 205 .Pp
 206 .
 207 .Bl -enum
 208 .
 209 .It
 210 The first element of the buffer is a
 211 .Vt u_int32_t
 212 that contains the overall length, in bytes, of the attributes returned.
 213 This size includes the length field itself.
 214 .
 215 .It
 216 Following the length field is a list of attributes.
 217 Each attribute is represented by a field of its type,
 218 where the type is given as part of the attribute description (below).
 219 .
 220 .It
 221 The attributes are placed into the attribute buffer in the order
 222 that they are described below.
 223 .
 224 .El
 225 .Pp
 226 .
 227 If the attribute is of variable length, it is represented
 228 in the list by an
 229 .Vt attrreference
 230 structure, as defined by
 231 .Aq Pa sys/attr.h
 232 (shown below).
 233 .
 234 .Bd -literal
 235 typedef struct attrreference {
 236     long        attr_dataoffset;
 237     size_t      attr_length;
 238 } attrreference_t;
 239 .Ed
 240 .Pp
 241 .
 242 This structure contains a 'pointer' to the variable length attribute data.
 243 The
 244 .Fa attr_length
 245 field is the length of the attribute data (in bytes).
 246 The
 247 .Fa attr_dataoffset
 248 field is the offset in bytes from the
 249 .Vt attrreference
 250 structure
 251 to the attribute data.
 252 This offset will always be a multiple of sizeof(unsigned long) bytes,
 253 so you can safely access common data types without fear of alignment
 254 exceptions.
 255 .Pp
 256 .
 257 The
 258 .Fn getattrlist
 259 function will silently truncate attribute data if
 260 .Fa attrBufSize
 261 is too small.
 262 The length field at the front of the attribute list always represents
 263 the length of the data actually copied into the attribute buffer.
 264 If the data is truncated, there is no easy way to determine the
 265 buffer size that's required to get all of the requested attributes.
 266 You should always pass an
 267 .Fa attrBufSize
 268 that is large enough to accommodate the known size of the attributes
 269 in the attribute list (including the leading length field).
 270 .Pp
 271 .
 272 Because the returned attributes are simply truncated if the buffer is
 273 too small, it's possible for a variable length attribute to reference
 274 data beyond the end of the attribute buffer.  That is, it's possible
 275 for the attribute data to start beyond the end of the attribute buffer
 276 (that is, if
 277 .Fa attrRef
 278 is a pointer to the
 279 .Vt attrreference_t ,
 280 ( ( (char *)
 281 .Fa attrRef
 282 ) +
 283 .Fa attr_dataoffset
 284 ) > ( ( (char *)
 285 .Fa attrBuf
 286 ) +
 287 .Fa attrSize
 288 ) ) or, indeed, for the attribute data to extend beyond the end of the attribute buffer (that is,
 289 ( ( (char *)
 290 .Fa attrRef
 291 ) +
 292 .Fa attr_dataoffset
 293 +
 294 .Fa attr_datalength
 295 ) > ( ( (char *)
 296 .Fa attrBuf
 297 ) +
 298 .Fa attrSize
 299 ) ).
 300 If this happens you must increase the size of the buffer and call
 301 .Fn getattrlist
 302 to get an accurate copy of the attribute.
 303 .
 304 .Sh COMMON ATTRIBUTES
 305 .
 306 Common attributes relate to all types of file system objects.
 307 The following common attributes are defined.
 308 .
 309 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
 310 .
 311 .It ATTR_CMN_NAME
 312 An
 313 .Vt attrreference
 314 structure containing the name of the file system object as
 315 UTF-8 encoded, null terminated C string.
 316 The attribute data length will not be greater than
 317 .Dv NAME_MAX +
 318 1.
 319 .Pp
 320 .
 321 .It ATTR_CMN_DEVID
 322 A
 323 .Vt dev_t
 324 containing the device number of the device on which this
 325 file system object's volume is mounted.
 326 Equivalent to the
 327 .Fa st_dev
 328 field of the
 329 .Vt stat
 330 structure returned by
 331 .Xr stat 2 .
 332 .
 333 .It ATTR_CMN_FSID
 334 An
 335 .Vt fsid_t
 336 structure containing the file system identifier for the volume on which
 337 the file system object resides.
 338 Equivalent to the
 339 .Fa f_fsid
 340 field of the
 341 .Vt statfs
 342 structure returned by
 343 .Xr statfs 2 .
 344 .
 345 .Pp
 346 This value is not related to the file system ID from traditional Mac OS (for example,
 347 the
 348 .Fa filesystemID
 349 field of the
 350 .Vt FSVolumeInfo
 351 structure returned by Carbon's FSGetVolumeInfo() function).
 352 On current versions of Mac OS X that value is synthesised by the Carbon File Manager.
 353 .
 354 .It ATTR_CMN_OBJTYPE
 355 An
 356 .Vt fsobj_type_t
 357 that identifies the type of file system object.
 358 The values are taken from
 359 .Vt enum vtype
 360 in
 361 .Aq Pa sys/vnode.h .
 362 .
 363 .It ATTR_CMN_OBJTAG
 364 An
 365 .Vt fsobj_tag_t
 366 that identifies the type of file system containing the object.
 367 The values are taken from
 368 .Vt enum vtagtype
 369 in
 370 .Aq Pa sys/vnode.h .
 371 .
 372 .It ATTR_CMN_OBJID
 373 An
 374 .Vt fsobj_id_t
 375 structure that uniquely identifies the file system object
 376 within its volume.
 377 The fid_generation field of this structure will be zero for all non-root callers
 378 (effective UID not 0).
 379 This identifier need not be persistent across an unmount/mount sequence.
 380 .Pp
 381 .
 382 Some volume formats use well known values for the
 383 .Fa fid_objno
 384 field for the root directory (2) and the parent of root directory (1).
 385 This is not a required behaviour of this attribute.
 386 .
 387 .It ATTR_CMN_OBJPERMANENTID
 388 An
 389 .Vt fsobj_id_t
 390 structure that uniquely identifies the file system object
 391 within its volume.
 392 The fid_generation field of this structure will be zero for all non-root callers
 393 (effective UID not 0).
 394 This identifier should be persistent across an unmount/mount sequence.
 395 .Pp
 396 Some file systems (for example, original HFS) may need to modify the on-disk
 397 structure to return a persistent identifier.
 398 If such a file system is mounted read-only, an attempt to get this attribute
 399 will fail with the error
 400 .Dv EROFS .
 401 .
 402 .It ATTR_CMN_PAROBJID
 403 An
 404 .Vt fsobj_id_t
 405 structure that identifies the parent directory of the file system object.
 406 The fid_generation field of this structure will be zero for all non-root callers
 407 (effective UID not 0).
 408 Equivalent to the ATTR_CMN_OBJID attribute of the parent directory.
 409 This identifier need not be persistent across an unmount/mount sequence.
 410 .Pp
 411 .
 412 On a volume that supports hard links, a multiply linked file has no unique parent.
 413 This attribute will return an unspecified parent.
 414 .Pp
 415 .
 416 For some volume formats this attribute is very expensive to calculate.
 417 .
 418 .It ATTR_CMN_SCRIPT
 419 (read/write) A
 420 .Vt text_encoding_t
 421 containing a text encoding hint for
 422 the file system object's name.
 423 It is included to facilitate the lossless round trip conversion of names between
 424 Unicode and traditional Mac OS script encodings.
 425 The values are defined in
 426 .Aq Pa CarbonCore/TextCommon.h .
 427 File systems that do not have an appropriate text encoding value should return
 428 kTextEncodingMacUnicode.
 429 See DTS Q&A 1173 "File Manager Text Encoding Hints".
 430 .
 431 .It ATTR_CMN_CRTIME
 432 (read/write) A
 433 .Vt timespec
 434 structure containing the time that the file system object
 435 was created.
 436 .
 437 .It ATTR_CMN_MODTIME
 438 (read/write) A
 439 .Vt timespec
 440 structure containing the time that the file system object
 441 was last modified.
 442 Equivalent to the
 443 .Fa st_mtimespec
 444 field of the
 445 .Vt stat
 446 structure returned by
 447 .Xr stat 2 .
 448 .
 449 .It ATTR_CMN_CHGTIME
 450 (read/write) A
 451 .Vt timespec
 452 structure containing the time that the file system object's
 453 attributes were last modified.
 454 Equivalent to the
 455 .Fa st_ctimespec
 456 field of the
 457 .Vt stat
 458 structure returned by
 459 .Xr stat 2 .
 460 .
 461 .It ATTR_CMN_ACCTIME
 462 (read/write) A
 463 .Vt timespec
 464 structure containing the time that the file system object
 465 was last accessed.
 466 Equivalent to the
 467 .Fa st_atimespec
 468 field of the
 469 .Vt stat
 470 structure returned by
 471 .Xr stat 2 .
 472 .
 473 .It ATTR_CMN_BKUPTIME
 474 (read/write) A
 475 .Vt timespec
 476 structure containing the time that the file system object was
 477 last backed up.
 478 This value is for use by backup utilities.
 479 The file system stores but does not interpret the value.
 480 .
 481 .It ATTR_CMN_FNDRINFO
 482 (read/write) 32 bytes of data for use by the Finder.
 483 Equivalent to the concatenation of a
 484 .Vt FileInfo
 485 structure and an
 486 .Vt ExtendedFileInfo
 487 structure
 488 (or, for directories, a
 489 .Vt FolderInfo
 490 structure and an
 491 .Vt ExtendedFolderInfo
 492 structure).
 493 These structures are defined in
 494 .Aq Pa CarbonCore/Finder.h .
 495 .Pp
 496 This attribute is not byte swapped by the file system.
 497 The value of multibyte fields on disk is always big endian.
 498 When running on a little endian system (such as Darwin on x86),
 499 you must byte swap any multibyte fields.
 500 .
 501 .It ATTR_CMN_OWNERID
 502 (read/write) A
 503 .Vt uid_t
 504 containing the owner of the file system object.
 505 Equivalent to the
 506 .Fa st_uid
 507 field of the
 508 .Vt stat
 509 structure returned by
 510 .Xr stat 2 .
 511 .
 512 .It ATTR_CMN_GRPID
 513 (read/write) A
 514 .Vt gid_t
 515 containing the group of the file system object.
 516 Equivalent to the
 517 .Fa st_gid
 518 field of the
 519 .Vt stat
 520 structure returned by
 521 .Xr stat 2 .
 522 .
 523 .It ATTR_CMN_ACCESSMASK
 524 (read/write) A
 525 .Vt u_int32_t
 526 containing the access permissions of the file system object.
 527 Equivalent to the
 528 .Fa st_mode
 529 field of the
 530 .Vt stat
 531 structure returned by
 532 .Xr stat 2 .
 533 .
 534 .It ATTR_CMN_NAMEDATTRCOUNT
 535 A
 536 .Vt u_int32_t
 537 containing the number of named attributes of the file system object.
 538 .
 539 .It ATTR_CMN_NAMEDATTRLIST
 540 An
 541 .Vt attrreference
 542 structure containing a list of named attributes of the file system object.
 543 No built-in file systems on Mac OS X currently support named attributes.
 544 Because of this, the structure of this attribute's value is not yet defined.
 545 .
 546 .It ATTR_CMN_FLAGS
 547 (read/write) A
 548 .Vt u_int32_t
 549 containing file flags.
 550 Equivalent to the
 551 .Fa st_flags
 552 field of the
 553 .Vt stat
 554 structure returned by
 555 .Xr stat 2 .
 556 For more information about these flags, see
 557 .Xr chflags 2 .
 558 .Pp
 559 .
 560 The order that attributes are placed into the attribute buffer
 561 almost invariably matches the order of the attribute mask bit values.
 562 The exception is
 563 .Dv ATTR_CMN_FLAGS .
 564 If its order was based on its bit position, it would be before
 565 the
 566 .Dv ATTR_CMN_NAMEDATTRCOUNT
 567 /
 568 .Dv ATTR_CMN_NAMEDATTRLIST
 569 pair, however,
 570 it is placed in the buffer after them.
 571 .
 572 .It ATTR_CMN_USERACCESS
 573 A
 574 .Vt u_int32_t
 575 containing the effective permissions of the current user
 576 (the calling process's effective UID) for this file system object.
 577 You can test for read, write, and execute permission using
 578 .Dv R_OK ,
 579 .Dv W_OK ,
 580 and
 581 .Dv X_OK ,
 582 respectively.
 583 See
 584 .Xr access 2
 585 for more details.
 586 .
 587 .It ATTR_CMN_FILEID
 588 A
 589 .Vt u_int64_t
 590 that uniquely identifies the file system object within its volume.
 591 .
 592 .It ATTR_CMN_PARENTID
 593 A
 594 .Vt u_int64_t
 595 that identifies the parent directory of the file system object.
 596 .
 597 .El
 598 .
 599 .Sh VOLUME ATTRIBUTES
 600 .
 601 Volume attributes relate to volumes (that is, mounted file systems).
 602 The following volume attributes are defined.
 603 .
 604 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
 605 .
 606 .It ATTR_VOL_INFO
 607 For reasons that are not at all obvious, you must set
 608 .Dv ATTR_VOL_INFO
 609 in the
 610 .Fa volattr
 611 field if you request any other volume attributes.
 612 This does not result in any attribute data being added to the attribute buffer.
 613 .
 614 .It ATTR_VOL_FSTYPE
 615 A
 616 .Vt u_int32_t
 617 containing the file system type.
 618 Equivalent to the
 619 .Fa f_type
 620 field of the
 621 .Vt statfs
 622 structure returned by
 623 .Xr statfs 2 .
 624 Generally not a useful value.
 625 .
 626 .It ATTR_VOL_SIGNATURE
 627 A
 628 .Vt u_int32_t
 629 containing the volume signature word.
 630 This value is unique within a given file system type and lets you
 631 distinguish between different volume formats handled by the same file system.
 632 See
 633 .Aq Pa CarbonCore/Files.h
 634 for more details.
 635 .
 636 .It ATTR_VOL_SIZE
 637 An
 638 .Vt off_t
 639 containing the total size of the volume in bytes.
 640 .
 641 .It ATTR_VOL_SPACEFREE
 642 An
 643 .Vt off_t
 644 containing the free space on the volume in bytes.
 645 .
 646 .It ATTR_VOL_SPACEAVAIL
 647 An
 648 .Vt off_t
 649 containing the space, in bytes, on the volume available to non-privileged processes.
 650 This is the free space minus the amount of space reserved by the system to prevent critical
 651 disk exhaustion errors.
 652 Non-privileged programs, like a disk management tool, should use this value to display the
 653 space available to the user.
 654 .Pp
 655 .Dv ATTR_VOL_SPACEAVAIL
 656 is to
 657 .Dv ATTR_VOL_SPACEFREE
 658 as
 659 .Fa f_bavail
 660 is to
 661 .Fa f_bfree
 662 in
 663 .Xr statfs 2 .
 664 .
 665 .It ATTR_VOL_MINALLOCATION
 666 An
 667 .Vt off_t
 668 containing the minimum allocation size on the volume in bytes.
 669 If you create a file containing one byte, it will consume this much space.
 670 .
 671 .It ATTR_VOL_ALLOCATIONCLUMP
 672 An
 673 .Vt off_t
 674 containing the allocation clump size on the volume, in bytes.
 675 As a file is extended, the file system will attempt to allocate
 676 this much space each time in order to reduce fragmentation.
 677 .
 678 .It ATTR_VOL_IOBLOCKSIZE
 679 A
 680 .Vt u_int32_t
 681 containing the optimal block size when reading or writing data.
 682 Equivalent to the
 683 .Fa f_iosize
 684 field of the
 685 .Vt statfs
 686 structure returned by
 687 .Xr statfs 2 .
 688 .
 689 .It ATTR_VOL_OBJCOUNT
 690 A
 691 .Vt u_int32_t
 692 containing the number of file system objects on the volume.
 693 .
 694 .It ATTR_VOL_FILECOUNT
 695 A
 696 .Vt u_int32_t
 697 containing the number of files on the volume.
 698 .
 699 .It ATTR_VOL_DIRCOUNT
 700 A
 701 .Vt u_int32_t
 702 containing the number of directories on the volume.
 703 .
 704 .It ATTR_VOL_MAXOBJCOUNT
 705 A
 706 .Vt u_int32_t
 707 containing the maximum number of file system objects that can be stored on the volume.
 708 .
 709 .It ATTR_VOL_MOUNTPOINT
 710 An
 711 .Vt attrreference
 712 structure containing the path to the volume's mount point as a
 713 UTF-8 encoded, null terminated C string.
 714 The attribute data length will not be greater than
 715 .Dv MAXPATHLEN .
 716 Equivalent to the
 717 .Fa f_mntonname
 718 field of the
 719 .Vt statfs
 720 structure returned by
 721 .Xr statfs 2 .
 722 .
 723 .It ATTR_VOL_NAME
 724 (read/write) An
 725 .Vt attrreference
 726 structure containing the name of the volume as a
 727 UTF-8 encoded, null terminated C string.
 728 The attribute data length will not be greater than
 729 .Dv NAME_MAX +
 730 1.
 731 .Pp
 732 .
 733 This attribute is only read/write if the
 734 .Dv VOL_CAP_INT_VOL_RENAME
 735 bit is set in the volume capabilities (see below).
 736 .Pp
 737 .
 738 .It ATTR_VOL_MOUNTFLAGS
 739 A
 740 .Vt u_int32_t
 741 containing the volume mount flags.
 742 This is a copy of the value passed to the
 743 .Fa flags
 744 parameter of
 745 .Xr mount 2
 746 when the volume was mounted.
 747 Equivalent to the
 748 .Fa f_flags
 749 field of the
 750 .Vt statfs
 751 structure returned by
 752 .Xr statfs 2 .
 753 .
 754 .It ATTR_VOL_MOUNTEDDEVICE
 755 An
 756 .Vt attrreference
 757 structure that returns the same value as the
 758 .Fa f_mntfromname
 759 field of the
 760 .Vt statfs
 761 structure returned by
 762 .Xr statfs 2 .
 763 For local volumes this is the path to the device on which the volume is mounted as a
 764 UTF-8 encoded, null terminated C string.
 765 For network volumes, this is a unique string that identifies the mount.
 766 The attribute data length will not be greater than
 767 .Dv MAXPATHLEN .
 768 .Pp
 769 .
 770 .It ATTR_VOL_ENCODINGSUSED
 771 An
 772 .Vt unsigned long long
 773 containing a bitmap of the text encodings used on this volume.
 774 For more information about this, see the discussion of
 775 .Fa encodingsBitmap
 776 in DTS Technote 1150 "HFS Plus Volume Format".
 777 .
 778 .It ATTR_VOL_CAPABILITIES
 779 A
 780 .Vt vol_capabilities_attr_t
 781 structure describing the optional features supported by this volume.
 782 See below for a discussion of volume capabilities.
 783 .
 784 .It ATTR_VOL_ATTRIBUTES
 785 A
 786 .Vt vol_attributes_attr_t
 787 structure describing the attributes supported by this volume.
 788 This structure is discussed below, along with volume capabilities.
 789 .
 790 .El
 791 .
 792 .Sh DIRECTORY ATTRIBUTES
 793 .
 794 The following directory attributes are defined.
 795 .
 796 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
 797 .
 798 .It ATTR_DIR_LINKCOUNT
 799 A
 800 .Vt u_int32_t
 801 containing the number of hard links to the directory;
 802 this does not include the historical "." and ".." entries.
 803 For filesystems that do not support hard links to directories,
 804 this value will be 1.
 805 .
 806 .It ATTR_DIR_ENTRYCOUNT
 807 A
 808 .Vt u_int32_t
 809 containing the number of file system objects in the directory, not including
 810 any synthetic items.
 811 .
 812 .It ATTR_DIR_MOUNTSTATUS
 813 A
 814 .Vt u_int32_t
 815 containing flags describing what's mounted on the directory.
 816 Currently the only flag defined is
 817 .Dv DIR_MNTSTATUS_MNTPOINT,
 818 which indicates that there is a file system mounted on this directory.
 819 Due to a bug (r. 3502822), this flag is never set on current system.
 820 .
 821 .El
 822 .
 823 .Sh FILE ATTRIBUTES
 824 .
 825 The following file attributes are defined.
 826 .
 827 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
 828 .
 829 .It ATTR_FILE_LINKCOUNT
 830 A
 831 .Vt u_int32_t
 832 containing the number of hard links to this file.
 833 Equivalent to the
 834 .Fa st_nlink
 835 field of the
 836 .Vt stat
 837 structure returned by
 838 .Xr stat 2 .
 839 .
 840 .It ATTR_FILE_TOTALSIZE
 841 An
 842 .Vt off_t
 843 containing the total number of bytes in all forks of the file (the logical size).
 844 .
 845 .It ATTR_FILE_ALLOCSIZE
 846 An
 847 .Vt off_t
 848 containing a count of the bytes on disk used by all of the file's forks (the physical size).
 849 .
 850 .It ATTR_FILE_IOBLOCKSIZE
 851 A
 852 .Vt u_int32_t
 853 containing the optimal block size when reading or writing this file's data.
 854 .
 855 .It ATTR_FILE_CLUMPSIZE
 856 A
 857 .Vt u_int32_t
 858 containing the allocation clump size for this file, in bytes.
 859 As the file is extended, the file system will attempt to allocate
 860 this much space each time in order to reduce fragmentation.
 861 This value applies to the data fork.
 862 .
 863 .It ATTR_FILE_DEVTYPE
 864 (read/write) A
 865 .Vt u_int32_t
 866 containing the device type for a special device file.
 867 Equivalent to the
 868 .Fa st_rdev
 869 field of the
 870 .Vt stat
 871 structure returned by
 872 .Xr stat 2 .
 873 .
 874 .It ATTR_FILE_FILETYPE
 875 A
 876 .Vt u_int32_t
 877 that whose value is reserved.
 878 Clients should ignore its value.
 879 New volume format implementations should not support this attribute.
 880 .
 881 .It ATTR_FILE_FORKCOUNT
 882 A
 883 .Vt u_int32_t
 884 containing the number of forks in the file.
 885 No built-in file systems on Mac OS X currently support forks other
 886 than the data and resource fork.
 887 .
 888 .It ATTR_FILE_FORKLIST
 889 An
 890 .Vt attrreference
 891 structure containing a list of named forks of the file.
 892 No built-in file systems on Mac OS X currently support forks
 893 other than the data and resource fork.
 894 Because of this, the structure of this attribute's value is not yet defined.
 895 .
 896 .It ATTR_FILE_DATALENGTH
 897 An
 898 .Vt off_t
 899 containing the length of the data fork in bytes (the logical size).
 900 .
 901 .It ATTR_FILE_DATAALLOCSIZE
 902 An
 903 .Vt off_t
 904 containing a count of the bytes on disk used by the data fork (the physical size).
 905 .
 906 .It ATTR_FILE_DATAEXTENTS
 907 An
 908 .Vt extentrecord
 909 array for the data fork.
 910 The array contains eight
 911 .Vt diskextent
 912 structures which represent the first
 913 eight extents of the fork.
 914 .Pp
 915 This attributes exists for compatibility reasons.
 916 New clients should not use this attribute.
 917 Rather, they should use the
 918 .Dv F_LOG2PHYS
 919 command in
 920 .Xr fcntl 2 .
 921 .Pp
 922 .
 923 In current implementations the value may not be entirely accurate for
 924 a variety of reasons.
 925 .
 926 .It ATTR_FILE_RSRCLENGTH
 927 An
 928 .Vt off_t
 929 containing the length of the resource fork in bytes (the logical size).
 930 .
 931 .It ATTR_FILE_RSRCALLOCSIZE
 932 An
 933 .Vt off_t
 934 containing a count of the bytes on disk used by the resource fork (the physical size).
 935 .
 936 .It ATTR_FILE_RSRCEXTENTS
 937 An
 938 .Vt extentrecord
 939 array for the resource fork.
 940 The array contains eight
 941 .Vt diskextent
 942 structures which represent the first
 943 eight extents of the fork.
 944 .Pp
 945 See also
 946 .Dv ATTR_FILE_DATAEXTENTS .
 947 .
 948 .El
 949 .
 950 .Sh FORK ATTRIBUTES
 951 .
 952 Fork attributes relate to the actual data in the file,
 953 which can be held in multiple named contiguous ranges, or forks.
 954 The following fork attributes are defined.
 955 .
 956 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
 957 .
 958 .It ATTR_FORK_TOTALSIZE
 959 An
 960 .Vt off_t
 961 containing the length of the fork in bytes (the logical size).
 962 .
 963 .It ATTR_FORK_ALLOCSIZE
 964 An
 965 .Vt off_t
 966 containing a count of the bytes on disk used by the fork (the physical size).
 967 .
 968 .El
 969 .Pp
 970 .
 971 Fork attributes are not properly implemented by any current Mac OS X
 972 volume format implementation.
 973 We strongly recommend that client programs do not request fork attributes.
 974 If you are implementing a volume format, you should not support these attributes.
 975 .
 976 .Sh VOLUME CAPABILITIES
 977 .
 978 .\" vol_capabilities_attr_t
 979 .
 980 Not all volumes support all features.
 981 The
 982 .Dv ATTR_VOL_CAPABILITIES
 983 attribute returns a
 984 .Vt vol_capabilities_attr_t
 985 structure (shown below) that indicates which features are supported by the volume.
 986 .
 987 .Bd -literal
 988 typedef u_int32_t vol_capabilities_set_t[4];
 989 .Pp
 990 .
 991 #define VOL_CAPABILITIES_FORMAT     0
 992 #define VOL_CAPABILITIES_INTERFACES 1
 993 #define VOL_CAPABILITIES_RESERVED1  2
 994 #define VOL_CAPABILITIES_RESERVED2  3
 995 .Pp
 996 .
 997 typedef struct vol_capabilities_attr {
 998     vol_capabilities_set_t capabilities;
 999     vol_capabilities_set_t valid;
1000 } vol_capabilities_attr_t;
1001 .Ed
1002 .Pp
1003 .
1004 The structure contains two fields,
1005 .Fa capabilities
1006 and
1007 .Fa valid .
1008 Each consists of an array of four elements.
1009 The arrays are indexed by the following values.
1010 .
1011 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1012 .
1013 .It VOL_CAPABILITIES_FORMAT
1014 This element contains information about the volume format.
1015 See
1016 .Dv VOL_CAP_FMT_PERSISTENTOBJECTIDS
1017 and so on, below.
1018 .
1019 .It VOL_CAPABILITIES_INTERFACES
1020 This element contains information about which optional functions are
1021 supported by the volume format implementation.
1022 See
1023 .Dv VOL_CAP_INT_SEARCHFS
1024 and so on, below.
1025 .
1026 .It VOL_CAPABILITIES_RESERVED1
1027 Reserved.
1028 A file system implementation should set this element to zero.
1029 A client program should ignore this element.
1030 .
1031 .It VOL_CAPABILITIES_RESERVED2
1032 Reserved.
1033 A file system implementation should set this element to zero.
1034 A client program should ignore this element.
1035 .
1036 .El
1037 .Pp
1038 .
1039 The
1040 .Fa valid
1041 field contains bit sets that indicate which flags are known to the volume format
1042 implementation.
1043 Each bit indicates whether the contents of the corresponding bit in the
1044 .Fa capabilities
1045 field is valid.
1046 .Pp
1047 .
1048 The
1049 .Fa capabilities
1050 field contains bit sets that indicate whether a particular feature is implemented
1051 by this volume format.
1052 .Pp
1053 .
1054 The following bits are defined in the first element (indexed by
1055 .Dv VOL_CAPABILITIES_FORMAT )
1056 of the
1057 .Fa capabilities
1058 and
1059 .Fa valid
1060 fields of the
1061 .Vt vol_capabilities_attr_t
1062 structure.
1063 .
1064 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1065 .
1066 .It VOL_CAP_FMT_PERSISTENTOBJECTIDS
1067 If this bit is set the volume format supports persistent object identifiers
1068 and can look up file system objects by their IDs.
1069 See
1070 .Dv ATTR_CMN_OBJPERMANENTID
1071 for details about how to obtain these identifiers.
1072 .
1073 .It VOL_CAP_FMT_SYMBOLICLINKS
1074 If this bit is set the volume format supports symbolic links.
1075 .
1076 .It VOL_CAP_FMT_HARDLINKS
1077 If this bit is set the volume format supports hard links.
1078 .
1079 .It VOL_CAP_FMT_JOURNAL
1080 If this bit is set the volume format supports a journal used to
1081 speed recovery in case of unplanned restart (such as a power outage
1082 or crash).
1083 This does not necessarily mean the volume is actively using a journal.
1084 .Pp
1085 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1086 .
1087 .It VOL_CAP_FMT_JOURNAL_ACTIVE
1088 If this bit is set the volume is currently using a journal for
1089 speedy recovery after an unplanned restart.
1090 This bit can be set only if
1091 .Dv VOL_CAP_FMT_JOURNAL
1092 is also set.
1093 .Pp
1094 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1095 .
1096 .It VOL_CAP_FMT_NO_ROOT_TIMES
1097 If this bit is set the volume format does not store reliable times for
1098 the root directory, so you should not depend on them to detect changes,
1099 identify volumes across unmount/mount, and so on.
1100 .Pp
1101 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1102 .
1103 .It VOL_CAP_FMT_SPARSE_FILES
1104 If this bit is set the volume format supports sparse files,
1105 that is, files which can have 'holes' that have never been written
1106 to, and thus do not consume space on disk.
1107 A sparse file may have an allocated size on disk that is less than its logical length (that is,
1108 .Dv ATTR_FILE_ALLOCSIZE
1109 <
1110 .Dv ATTR_FILE_TOTALSIZE ).
1111 .
1112 .Pp
1113 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1114 .
1115 .It VOL_CAP_FMT_ZERO_RUNS
1116 For security reasons, parts of a file (runs) that have never been
1117 written to must appear to contain zeroes.
1118 When this bit is set, the volume keeps track of allocated but unwritten
1119 runs of a file so that it can substitute zeroes without actually
1120 writing zeroes to the media.
1121 This provides performance similar to sparse files, but not the space savings.
1122 .Pp
1123 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1124 .
1125 .It VOL_CAP_FMT_CASE_SENSITIVE
1126 If this bit is set the volume format treats upper and lower case
1127 characters in file and directory names as different.
1128 Otherwise an upper case character is equivalent to a lower case character,
1129 and you can't have two names that differ solely in the case of
1130 the characters.
1131 .Pp
1132 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1133 .
1134 .It VOL_CAP_FMT_CASE_PRESERVING
1135 If this bit is set the volume format preserves the case of
1136 file and directory names.
1137 Otherwise the volume may change the case of some characters
1138 (typically making them all upper or all lower case).
1139 A volume that sets
1140 .Dv VOL_CAP_FMT_CASE_SENSITIVE
1141 must also set
1142 .Dv VOL_CAP_FMT_CASE_PRESERVING .
1143 .Pp
1144 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1145 .
1146 .It VOL_CAP_FMT_FAST_STATFS
1147 This bit is used as a hint to upper layers (specifically the Carbon File Manager) to
1148 indicate that
1149 .Xr statfs 2
1150 is fast enough that its results need not be cached by the caller.
1151 A volume format implementation that caches the
1152 .Xr statfs 2
1153 information in memory should set this bit.
1154 An implementation that must always read from disk or always perform a network
1155 transaction to satisfy
1156 .Xr statfs 2
1157 should not set this bit.
1158 .Pp
1159 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1160 .
1161 .It VOL_CAP_FMT_2TB_FILESIZE
1162 If this bit is set the volume format supports file
1163 sizes upto 2TB.  This bit does not necessarily mean that the file
1164 system does not support file size more than 2TB.
1165 This bit does not mean that the currently available space on the volume is 2TB.
1166 .Pp
1167 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1168 .
1169 .El
1170 .Pp
1171 .
1172 The following bits are defined in the second element (indexed by
1173 .Dv VOL_CAPABILITIES_INTERFACES )
1174 of the
1175 .Fa capabilities
1176 and
1177 .Fa valid
1178 fields of the
1179 .Vt vol_capabilities_attr_t
1180 structure.
1181 .
1182 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1183 .
1184 .It VOL_CAP_INT_SEARCHFS
1185 If this bit is set the volume format implementation supports
1186 .Xr searchfs 2 .
1187 .
1188 .It VOL_CAP_INT_ATTRLIST
1189 If this bit is set the volume format implementation supports
1190 .Fn getattrlist
1191 and
1192 .Xr setattrlist 2 .
1193 .
1194 .It VOL_CAP_INT_NFSEXPORT
1195 If this bit is set the volume format implementation allows this volume to be exported via NFS.
1196 .
1197 .It VOL_CAP_INT_READDIRATTR
1198 If this bit is set the volume format implementation supports
1199 .Xr getdirentriesattr 2 .
1200 .
1201 .It VOL_CAP_INT_EXCHANGEDATA
1202 If this bit is set the volume format implementation supports
1203 .Xr exchangedata 2 .
1204 .Pp
1205 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1206 .
1207 .It VOL_CAP_INT_COPYFILE
1208 If this bit is set the volume format implementation supports the (private and undocumented)
1209 copyfile() function.
1210 .Pp
1211 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1212 .
1213 .It VOL_CAP_INT_ALLOCATE
1214 If this bit is set the volume format implementation supports the
1215 .Dv F_PREALLOCATE
1216 selector of
1217 .Xr fcntl 2 .
1218 .Pp
1219 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1220 .
1221 .It VOL_CAP_INT_VOL_RENAME
1222 If this bit is set the volume format implementation allows you to
1223 modify the volume name using
1224 .Xr setattrlist 2 .
1225 .Pp
1226 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1227 .
1228 .It VOL_CAP_INT_ADVLOCK
1229 If this bit is set the volume format implementation supports
1230 advisory locking, that is, the
1231 .Dv F_GETLK ,
1232 .Dv F_SETLK ,
1233 and
1234 .Dv F_SETLKW
1235 selectors to
1236 .Xr fcntl 2 .
1237 .Pp
1238 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1239 .
1240 .It VOL_CAP_INT_FLOCK
1241 If this bit is set the volume format implementation supports
1242 whole file locks.
1243 This includes
1244 .Xr flock 2
1245 and the
1246 .Dv O_EXLOCK
1247 and
1248 .Dv O_SHLOCK
1249 flags to
1250 .Xr open 2 .
1251 .Pp
1252 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1253 .
1254 .It VOL_CAP_INT_EXTENDED_SECURITY
1255 If this bit is set the volume format implementation supports
1256 extended security controls (ACLs).
1257 .Pp
1258 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1259 .
1260 .It VOL_CAP_INT_USERACCESS
1261 If this bit is set the volume format implementation supports the
1262 ATTR_CMN_USERACCESS attribute.
1263 .Pp
1264 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1265 .
1266 .El
1267 .Pp
1268 .
1269 .\" vol_attributes_attr_t
1270 .
1271 A volume can also report which attributes it supports.
1272 This information is returned by the
1273 .Dv ATTR_VOL_ATTRIBUTES
1274 attribute, which returns a
1275 .Vt vol_attributes_attr_t
1276 structure (shown below).
1277 .
1278 .Bd -literal
1279 typedef struct attribute_set {
1280     attrgroup_t commonattr; /* common attribute group */
1281     attrgroup_t volattr;    /* volume attribute group */
1282     attrgroup_t dirattr;    /* directory attribute group */
1283     attrgroup_t fileattr;   /* file attribute group */
1284     attrgroup_t forkattr;   /* fork attribute group */
1285 } attribute_set_t;
1286 .Pp
1287 .
1288 typedef struct vol_attributes_attr {
1289     attribute_set_t validattr;
1290     attribute_set_t nativeattr;
1291 } vol_attributes_attr_t;
1292 .Ed
1293 .Pp
1294 .
1295 The
1296 .Fa validattr
1297 field consists of a number of bit sets that indicate whether an attribute is
1298 supported by the volume format implementation.
1299 The
1300 .Fa nativeattr
1301 is similar except that the bit sets indicate whether an attribute is supported
1302 natively by the volume format.
1303 An attribute is supported natively if the volume format implementation does not have to do
1304 any complex conversions to access the attribute.
1305 For example, a volume format might support persistent object identifiers, but
1306 doing so requires a complex table lookup that is not part of the core volume
1307 format.
1308 In that case, the
1309 .Dv ATTR_VOL_ATTRIBUTES
1310 attribute would return
1311 .Dv ATTR_CMN_OBJPERMANENTID
1312 set in the
1313 .Fa validattr
1314 field of the
1315 .Vt vol_attributes_attr_t ,
1316 but not in the
1317 .Fa nativeattr
1318 field.
1319 .
1320 .Sh RETURN VALUES
1321 Upon successful completion a value of 0 is returned.
1322 Otherwise, a value of -1 is returned and
1323 .Va errno
1324 is set to indicate the error.
1325 .
1326 .Sh COMPATIBILITY
1327 Not all volumes support
1328 .Fn getattrlist .
1329 The best way to test whether a volume supports this function is to
1330 simply call it and check the error result.
1331 .Fn getattrlist
1332 will return
1333 .Dv ENOTSUP
1334 if it is not supported on a particular volume.
1335 .Pp
1336 .
1337 The
1338 .Fn getattrlist
1339 function has been undocumented for more than two years.
1340 In that time a number of volume format implementations have been created without
1341 a proper specification for the behaviour of this routine.
1342 You may encounter volume format implementations with slightly different
1343 behaviour than what is described here.
1344 Your program is expected to be tolerant of this variant behaviour.
1345 .Pp
1346 .
1347 If you're implementing a volume format that supports
1348 .Fn getattrlist ,
1349 you should be careful to support the behaviour specified by this document.
1350 .
1351 .Sh ERRORS
1352 .Fn getattrlist
1353 will fail if:
1354 .Bl -tag -width Er
1355 .
1356 .It Bq Er ENOTSUP
1357 The volume does not support
1358 .Fn getattrlist .
1359 .
1360 .It Bq Er ENOTDIR
1361 A component of the path prefix is not a directory.
1362 .
1363 .It Bq Er ENAMETOOLONG
1364 A component of a path name exceeded
1365 .Dv NAME_MAX
1366 characters, or an entire path name exceeded
1367 .Dv PATH_MAX
1368 characters.
1369 .
1370 .It Bq Er ENOENT
1371 The file system object does not exist.
1372 .
1373 .It Bq Er EACCES
1374 Search permission is denied for a component of the path prefix.
1375 .
1376 .It Bq Er ELOOP
1377 Too many symbolic links were encountered in translating the pathname.
1378 .
1379 .It Bq Er EFAULT
1380 .Fa path ,
1381 .Fa attrList
1382 or
1383 .Em attrBuf
1384 points to an invalid address.
1385 .
1386 .It Bq Er EINVAL
1387 The
1388 .Fa bitmapcount
1389 field of
1390 .Fa attrList
1391 is not
1392 .Dv ATTR_BIT_MAP_COUNT .
1393 .
1394 .It Bq Er EINVAL
1395 You requested an invalid attribute.
1396 .
1397 .It Bq Er EINVAL
1398 You requested an attribute that is not supported for this file system object.
1399 .
1400 .It Bq Er EINVAL
1401 You requested volume attributes and directory or file attributes.
1402 .
1403 .It Bq Er EINVAL
1404 You requested volume attributes but
1405 .Fa path
1406 does not reference the root of the volume.
1407 .
1408 .It Bq Er EROFS
1409 The volume is read-only but must be modified in order to return this attribute.
1410 .
1411 .It Bq Er EIO
1412 An I/O error occurred while reading from or writing to the file system.
1413 .El
1414 .Pp
1415 .
1416 .Sh CAVEATS
1417 .
1418 If you request any volume attributes, you must set
1419 .Dv ATTR_VOL_INFO
1420 in the
1421 .Fa volattr
1422 field, even though it generates no result in the attribute buffer.
1423 .Pp
1424 .
1425 The order that attributes are stored in the attribute buffer almost
1426 invariably matches the order of attribute mask bit values.
1427 For example,
1428 .Dv ATTR_CMN_NAME
1429 (0x00000001) comes before
1430 .Dv ATTR_CMN_DEVID
1431 (0x00000002) because its value is smaller.
1432 However, you can not rely on this ordering because there is one key exception:
1433 .Dv ATTR_CMN_FLAGS
1434 is placed after the
1435 .Dv ATTR_CMN_NAMEDATTRCOUNT
1436 /
1437 .Dv ATTR_CMN_NAMEDATTRLIST
1438 pair, even though its bit position indicates that it should come before.
1439 This is due to a bug in an early version of Mac OS X that can't be fixed for
1440 binary compatibility reasons.
1441 When ordering attributes, you should always use the order in which they
1442 are described above.
1443 .Pp
1444 .
1445 For more caveats, see also the compatibility notes above.
1446 .
1447 .Sh EXAMPLES
1448 .
1449 The following code prints the file type and creator of a file,
1450 assuming that the volume supports the required attributes.
1451 .
1452 .Bd -literal
1453 #include <assert.h>
1454 #include <stdio.h>
1455 #include <string.h>
1456 #include <sys/attr.h>
1457 #include <sys/errno.h>
1458 #include <unistd.h>
1459 #include <sys/vnode.h>
1460 .Pp
1461 .
1462 typedef struct attrlist attrlist_t;
1463 .Pp
1464 .
1465 struct FInfoAttrBuf {
1466     u_int32_t       length;
1467     fsobj_type_t    objType;
1468     char            finderInfo[32];
1469 };
1470 typedef struct FInfoAttrBuf FInfoAttrBuf;
1471 .Pp
1472 .
1473 static int FInfoDemo(const char *path)
1474 {
1475     int             err;
1476     attrlist_t      attrList;
1477     FInfoAttrBuf    attrBuf;
1478 .Pp
1479 .
1480     memset(&attrList, 0, sizeof(attrList));
1481     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1482     attrList.commonattr  = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1483 .Pp
1484
1485     err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1486     if (err != 0) {
1487         err = errno;
1488     }
1489 .Pp
1490
1491     if (err == 0) {
1492         assert(attrBuf.length == sizeof(attrBuf));
1493 .Pp
1494
1495         printf("Finder information for %s:\en", path);
1496         switch (attrBuf.objType) {
1497             case VREG:
1498                 printf("file type    = '%.4s'\en", &attrBuf.finderInfo[0]);
1499                 printf("file creator = '%.4s'\en", &attrBuf.finderInfo[4]);
1500                 break;
1501             case VDIR:
1502                 printf("directory\en");
1503                 break;
1504             default:
1505                 printf("other object type, %d\en", attrBuf.objType);
1506                 break;
1507         }
1508     }
1509 .Pp
1510 .
1511     return err;
1512 }
1513 .Ed
1514 .Pp
1515 .
1516 The following code is an alternative implementation that uses nested structures
1517 to group the related attributes.
1518 .
1519 .Bd -literal
1520 #include <assert.h>
1521 #include <stdio.h>
1522 #include <stddef.h>
1523 #include <string.h>
1524 #include <sys/attr.h>
1525 #include <sys/errno.h>
1526 #include <unistd.h>
1527 #include <sys/vnode.h>
1528 .Pp
1529 .
1530 typedef struct attrlist attrlist_t;
1531 .Pp
1532 .
1533 struct FInfo2CommonAttrBuf {
1534     fsobj_type_t    objType;
1535     char            finderInfo[32];
1536 };
1537 typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
1538 .Pp
1539 .
1540 struct FInfo2AttrBuf {
1541     u_int32_t           length;
1542     FInfo2CommonAttrBuf common;
1543 };
1544 typedef struct FInfo2AttrBuf FInfo2AttrBuf;
1545 .Pp
1546 .
1547 static int FInfo2Demo(const char *path)
1548 {
1549     int             err;
1550     attrlist_t      attrList;
1551     FInfo2AttrBuf   attrBuf;
1552 .Pp
1553 .
1554     memset(&attrList, 0, sizeof(attrList));
1555     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1556     attrList.commonattr  = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1557 .Pp
1558 .
1559     err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1560     if (err != 0) {
1561         err = errno;
1562     }
1563 .Pp
1564 .
1565     if (err == 0) {
1566         assert(attrBuf.length == sizeof(attrBuf));
1567 .Pp
1568 .
1569         printf("Finder information for %s:\en", path);
1570         switch (attrBuf.common.objType) {
1571             case VREG:
1572                 printf(
1573                     "file type    = '%.4s'\en",
1574                     &attrBuf.common.finderInfo[0]
1575                 );
1576                 printf(
1577                     "file creator = '%.4s'\en",
1578                     &attrBuf.common.finderInfo[4]
1579                 );
1580                 break;
1581             case VDIR:
1582                 printf("directory\en");
1583                 break;
1584             default:
1585                 printf(
1586                     "other object type, %d\en",
1587                     attrBuf.common.objType
1588                 );
1589                 break;
1590         }
1591     }
1592 .Pp
1593 .
1594     return err;
1595 }
1596 .Ed
1597 .Pp
1598 .
1599 The following example shows how to deal with variable length attributes.
1600 It assumes that the volume specified by
1601 .Fa path
1602 supports the necessary attributes.
1603 .
1604 .Bd -literal
1605 #include <assert.h>
1606 #include <stdio.h>
1607 #include <stddef.h>
1608 #include <string.h>
1609 #include <sys/attr.h>
1610 #include <sys/errno.h>
1611 #include <unistd.h>
1612 #include <sys/vnode.h>
1613 .Pp
1614 .
1615 typedef struct attrlist attrlist_t;
1616 .Pp
1617 .
1618 struct VolAttrBuf {
1619     u_int32_t       length;
1620     u_int32_t       fileCount;
1621     u_int32_t       dirCount;
1622     attrreference_t mountPointRef;
1623     attrreference_t volNameRef;
1624     char            mountPointSpace[MAXPATHLEN];
1625     char            volNameSpace[MAXPATHLEN];
1626 };
1627 typedef struct VolAttrBuf VolAttrBuf;
1628 .Pp
1629 .
1630 static int VolDemo(const char *path)
1631 {
1632     int             err;
1633     attrlist_t      attrList;
1634     VolAttrBuf      attrBuf;
1635 .Pp
1636 .
1637     memset(&attrList, 0, sizeof(attrList));
1638     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1639     attrList.volattr     =   ATTR_VOL_INFO
1640                            | ATTR_VOL_FILECOUNT
1641                            | ATTR_VOL_DIRCOUNT
1642                            | ATTR_VOL_MOUNTPOINT
1643                            | ATTR_VOL_NAME;
1644 .Pp
1645
1646     err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1647     if (err != 0) {
1648         err = errno;
1649     }
1650 .Pp
1651
1652     if (err == 0) {
1653         assert(attrBuf.length >  offsetof(VolAttrBuf, mountPointSpace));
1654         assert(attrBuf.length <= sizeof(attrBuf));
1655 .Pp
1656
1657         printf("Volume information for %s:\en", path);
1658         printf("ATTR_VOL_FILECOUNT:  %lu\en", attrBuf.fileCount);
1659         printf("ATTR_VOL_DIRCOUNT:   %lu\en", attrBuf.dirCount);
1660         printf(
1661             "ATTR_VOL_MOUNTPOINT: %.*s\en",
1662             (int) attrBuf.mountPointRef.attr_length,
1663             ( ((char *) &attrBuf.mountPointRef)
1664               + attrBuf.mountPointRef.attr_dataoffset )
1665         );
1666         printf(
1667             "ATTR_VOL_NAME:       %.*s\en",
1668             (int) attrBuf.volNameRef.attr_length,
1669             ( ((char *) &attrBuf.volNameRef)
1670               + attrBuf.volNameRef.attr_dataoffset )
1671         );
1672     }
1673 .Pp
1674 .
1675     return err;
1676 }
1677 .Ed
1678 .Pp
1679 .
1680 .Sh SEE ALSO
1681 .
1682 .Xr access 2 ,
1683 .Xr chflags 2 ,
1684 .Xr exchangedata 2 ,
1685 .Xr fcntl 2 ,
1686 .Xr getdirentriesattr 2 ,
1687 .Xr mount 2 ,
1688 .Xr searchfs 2 ,
1689 .Xr setattrlist 2 ,
1690 .Xr stat 2 ,
1691 .Xr statfs 2
1692 .
1693 .Sh HISTORY
1694 A
1695 .Fn getattrlist
1696 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
1697 .