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