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 behaviour.
  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 unsigned long
 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 mode_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 unsigned long
 537 containing the number of named attributes of the file system object.
 538 No built-in file systems on Mac OS X currently support named attributes.
 539 .
 540 .It ATTR_CMN_NAMEDATTRLIST
 541 An
 542 .Vt attrreference
 543 structure containing a list of named attributes of the file system object.
 544 No built-in file systems on Mac OS X currently support named attributes.
 545 Because of this, the structure of this attribute's value is not yet defined.
 546 .
 547 .It ATTR_CMN_FLAGS
 548 (read/write) A
 549 .Vt unsigned long
 550 containing file flags.
 551 Equivalent to the
 552 .Fa st_flags
 553 field of the
 554 .Vt stat
 555 structure returned by
 556 .Xr stat 2 .
 557 For more information about these flags, see
 558 .Xr chflags 2 .
 559 .Pp
 560 .
 561 The order that attributes are placed into the attribute buffer
 562 almost invariably matches the order of the attribute mask bit values.
 563 The exception is
 564 .Dv ATTR_CMN_FLAGS .
 565 If its order was based on its bit position, it would be before
 566 the
 567 .Dv ATTR_CMN_NAMEDATTRCOUNT
 568 /
 569 .Dv ATTR_CMN_NAMEDATTRLIST
 570 pair, however,
 571 it is placed in the buffer after them.
 572 .
 573 .It ATTR_CMN_USERACCESS
 574 A
 575 .Vt unsigned long
 576 containing the effective permissions of the current user
 577 (the calling process's effective UID) for this file system object.
 578 You can test for read, write, and execute permission using
 579 .Dv R_OK ,
 580 .Dv W_OK ,
 581 and
 582 .Dv X_OK ,
 583 respectively.  See
 584 .Xr access 2
 585 for more details.
 586 .
 587 .El
 588 .
 589 .Sh VOLUME ATTRIBUTES
 590 .
 591 Volume attributes relate to volumes (that is, mounted file systems).
 592 The following volume attributes are defined.
 593 .
 594 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
 595 .
 596 .It ATTR_VOL_INFO
 597 For reasons that are not at all obvious, you must set
 598 .Dv ATTR_VOL_INFO
 599 in the
 600 .Fa volattr
 601 field if you request any other volume attributes.
 602 This does not result in any attribute data being added to the attribute buffer.
 603 .
 604 .It ATTR_VOL_FSTYPE
 605 A
 606 .Vt unsigned long
 607 containing the file system type.
 608 Equivalent to the
 609 .Fa f_type
 610 field of the
 611 .Vt statfs
 612 structure returned by
 613 .Xr statfs 2 .
 614 Generally not a useful value.
 615 .
 616 .It ATTR_VOL_SIGNATURE
 617 A
 618 .Vt unsigned long
 619 containing the volume signature word.
 620 This value is unique within a given file system type and lets you
 621 distinguish between different volume formats handled by the same file system.
 622 See
 623 .Aq Pa CarbonCore/Files.h
 624 for more details.
 625 .
 626 .It ATTR_VOL_SIZE
 627 An
 628 .Vt off_t
 629 containing the total size of the volume in bytes.
 630 .
 631 .It ATTR_VOL_SPACEFREE
 632 An
 633 .Vt off_t
 634 containing the free space on the volume in bytes.
 635 .
 636 .It ATTR_VOL_SPACEAVAIL
 637 An
 638 .Vt off_t
 639 containing the space, in bytes, on the volume available to non-privileged processes.
 640 This is the free space minus the amount of space reserved by the system to prevent critical
 641 disk exhaustion errors.
 642 Non-privileged programs, like a disk management tool, should use this value to display the
 643 space available to the user.
 644 .Pp
 645 .Dv ATTR_VOL_SPACEAVAIL
 646 is to
 647 .Dv ATTR_VOL_SPACEFREE
 648 as
 649 .Fa f_bavail
 650 is to
 651 .Fa f_bfree
 652 in
 653 .Xr statfs 2 .
 654 .
 655 .It ATTR_VOL_MINALLOCATION
 656 An
 657 .Vt off_t
 658 containing the minimum allocation size on the volume in bytes.
 659 If you create a file containing one byte, it will consume this much space.
 660 .
 661 .It ATTR_VOL_ALLOCATIONCLUMP
 662 An
 663 .Vt off_t
 664 containing the allocation clump size on the volume, in bytes.
 665 As a file is extended, the file system will attempt to allocate
 666 this much space each time in order to reduce fragmentation.
 667 .
 668 .It ATTR_VOL_IOBLOCKSIZE
 669 A
 670 .Vt unsigned long
 671 containing the optimal block size when reading or writing data.
 672 Equivalent to the
 673 .Fa f_iosize
 674 field of the
 675 .Vt statfs
 676 structure returned by
 677 .Xr statfs 2 .
 678 .
 679 .It ATTR_VOL_OBJCOUNT
 680 A
 681 .Vt unsigned long
 682 containing the number of file system objects on the volume.
 683 .
 684 .It ATTR_VOL_FILECOUNT
 685 A
 686 .Vt unsigned long
 687 containing the number of files on the volume.
 688 .
 689 .It ATTR_VOL_DIRCOUNT
 690 A
 691 .Vt unsigned long
 692 containing the number of directories on the volume.
 693 .
 694 .It ATTR_VOL_MAXOBJCOUNT
 695 A
 696 .Vt unsigned long
 697 containing the maximum number of file system objects that can be stored on the volume.
 698 .
 699 .It ATTR_VOL_MOUNTPOINT
 700 An
 701 .Vt attrreference
 702 structure containing the path to the volume's mount point as a
 703 UTF-8 encoded, null terminated C string.
 704 The attribute data length will not be greater than
 705 .Dv MAXPATHLEN .
 706 Equivalent to the
 707 .Fa f_mntonname
 708 field of the
 709 .Vt statfs
 710 structure returned by
 711 .Xr statfs 2 .
 712 .
 713 .It ATTR_VOL_NAME
 714 (read/write) An
 715 .Vt attrreference
 716 structure containing the name of the volume as a
 717 UTF-8 encoded, null terminated C string.
 718 The attribute data length will not be greater than
 719 .Dv NAME_MAX +
 720 1.
 721 .Pp
 722 .
 723 This attribute is only read/write if the
 724 .Dv VOL_CAP_INT_VOL_RENAME
 725 bit is set in the volume capabilities (see below).
 726 .Pp
 727 .
 728 .It ATTR_VOL_MOUNTFLAGS
 729 A
 730 .Vt unsigned long
 731 containing the volume mount flags.
 732 This is a copy of the value passed to the
 733 .Fa flags
 734 parameter of
 735 .Xr mount 2
 736 when the volume was mounted.
 737 Equivalent to the
 738 .Fa f_flags
 739 field of the
 740 .Vt statfs
 741 structure returned by
 742 .Xr statfs 2 .
 743 .
 744 .It ATTR_VOL_MOUNTEDDEVICE
 745 An
 746 .Vt attrreference
 747 structure that returns the same value as the
 748 .Fa f_mntfromname
 749 field of the
 750 .Vt statfs
 751 structure returned by
 752 .Xr statfs 2 .
 753 For local volumes this is the path to the device on which the volume is mounted as a
 754 UTF-8 encoded, null terminated C string.
 755 For network volumes, this is a unique string that identifies the mount.
 756 The attribute data length will not be greater than
 757 .Dv MAXPATHLEN .
 758 .Pp
 759 .
 760 .It ATTR_VOL_ENCODINGSUSED
 761 An
 762 .Vt unsigned long long
 763 containing a bitmap of the text encodings used on this volume.
 764 For more information about this, see the discussion of
 765 .Fa encodingsBitmap
 766 in DTS Technote 1150 "HFS Plus Volume Format".
 767 .
 768 .It ATTR_VOL_CAPABILITIES
 769 A
 770 .Vt vol_capabilities_attr_t
 771 structure describing the optional features supported by this volume.
 772 See below for a discussion of volume capabilities.
 773 .
 774 .It ATTR_VOL_ATTRIBUTES
 775 A
 776 .Vt vol_attributes_attr_t
 777 structure describing the attributes supported by this volume.
 778 This structure is discussed below, along with volume capabilities.
 779 .
 780 .El
 781 .
 782 .Sh DIRECTORY ATTRIBUTES
 783 .
 784 The following directory attributes are defined.
 785 .
 786 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
 787 .
 788 .It ATTR_DIR_LINKCOUNT
 789 A
 790 .Vt unsigned long
 791 containing the number of file system objects in the directory, including
 792 synthetic items such as "." and "..".
 793 For historical reasons, you should not always rely on this value being accurate.
 794 .Pp
 795 If you're implementing a volume format on which this is hard to calculate,
 796 you should not support this attribute.
 797 While it's traditional to return a constant value of 1 in the
 798 .Fa st_nlink
 799 field of the
 800 .Vt stat
 801 structure as returned by
 802 .Xr stat 2 ,
 803 it's not necessary to do this here because there is a
 804 defined way to indicate that you do not support the attribute.
 805 .
 806 .It ATTR_DIR_ENTRYCOUNT
 807 A
 808 .Vt unsigned long
 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 unsigned long
 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 unsigned long
 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 unsigned long
 853 containing the optimal block size when reading or writing this file's data.
 854 .
 855 .It ATTR_FILE_CLUMPSIZE
 856 A
 857 .Vt unsigned long
 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 unsigned long
 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 unsigned long
 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 unsigned long
 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.  The
 981 .Dv ATTR_VOL_CAPABILITIES
 982 attribute returns a
 983 .Vt vol_capabilities_attr_t
 984 structure (shown below) that indicates which features are supported by the volume.
 985 .
 986 .Bd -literal
 987 typedef u_int32_t vol_capabilities_set_t[4];
 988 .Pp
 989 .
 990 #define VOL_CAPABILITIES_FORMAT     0
 991 #define VOL_CAPABILITIES_INTERFACES 1
 992 #define VOL_CAPABILITIES_RESERVED1  2
 993 #define VOL_CAPABILITIES_RESERVED2  3
 994 .Pp
 995 .
 996 typedef struct vol_capabilities_attr {
 997     vol_capabilities_set_t capabilities;
 998     vol_capabilities_set_t valid;
 999 } vol_capabilities_attr_t;
1000 .Ed
1001 .Pp
1002 .
1003 The structure contains two fields,
1004 .Fa capabilities
1005 and
1006 .Fa valid .
1007 Each consists of an array of four elements.
1008 The arrays are indexed by the following values.
1009 .
1010 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1011 .
1012 .It VOL_CAPABILITIES_FORMAT
1013 This element contains information about the volume format.
1014 See
1015 .Dv VOL_CAP_FMT_PERSISTENTOBJECTIDS
1016 and so on, below.
1017 .
1018 .It VOL_CAPABILITIES_INTERFACES
1019 This element contains information about which optional functions are
1020 supported by the volume format implementation.
1021 See
1022 .Dv VOL_CAP_INT_SEARCHFS
1023 and so on, below.
1024 .
1025 .It VOL_CAPABILITIES_RESERVED1
1026 Reserved.
1027 A file system implementation should set this element to zero.
1028 A client program should ignore this element.
1029 .
1030 .It VOL_CAPABILITIES_RESERVED2
1031 Reserved.
1032 A file system implementation should set this element to zero.
1033 A client program should ignore this element.
1034 .
1035 .El
1036 .Pp
1037 .
1038 The
1039 .Fa valid
1040 field contains bit sets that indicate which flags are known to the volume format
1041 implementation.
1042 Each bit indicates whether the contents of the corresponding bit in the
1043 .Fa capabilities
1044 field is valid.
1045 .Pp
1046 .
1047 The
1048 .Fa capabilities
1049 field contains bit sets that indicate whether a particular feature is implemented
1050 by this volume format.
1051 .Pp
1052 .
1053 The following bits are defined in the first element (indexed by
1054 .Dv VOL_CAPABILITIES_FORMAT )
1055 of the
1056 .Fa capabilities
1057 and
1058 .Fa valid
1059 fields of the
1060 .Vt vol_capabilities_attr_t
1061 structure.
1062 .
1063 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1064 .
1065 .It VOL_CAP_FMT_PERSISTENTOBJECTIDS
1066 If this bit is set the volume format supports persistent object identifiers
1067 and can look up file system objects by their IDs.
1068 See
1069 .Dv ATTR_CMN_OBJPERMANENTID
1070 for details about how to obtain these identifiers.
1071 .
1072 .It VOL_CAP_FMT_SYMBOLICLINKS
1073 If this bit is set the volume format supports symbolic links.
1074 .
1075 .It VOL_CAP_FMT_HARDLINKS
1076 If this bit is set the volume format supports hard links.
1077 .
1078 .It VOL_CAP_FMT_JOURNAL
1079 If this bit is set the volume format supports a journal used to
1080 speed recovery in case of unplanned restart (such as a power outage
1081 or crash).
1082 This does not necessarily mean the volume is actively using a journal.
1083 .Pp
1084 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1085 .
1086 .It VOL_CAP_FMT_JOURNAL_ACTIVE
1087 If this bit is set the volume is currently using a journal for
1088 speedy recovery after an unplanned restart.
1089 This bit can be set only if
1090 .Dv VOL_CAP_FMT_JOURNAL
1091 is also set.
1092 .Pp
1093 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1094 .
1095 .It VOL_CAP_FMT_NO_ROOT_TIMES
1096 If this bit is set the volume format does not store reliable times for
1097 the root directory, so you should not depend on them to detect changes,
1098 identify volumes across unmount/mount, and so on.
1099 .Pp
1100 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1101 .
1102 .It VOL_CAP_FMT_SPARSE_FILES
1103 If this bit is set the volume format supports sparse files,
1104 that is, files which can have 'holes' that have never been written
1105 to, and thus do not consume space on disk.
1106 A sparse file may have an allocated size on disk that is less than its logical length (that is,
1107 .Dv ATTR_FILE_ALLOCSIZE
1108 <
1109 .Dv ATTR_FILE_TOTALSIZE ).
1110 .
1111 .Pp
1112 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1113 .
1114 .It VOL_CAP_FMT_ZERO_RUNS
1115 For security reasons, parts of a file (runs) that have never been
1116 written to must appear to contain zeroes.
1117 When this bit is set, the volume keeps track of allocated but unwritten
1118 runs of a file so that it can substitute zeroes without actually
1119 writing zeroes to the media.
1120 This provides performance similar to sparse files, but not the space savings.
1121 .Pp
1122 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1123 .
1124 .It VOL_CAP_FMT_CASE_SENSITIVE
1125 If this bit is set the volume format treats upper and lower case
1126 characters in file and directory names as different.
1127 Otherwise an upper case character is equivalent to a lower case character,
1128 and you can't have two names that differ solely in the case of
1129 the characters.
1130 .Pp
1131 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1132 .
1133 .It VOL_CAP_FMT_CASE_PRESERVING
1134 If this bit is set the volume format preserves the case of
1135 file and directory names.
1136 Otherwise the volume may change the case of some characters
1137 (typically making them all upper or all lower case).
1138 A volume that sets
1139 .Dv VOL_CAP_FMT_CASE_SENSITIVE
1140 must also set
1141 .Dv VOL_CAP_FMT_CASE_PRESERVING .
1142 .Pp
1143 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1144 .
1145 .It VOL_CAP_FMT_FAST_STATFS
1146 This bit is used as a hint to upper layers (specifically the Carbon File Manager) to
1147 indicate that
1148 .Xr statfs 2
1149 is fast enough that its results need not be cached by the caller.
1150 A volume format implementation that caches the
1151 .Xr statfs 2
1152 information in memory should set this bit.
1153 An implementation that must always read from disk or always perform a network
1154 transaction to satisfy
1155 .Xr statfs 2
1156 should not set this bit.
1157 .Pp
1158 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1159 .
1160 .It VOL_CAP_FMT_2TB_FILESIZE
1161 If this bit is set the volume format supports file
1162 sizes upto 2TB.  This bit does not necessarily mean that the file
1163 system does not support file size more than 2TB.   This bit does
1164 not mean that the currently available space on the volume is 2TB.
1165 .Pp
1166 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1167 .
1168 .El
1169 .Pp
1170 .
1171 The following bits are defined in the second element (indexed by
1172 .Dv VOL_CAPABILITIES_INTERFACES )
1173 of the
1174 .Fa capabilities
1175 and
1176 .Fa valid
1177 fields of the
1178 .Vt vol_capabilities_attr_t
1179 structure.
1180 .
1181 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1182 .
1183 .It VOL_CAP_INT_SEARCHFS
1184 If this bit is set the volume format implementation supports
1185 .Xr searchfs 2 .
1186 .
1187 .It VOL_CAP_INT_ATTRLIST
1188 If this bit is set the volume format implementation supports
1189 .Fn getattrlist
1190 and
1191 .Xr setattrlist 2 .
1192 .
1193 .It VOL_CAP_INT_NFSEXPORT
1194 If this bit is set the volume format implementation allows this volume to be exported via NFS.
1195 .
1196 .It VOL_CAP_INT_READDIRATTR
1197 If this bit is set the volume format implementation supports
1198 .Xr getdirentriesattr 2 .
1199 .
1200 .It VOL_CAP_INT_EXCHANGEDATA
1201 If this bit is set the volume format implementation supports
1202 .Xr exchangedata 2 .
1203 .Pp
1204 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1205 .
1206 .It VOL_CAP_INT_COPYFILE
1207 If this bit is set the volume format implementation supports the (private and undocumented)
1208 copyfile() function.
1209 .Pp
1210 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1211 .
1212 .It VOL_CAP_INT_ALLOCATE
1213 If this bit is set the volume format implementation supports the
1214 .Dv F_PREALLOCATE
1215 selector of
1216 .Xr fcntl 2 .
1217 .Pp
1218 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1219 .
1220 .It VOL_CAP_INT_VOL_RENAME
1221 If this bit is set the volume format implementation allows you to
1222 modify the volume name using
1223 .Xr setattrlist 2 .
1224 .Pp
1225 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1226 .
1227 .It VOL_CAP_INT_ADVLOCK
1228 If this bit is set the volume format implementation supports
1229 advisory locking, that is, the
1230 .Dv F_GETLK ,
1231 .Dv F_SETLK ,
1232 and
1233 .Dv F_SETLKW
1234 selectors to
1235 .Xr fcntl 2 .
1236 .Pp
1237 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1238 .
1239 .It VOL_CAP_INT_FLOCK
1240 If this bit is set the volume format implementation supports
1241 whole file locks.
1242 This includes
1243 .Xr flock 2
1244 and the
1245 .Dv O_EXLOCK
1246 and
1247 .Dv O_SHLOCK
1248 flags to
1249 .Xr open 2 .
1250 .Pp
1251 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1252 .
1253 .El
1254 .Pp
1255 .
1256 .\" vol_attributes_attr_t
1257 .
1258 A volume can also report which attributes it supports.
1259 This information is returned by the
1260 .Dv ATTR_VOL_ATTRIBUTES
1261 attribute, which returns a
1262 .Vt vol_attributes_attr_t
1263 structure (shown below).
1264 .
1265 .Bd -literal
1266 typedef struct attribute_set {
1267     attrgroup_t commonattr; /* common attribute group */
1268     attrgroup_t volattr;    /* volume attribute group */
1269     attrgroup_t dirattr;    /* directory attribute group */
1270     attrgroup_t fileattr;   /* file attribute group */
1271     attrgroup_t forkattr;   /* fork attribute group */
1272 } attribute_set_t;
1273 .Pp
1274 .
1275 typedef struct vol_attributes_attr {
1276     attribute_set_t validattr;
1277     attribute_set_t nativeattr;
1278 } vol_attributes_attr_t;
1279 .Ed
1280 .Pp
1281 .
1282 The
1283 .Fa validattr
1284 field consists of a number of bit sets that indicate whether an attribute is
1285 supported by the volume format implementation.
1286 The
1287 .Fa nativeattr
1288 is similar except that the bit sets indicate whether an attribute is supported
1289 natively by the volume format.
1290 An attribute is supported natively if the volume format implementation does not have to do
1291 any complex conversions to access the attribute.
1292 For example, a volume format might support persistent object identifiers, but
1293 doing so requires a complex table lookup that is not part of the core volume
1294 format.
1295 In that case, the
1296 .Dv ATTR_VOL_ATTRIBUTES
1297 attribute would return
1298 .Dv ATTR_CMN_OBJPERMANENTID
1299 set in the
1300 .Fa validattr
1301 field of the
1302 .Vt vol_attributes_attr_t ,
1303 but not in the
1304 .Fa nativeattr
1305 field.
1306 .
1307 .Sh RETURN VALUES
1308 Upon successful completion a value of 0 is returned.
1309 Otherwise, a value of -1 is returned and
1310 .Va errno
1311 is set to indicate the error.
1312 .
1313 .Sh COMPATIBILITY
1314 Not all volumes support
1315 .Fn getattrlist .
1316 The best way to test whether a volume supports this function is to
1317 simply call it and check the error result.
1318 .Fn getattrlist
1319 will return
1320 .Dv ENOTSUP
1321 if it is not supported on a particular volume.
1322 .Pp
1323 .
1324 The
1325 .Fn getattrlist
1326 function has been undocumented for more than two years.
1327 In that time a number of volume format implementations have been created without
1328 a proper specification for the behaviour of this routine.
1329 You may encounter volume format implementations with slightly different
1330 behaviour than what is described here.
1331 Your program is expected to be tolerant of this variant behaviour.
1332 .Pp
1333 .
1334 If you're implementing a volume format that supports
1335 .Fn getattrlist ,
1336 you should be careful to support the behaviour specified by this document.
1337 .
1338 .Sh ERRORS
1339 .Fn getattrlist
1340 will fail if:
1341 .Bl -tag -width Er
1342 .
1343 .It Bq Er ENOTSUP
1344 The volume does not support
1345 .Fn getattrlist .
1346 .
1347 .It Bq Er ENOTDIR
1348 A component of the path prefix is not a directory.
1349 .
1350 .It Bq Er ENAMETOOLONG
1351 A component of a path name exceeded
1352 .Dv NAME_MAX
1353 characters, or an entire path name exceeded
1354 .Dv PATH_MAX
1355 characters.
1356 .
1357 .It Bq Er ENOENT
1358 The file system object does not exist.
1359 .
1360 .It Bq Er EACCES
1361 Search permission is denied for a component of the path prefix.
1362 .
1363 .It Bq Er ELOOP
1364 Too many symbolic links were encountered in translating the pathname.
1365 .
1366 .It Bq Er EFAULT
1367 .Fa path ,
1368 .Fa attrList
1369 or
1370 .Em attrBuf
1371 points to an invalid address.
1372 .
1373 .It Bq Er EINVAL
1374 The
1375 .Fa bitmapcount
1376 field of
1377 .Fa attrList
1378 is not
1379 .Dv ATTR_BIT_MAP_COUNT .
1380 .
1381 .It Bq Er EINVAL
1382 You requested an invalid attribute.
1383 .
1384 .It Bq Er EINVAL
1385 You requested an attribute that is not supported for this file system object.
1386 .
1387 .It Bq Er EINVAL
1388 You requested volume attributes and directory or file attributes.
1389 .
1390 .It Bq Er EINVAL
1391 You requested volume attributes but
1392 .Fa path
1393 does not reference the root of the volume.
1394 .
1395 .It Bq Er EROFS
1396 The volume is read-only but must be modified in order to return this attribute.
1397 .
1398 .It Bq Er EIO
1399 An I/O error occurred while reading from or writing to the file system.
1400 .El
1401 .Pp
1402 .
1403 .Sh CAVEATS
1404 .
1405 If you request any volume attributes, you must set
1406 .Dv ATTR_VOL_INFO
1407 in the
1408 .Fa volattr
1409 field, even though it generates no result in the attribute buffer.
1410 .Pp
1411 .
1412 The order that attributes are stored in the attribute buffer almost
1413 invariably matches the order of attribute mask bit values.
1414 For example,
1415 .Dv ATTR_CMN_NAME
1416 (0x00000001) comes before
1417 .Dv ATTR_CMN_DEVID
1418 (0x00000002) because its value is smaller.
1419 However, you can not rely on this ordering because there is one key exception:
1420 .Dv ATTR_CMN_FLAGS
1421 is placed after the
1422 .Dv ATTR_CMN_NAMEDATTRCOUNT
1423 /
1424 .Dv ATTR_CMN_NAMEDATTRLIST
1425 pair, even though its bit position indicates that it should come before.
1426 This is due to a bug in an early version of Mac OS X that can't be fixed for
1427 binary compatibility reasons.
1428 When ordering attributes, you should always use the order in which they
1429 are described above.
1430 .Pp
1431 .
1432 For more caveats, see also the compatibility notes above.
1433 .
1434 .Sh EXAMPLES
1435 .
1436 The following code prints the file type and creator of a file,
1437 assuming that the volume supports the required attributes.
1438 .
1439 .Bd -literal
1440 #include <assert.h>
1441 #include <stdio.h>
1442 #include <string.h>
1443 #include <sys/attr.h>
1444 #include <sys/errno.h>
1445 #include <unistd.h>
1446 #include <sys/vnode.h>
1447 .Pp
1448 .
1449 typedef struct attrlist attrlist_t;
1450 .Pp
1451 .
1452 struct FInfoAttrBuf {
1453     unsigned long   length;
1454     fsobj_type_t    objType;
1455     char            finderInfo[32];
1456 };
1457 typedef struct FInfoAttrBuf FInfoAttrBuf;
1458 .Pp
1459 .
1460 static int FInfoDemo(const char *path)
1461 {
1462     int             err;
1463     attrlist_t      attrList;
1464     FInfoAttrBuf    attrBuf;
1465 .Pp
1466 .
1467     memset(&attrList, 0, sizeof(attrList));
1468     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1469     attrList.commonattr  = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1470 .Pp
1471
1472     err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1473     if (err != 0) {
1474         err = errno;
1475     }
1476 .Pp
1477
1478     if (err == 0) {
1479         assert(attrBuf.length == sizeof(attrBuf));
1480 .Pp
1481
1482         printf("Finder information for %s:\en", path);
1483         switch (attrBuf.objType) {
1484             case VREG:
1485                 printf("file type    = '%.4s'\en", &attrBuf.finderInfo[0]);
1486                 printf("file creator = '%.4s'\en", &attrBuf.finderInfo[4]);
1487                 break;
1488             case VDIR:
1489                 printf("directory\en");
1490                 break;
1491             default:
1492                 printf("other object type, %d\en", attrBuf.objType);
1493                 break;
1494         }
1495     }
1496 .Pp
1497 .
1498     return err;
1499 }
1500 .Ed
1501 .Pp
1502 .
1503 The following code is an alternative implementation that uses nested structures
1504 to group the related attributes.
1505 .
1506 .Bd -literal
1507 #include <assert.h>
1508 #include <stdio.h>
1509 #include <stddef.h>
1510 #include <string.h>
1511 #include <sys/attr.h>
1512 #include <sys/errno.h>
1513 #include <unistd.h>
1514 #include <sys/vnode.h>
1515 .Pp
1516 .
1517 typedef struct attrlist attrlist_t;
1518 .Pp
1519 .
1520 struct FInfo2CommonAttrBuf {
1521     fsobj_type_t    objType;
1522     char            finderInfo[32];
1523 };
1524 typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
1525 .Pp
1526 .
1527 struct FInfo2AttrBuf {
1528     unsigned long       length;
1529     FInfo2CommonAttrBuf common;
1530 };
1531 typedef struct FInfo2AttrBuf FInfo2AttrBuf;
1532 .Pp
1533 .
1534 static int FInfo2Demo(const char *path)
1535 {
1536     int             err;
1537     attrlist_t      attrList;
1538     FInfo2AttrBuf   attrBuf;
1539 .Pp
1540 .
1541     memset(&attrList, 0, sizeof(attrList));
1542     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1543     attrList.commonattr  = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1544 .Pp
1545 .
1546     err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1547     if (err != 0) {
1548         err = errno;
1549     }
1550 .Pp
1551 .
1552     if (err == 0) {
1553         assert(attrBuf.length == sizeof(attrBuf));
1554 .Pp
1555 .
1556         printf("Finder information for %s:\en", path);
1557         switch (attrBuf.common.objType) {
1558             case VREG:
1559                 printf(
1560                     "file type    = '%.4s'\en",
1561                     &attrBuf.common.finderInfo[0]
1562                 );
1563                 printf(
1564                     "file creator = '%.4s'\en",
1565                     &attrBuf.common.finderInfo[4]
1566                 );
1567                 break;
1568             case VDIR:
1569                 printf("directory\en");
1570                 break;
1571             default:
1572                 printf(
1573                     "other object type, %d\en",
1574                     attrBuf.common.objType
1575                 );
1576                 break;
1577         }
1578     }
1579 .Pp
1580 .
1581     return err;
1582 }
1583 .Ed
1584 .Pp
1585 .
1586 The following example shows how to deal with variable length attributes.
1587 It assumes that the volume specified by
1588 .Fa path
1589 supports the necessary attributes.
1590 .
1591 .Bd -literal
1592 #include <assert.h>
1593 #include <stdio.h>
1594 #include <stddef.h>
1595 #include <string.h>
1596 #include <sys/attr.h>
1597 #include <sys/errno.h>
1598 #include <unistd.h>
1599 #include <sys/vnode.h>
1600 .Pp
1601 .
1602 typedef struct attrlist attrlist_t;
1603 .Pp
1604 .
1605 struct VolAttrBuf {
1606     unsigned long   length;
1607     unsigned long   fileCount;
1608     unsigned long   dirCount;
1609     attrreference_t mountPointRef;
1610     attrreference_t volNameRef;
1611     char            mountPointSpace[MAXPATHLEN];
1612     char            volNameSpace[MAXPATHLEN];
1613 };
1614 typedef struct VolAttrBuf VolAttrBuf;
1615 .Pp
1616 .
1617 static int VolDemo(const char *path)
1618 {
1619     int             err;
1620     attrlist_t      attrList;
1621     VolAttrBuf      attrBuf;
1622 .Pp
1623 .
1624     memset(&attrList, 0, sizeof(attrList));
1625     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1626     attrList.volattr     =   ATTR_VOL_INFO
1627                            | ATTR_VOL_FILECOUNT
1628                            | ATTR_VOL_DIRCOUNT
1629                            | ATTR_VOL_MOUNTPOINT
1630                            | ATTR_VOL_NAME;
1631 .Pp
1632
1633     err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1634     if (err != 0) {
1635         err = errno;
1636     }
1637 .Pp
1638
1639     if (err == 0) {
1640         assert(attrBuf.length >  offsetof(VolAttrBuf, mountPointSpace));
1641         assert(attrBuf.length <= sizeof(attrBuf));
1642 .Pp
1643
1644         printf("Volume information for %s:\en", path);
1645         printf("ATTR_VOL_FILECOUNT:  %lu\en", attrBuf.fileCount);
1646         printf("ATTR_VOL_DIRCOUNT:   %lu\en", attrBuf.dirCount);
1647         printf(
1648             "ATTR_VOL_MOUNTPOINT: %.*s\en",
1649             (int) attrBuf.mountPointRef.attr_length,
1650             ( ((char *) &attrBuf.mountPointRef)
1651               + attrBuf.mountPointRef.attr_dataoffset )
1652         );
1653         printf(
1654             "ATTR_VOL_NAME:       %.*s\en",
1655             (int) attrBuf.volNameRef.attr_length,
1656             ( ((char *) &attrBuf.volNameRef)
1657               + attrBuf.volNameRef.attr_dataoffset )
1658         );
1659     }
1660 .Pp
1661 .
1662     return err;
1663 }
1664 .Ed
1665 .Pp
1666 .
1667 .Sh SEE ALSO
1668 .
1669 .Xr access 2 ,
1670 .Xr chflags 2 ,
1671 .Xr exchangedata 2 ,
1672 .Xr fcntl 2 ,
1673 .Xr getdirentriesattr 2 ,
1674 .Xr mount 2 ,
1675 .Xr searchfs 2 ,
1676 .Xr setattrlist 2 ,
1677 .Xr stat 2 ,
1678 .Xr statfs 2
1679 .
1680 .Sh HISTORY
1681 A
1682 .Fn getattrlist
1683 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
1684 .