1.\" 2.\" Copyright (c) 2004 Apple Computer, Inc. All rights reserved. 3.\" 4.\" @APPLE_LICENSE_HEADER_START@ 5.\" 6.\" This file contains Original Code and/or Modifications of Original Code 7.\" as defined in and that are subject to the Apple Public Source License 8.\" Version 2.0 (the 'License'). You may not use this file except in 9.\" compliance with the License. Please obtain a copy of the License at 10.\" http://www.opensource.apple.com/apsl/ and read it before using this 11.\" file. 12.\" 13.\" The Original Code and all software distributed under the License are 14.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18.\" Please see the License for the specific language governing rights and 19.\" limitations under the License. 20.\" 21.\" @APPLE_LICENSE_HEADER_END@ 22.\" 23.Dd Oct 19, 2004 24.Dt GETXATTR 2 25.Os "Mac OS X" 26.Sh NAME 27.Nm getxattr, 28.Nm fgetxattr 29.Nd get an extended attribute value 30.Sh SYNOPSIS 31.Fd #include <sys/xattr.h> 32.Ft ssize_t 33.Fn getxattr "const char *path" "const char *name" "void *value" "size_t size" "u_int32_t position" "int options" 34.Ft ssize_t 35.Fn fgetxattr "int fd" "const char *name" "void *value" "size_t size" "u_int32_t position" "int options" 36.Sh DESCRIPTION 37Extended attributes extend the basic attributes of files and 38directories in the file system. They are stored as name:data pairs 39associated with file system objects (files, directories, symlinks, etc). 40.Pp 41The 42.Fn getxattr 43function retrieves up to 44.Fa size 45bytes of data from the extended attribute identified by 46.Fa name 47associated with 48.Fa path 49into the pre-allocated buffer pointed to by 50.Fa value . 51The function returns the number of bytes of data retrieved. 52.Pp 53An extended attribute's 54.Fa name 55is a simple NULL-terminated UTF-8 string. 56.Fa position 57specifies an offset within the extended attribute. In the current 58implementation, this argument is only used with the resource fork attribute. 59For all other extended attributes, this parameter is reserved and should 60be zero. 61.Pp 62On success, 63.Fa value 64contains the data associated with 65.Fa name . 66When 67.Fa value 68is set to NULL, 69.Fn getxattr 70returns current size of the named attribute. This facility can be used 71to determine the size of a buffer sufficiently large to hold the data 72currently associated with the attribute. 73.Pp 74.Fa options 75specify options for retrieving extended attributes: 76.Pp 77.Bl -tag -width XATTR_NOFOLLOW 78.It Dv XATTR_NOFOLLOW 79do not follow symbolic links. 80.Fn getxattr 81normally returns information from the target of 82.Fa path 83if it is a symbolic link. With this option, 84.Fn getxattr 85will return extended attribute data from the symbolic link instead. 86.It Dv XATTR_NOFOLLOW_ANY 87do not follow any symbolic links encountered during pathname resolution. An 88error is returned if a symlink is encountered before the last component of path. 89.It Dv XATTR_SHOWCOMPRESSION 90.Fn getxattr 91and 92.Fn fgetxattr 93will return HFS Plus Compression extended attribute 94.Fa name 95(if present) for the file referred to by 96.Fa path 97or 98.Fa fd . 99.El 100.Pp 101.Fn fgetxattr 102is identical to 103.Fn getxattr , 104except that it retrieves extended attribute data from the open file 105referenced by the file descriptor 106.Fa fd . 107.Sh RETURN VALUES 108On success, the size of the extended attribute data is returned. On 109failure, -1 is returned and the global variable 110.Va errno 111is set as follows. 112.Sh ERRORS 113.Bl -tag -width Er 114.It Bq Er ENOATTR 115The extended attribute does not exist. 116.It Bq Er ENOTSUP 117The file system does not support extended attributes or has the feature 118disabled. 119.It Bq Er ERANGE 120.Fa value 121(as indicated by 122.Fa size ) 123is too small to hold the extended attribute data. 124.It Bq Er EPERM 125The named attribute is not permitted for this type of object. 126.It Bq Er EINVAL 127.Fa name 128is invalid or 129.Fa options 130has an unsupported bit set. 131.It Bq Er EINVAL 132XATTR_NOFOLLOW or XATTR_NOFOLLOW_ANY option was passed in 133.Fn fgetxattr . 134.It Bq Er EISDIR 135.Fa path 136or 137.Fa fd 138do not refer to a regular file and the attribute in question is only 139applicable to files. Similar to EPERM. 140.It Bq Er ENOTDIR 141A component of 142.Fa path 's 143prefix is not a directory. 144.It Bq Er ENAMETOOLONG 145The length of 146.Fa name 147exceeds 148.Dv XATTR_MAXNAMELEN 149UTF-8 bytes, or a component of 150.Fa path 151exceeds 152.Dv NAME_MAX 153characters, or the entire 154.Fa path 155exceeds 156.Dv PATH_MAX 157characters. 158.It Bq Er EACCES 159Search permission is denied for a component of 160.Fa path 161or the attribute is not allowed to be read (e.g. an ACL prohibits reading 162the attributes of this file). 163.It Bq Er ELOOP 164Too many symbolic links were encountered in translating the pathname. 165.It Bq Er ELOOP 166If XATTR_NOFOLLOW_ANY option was passed and a symbolic link was encountered in 167translating the pathname. 168.It Bq Er EFAULT 169.Fa path 170or 171.Fa name 172points to an invalid address. 173.It Bq Er EIO 174An I/O error occurred while reading from or writing to the file system. 175.El 176.Sh SEE ALSO 177.Xr listxattr 2 , 178.Xr removexattr 2 , 179.Xr setxattr 2 180.Sh HISTORY 181.Fn getxattr 182and 183.Fn fgetxattr 184first appeared in Mac OS X 10.4. 185