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