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 .El
  87 .Pp
  88 .Fn fgetxattr
  89 is identical to
  90 .Fn getxattr ,
  91 except that it retrieves extended attribute data from the open file
  92 referenced by the file descriptor
  93 .Fa fd .
  94 .Sh RETURN VALUES
  95 On success, the size of the extended attribute data is returned.  On
  96 failure, -1 is returned and the global variable
  97 .Va errno
  98 is set as follows.
  99 .Sh ERRORS
 100 .Bl -tag -width Er
 101 .It Bq Er ENOATTR
 102 The extended attribute does not exist.
 103 .It Bq Er ENOTSUP
 104 The file system does not support extended attributes or has the feature
 105 disabled.
 106 .It Bq Er ERANGE
 107 .Fa value
 108 (as indicated by
 109 .Fa size )
 110 is too small to hold the extended attribute data.
 111 .It Bq Er EPERM
 112 The named attribute is not permitted for this type of object.
 113 .It Bq Er EINVAL
 114 .Fa name
 115 is invalid or
 116 .Fa options
 117 has an unsupported bit set.
 118 .It Bq Er EISDIR
 119 .Fa path
 120 or
 121 .Fa fd
 122 do not refer to a regular file and the attribute in question is only
 123 applicable to files.  Similar to EPERM.
 124 .It Bq Er ENOTDIR
 125 A component of
 126 .Fa path 's
 127 prefix is not a directory.
 128 .It Bq Er ENAMETOOLONG
 129 The length of
 130 .Fa name
 131 exceeds
 132 .Dv XATTR_MAXNAMELEN
 133 UTF-8 bytes, or a component of
 134 .Fa path
 135 exceeds
 136 .Dv NAME_MAX
 137 characters, or the entire
 138 .Fa path
 139 exceeds
 140 .Dv PATH_MAX
 141 characters.
 142 .It Bq Er EACCES
 143 Search permission is denied for a component of
 144 .Fa path
 145 or the attribute is not allowed to be read (e.g. an ACL prohibits reading
 146 the attributes of this file).
 147 .It Bq Er ELOOP
 148 Too many symbolic links were encountered in translating the pathname.
 149 .It Bq Er EFAULT
 150 .Fa path
 151 or
 152 .Fa name
 153 points to an invalid address.
 154 .It Bq Er EIO
 155 An I/O error occurred while reading from or writing to the file system.
 156 .El
 157 .Sh SEE ALSO
 158 .Xr listxattr 2 ,
 159 .Xr removexattr 2 ,
 160 .Xr setxattr 2
 161 .Sh HISTORY
 162 .Fn getxattr
 163 and
 164 .Fn fgetxattr
 165 first appeared in Mac OS X 10.4.