bsd/man/man2/getxattr.2

   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
  37 Extended attributes extend the basic attributes of files and
  38 directories in the file system.  They are stored as name:data pairs
  39 associated with file system objects (files, directories, symlinks, etc).
  40 .Pp
  41 The
  42 .Fn getxattr
  43 function retrieves up to
  44 .Fa size
  45 bytes of data from the extended attribute identified by
  46 .Fa name
  47 associated with
  48 .Fa path
  49 into the pre-allocated buffer pointed to by
  50 .Fa value .
  51 The function returns the number of bytes of data retrieved.
  52 .Pp
  53 An extended attribute's
  54 .Fa name
  55 is a simple NULL-terminated UTF-8 string.
  56 .Fa position
  57 specifies an offset within the extended attribute.  In the current
  58 implementation, this argument is only used with the resource fork attribute.
  59 For all other extended attributes, this parameter is reserved and should
  60 be zero.
  61 .Pp
  62 On success,
  63 .Fa value
  64 contains the data associated with
  65 .Fa name .
  66 When
  67 .Fa value
  68 is set to NULL,
  69 .Fn getxattr
  70 returns current size of the named attribute.  This facility can be used
  71 to determine the size of a buffer sufficiently large to hold the data
  72 currently associated with the attribute.
  73 .Pp
  74 .Fa options
  75 specify options for retrieving extended attributes:
  76 .Pp
  77 .Bl -tag -width XATTR_NOFOLLOW
  78 .It Dv XATTR_NOFOLLOW
  79 do not follow symbolic links.
  80 .Fn getxattr
  81 normally returns information from the target of
  82 .Fa path
  83 if it is a symbolic link.  With this option,
  84 .Fn getxattr
  85 will return extended attribute data from the symbolic link instead.
  86 .It Dv XATTR_SHOWCOMPRESSION
  87 .Fn getxattr
  88 and
  89 .Fn fgetxattr
  90 will return HFS Plus Compression extended attribute
  91 .Fa name
  92 (if present) for the file referred to by
  93 .Fa path
  94 or
  95 .Fa fd .
  96 .El
  97 .Pp
  98 .Fn fgetxattr
  99 is identical to
 100 .Fn getxattr ,
 101 except that it retrieves extended attribute data from the open file
 102 referenced by the file descriptor
 103 .Fa fd .
 104 .Sh RETURN VALUES
 105 On success, the size of the extended attribute data is returned.  On
 106 failure, -1 is returned and the global variable
 107 .Va errno
 108 is set as follows.
 109 .Sh ERRORS
 110 .Bl -tag -width Er
 111 .It Bq Er ENOATTR
 112 The extended attribute does not exist.
 113 .It Bq Er ENOTSUP
 114 The file system does not support extended attributes or has the feature
 115 disabled.
 116 .It Bq Er ERANGE
 117 .Fa value
 118 (as indicated by
 119 .Fa size )
 120 is too small to hold the extended attribute data.
 121 .It Bq Er EPERM
 122 The named attribute is not permitted for this type of object.
 123 .It Bq Er EINVAL
 124 .Fa name
 125 is invalid or
 126 .Fa options
 127 has an unsupported bit set.
 128 .It Bq Er EISDIR
 129 .Fa path
 130 or
 131 .Fa fd
 132 do not refer to a regular file and the attribute in question is only
 133 applicable to files.  Similar to EPERM.
 134 .It Bq Er ENOTDIR
 135 A component of
 136 .Fa path 's
 137 prefix is not a directory.
 138 .It Bq Er ENAMETOOLONG
 139 The length of
 140 .Fa name
 141 exceeds
 142 .Dv XATTR_MAXNAMELEN
 143 UTF-8 bytes, or a component of
 144 .Fa path
 145 exceeds
 146 .Dv NAME_MAX
 147 characters, or the entire
 148 .Fa path
 149 exceeds
 150 .Dv PATH_MAX
 151 characters.
 152 .It Bq Er EACCES
 153 Search permission is denied for a component of
 154 .Fa path
 155 or the attribute is not allowed to be read (e.g. an ACL prohibits reading
 156 the attributes of this file).
 157 .It Bq Er ELOOP
 158 Too many symbolic links were encountered in translating the pathname.
 159 .It Bq Er EFAULT
 160 .Fa path
 161 or
 162 .Fa name
 163 points to an invalid address.
 164 .It Bq Er EIO
 165 An I/O error occurred while reading from or writing to the file system.
 166 .El
 167 .Sh SEE ALSO
 168 .Xr listxattr 2 ,
 169 .Xr removexattr 2 ,
 170 .Xr setxattr 2
 171 .Sh HISTORY
 172 .Fn getxattr
 173 and
 174 .Fn fgetxattr
 175 first appeared in Mac OS X 10.4.