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