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