bsd/man/man2/setxattr.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 SETXATTR 2
  25 .Os "Mac OS X"
  26 .Sh NAME
  27 .Nm setxattr,
  28 .Nm fsetxattr
  29 .Nd set an extended attribute value
  30 .Sh SYNOPSIS
  31 .Fd #include <sys/xattr.h>
  32 .Ft int
  33 .Fn setxattr "const char *path" "const char *name" "void *value" "size_t size" "u_int32_t position" "int options"
  34 .Ft int
  35 .Fn fsetxattr "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 associated with 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 .Fn setxattr
  42 associates
  43 .Fa name
  44 and
  45 .Fa data
  46 together as an attribute of
  47 .Fa path .
  48 .Pp
  49 An extended attribute's
  50 .Fa name
  51 is a simple NULL-terminated UTF-8 string.
  52 .Fa Value
  53 is a pointer to a data buffer of
  54 .Fa size
  55 bytes containing textual or binary data to be associated with the
  56 extended attribute.
  57 .Fa Position
  58 specifies the offset within the extended attribute.  In the current
  59 implementation, only the resource fork extended attribute makes use of
  60 this argument.  For all others,
  61 .Fa position
  62 is reserved and should be
  63 set to zero.
  64 .Pp
  65 .Fa options
  66 controls how the attribute is set:
  67 .Pp
  68 .Bl -tag -width XATTR_NOFOLLOW
  69 .It Dv XATTR_NOFOLLOW
  70 do not follow symbolic links.
  71 .Fn setxattr
  72 normally sets attributes on the target of
  73 .Fa path
  74 if it is a symbolic link.
  75 With this option,
  76 .Fn setxattr
  77 will act on the link itself.
  78 .It Dv XATTR_CREATE
  79 fail if the named attribute already exists.
  80 .It Dv XATTR_REPLACE
  81 fail if the named attribute does not exist.  Failure to specify
  82 .Dv XATTR_REPLACE
  83 or
  84 .Dv XATTR_CREATE
  85 allows creation and replacement.
  86 .El
  87 .Pp
  88 .Fn fsetxattr
  89 is identical to
  90 .Fn setxattr ,
  91 except that it sets an extended attribute on an open file referenced by
  92 file descriptor
  93 .Fa fd .
  94 .Sh NOTES
  95 On some filesystems, such as
  96 .Dv HFS+ ,
  97 setting the extended attribute
  98 .Dv com.apple.ResourceFork
  99 will update the modification time (``mtime'') of
 100 the file.
 101 .Pp
 102 Due to historical reasons, the
 103 .Dv XATTR_FINDERINFO_NAME
 104 (defined to be
 105 .Dq com.apple.FinderInfo )
 106 extended attribute must be 32 bytes; see the
 107 .Dv ATTR_CMN_FNDRINFO
 108 section in
 109 .Xr getattrlist 2 .
 110 .Pp
 111 The maximum supported size of extended attribute can be found out using
 112 .Xr pathconf 2
 113 with _PC_XATTR_SIZE_BITS option.
 114 .Sh RETURN VALUES
 115 On success, 0 is returned.  On failure, -1 is returned and the global
 116 variable
 117 .Va errno
 118 is set as follows.
 119 .Sh ERRORS
 120 .Bl -tag -width Er
 121 .It Bq Er EEXIST
 122 .Fa options
 123 contains
 124 .Em XATTR_CREATE
 125 and the named attribute already exists.
 126 .It Bq Er ENOATTR
 127 .Fa options
 128 is set to
 129 .Em XATTR_REPLACE
 130 and the named attribute does not exist.
 131 .It Bq Er ENOTSUP
 132 The file system does not support extended attributes or has them disabled.
 133 .It Bq Er EROFS
 134 The file system is mounted read-only.
 135 .It Bq Er ERANGE
 136 The data size of the attribute is out of range (some attributes have size
 137 restrictions).
 138 .It Bq Er EPERM
 139 .\" EFTYPE could be more specific but isn't POSIX
 140 Attributes cannot be associated with this type of object.  For example,
 141 attributes are not allowed for resource forks.
 142 .It Bq Er EINVAL
 143 .Fa name
 144 or
 145 .Fa options
 146 is invalid.
 147 .Fa name
 148 must be valid UTF-8 and
 149 .Fa options
 150 must make sense.
 151 .It Bq Er ENOTDIR
 152 A component of
 153 .Fa path
 154 is not a directory.
 155 .It Bq Er ENAMETOOLONG
 156 .Fa name
 157 exceeded
 158 .Dv XATTR_MAXNAMELEN
 159 UTF-8 bytes, or a component of
 160 .Fa path
 161 exceeded
 162 .Dv NAME_MAX
 163 characters, or the entire
 164 .Fa path
 165 exceeded
 166 .Dv PATH_MAX
 167 characters.
 168 .It Bq Er EACCES
 169 Search permission is denied for a component of
 170 .Fa path
 171 or permission to set the attribute is denied.
 172 .It Bq Er ELOOP
 173 Too many symbolic links were encountered resolving
 174 .Fa path .
 175 .It Bq Er EFAULT
 176 .Fa path
 177 or
 178 .Fa name
 179 points to an invalid address.
 180 .It Bq Er EIO
 181 An I/O error occurred while reading from or writing to the file system.
 182 .It Bq Er E2BIG
 183 The data size of the extended attribute is too large.
 184 .It Bq Er ENOSPC
 185 Not enough space left on the file system.
 186 .El
 187 .Sh SEE ALSO
 188 .Xr getxattr 2 ,
 189 .Xr listxattr 2 ,
 190 .Xr removexattr 2 ,
 191 .Xr pathconf 2
 192 .Sh HISTORY
 193 .Fn setxattr
 194 and
 195 .Fn fsetxattr
 196 first appeared in Mac OS X 10.4.