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 NOTE
  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 .Sh RETURN VALUES
 102 On success, 0 is returned.  On failure, -1 is returned and the global
 103 variable
 104 .Va errno
 105 is set as follows.
 106 .Sh ERRORS
 107 .Bl -tag -width Er
 108 .It Bq Er EEXIST
 109 .Fa options
 110 contains
 111 .Em XATTR_CREATE
 112 and the named attribute already exists.
 113 .It Bq Er ENOATTR
 114 .Fa options
 115 is set to
 116 .Em XATTR_REPLACE
 117 and the named attribute does not exist.
 118 .It Bq Er ENOTSUP
 119 The file system does not support extended attributes or has them disabled.
 120 .It Bq Er EROFS
 121 The file system is mounted read-only.
 122 .It Bq Er ERANGE
 123 The data size of the attribute is out of range (some attributes have size
 124 restrictions).
 125 .It Bq Er EPERM
 126 .\" EFTYPE could be more specific but isn't POSIX
 127 Attributes cannot be associated with this type of object.  For example,
 128 attributes are not allowed for resource forks.
 129 .It Bq Er EINVAL
 130 .Fa name
 131 or
 132 .Fa options
 133 is invalid.
 134 .Fa name
 135 must be valid UTF-8 and
 136 .Fa options
 137 must make sense.
 138 .It Bq Er ENOTDIR
 139 A component of
 140 .Fa path
 141 is not a directory.
 142 .It Bq Er ENAMETOOLONG
 143 .Fa name
 144 exceeded
 145 .Dv XATTR_MAXNAMELEN
 146 UTF-8 bytes, or a component of
 147 .Fa path
 148 exceeded
 149 .Dv NAME_MAX
 150 characters, or the entire
 151 .Fa path
 152 exceeded
 153 .Dv PATH_MAX
 154 characters.
 155 .It Bq Er EACCES
 156 Search permission is denied for a component of
 157 .Fa path
 158 or permission to set the attribute is denied.
 159 .It Bq Er ELOOP
 160 Too many symbolic links were encountered resolving
 161 .Fa path .
 162 .It Bq Er EFAULT
 163 .Fa path
 164 or
 165 .Fa name
 166 points to an invalid address.
 167 .It Bq Er EIO
 168 An I/O error occurred while reading from or writing to the file system.
 169 .It Bq Er E2BIG
 170 The data size of the extended attribute is too large.
 171 .It Bq Er ENOSPC
 172 Not enough space left on the file system.
 173 .El
 174 .Sh SEE ALSO
 175 .Xr getxattr 2 ,
 176 .Xr listxattr 2 ,
 177 .Xr removexattr 2
 178 .Sh HISTORY
 179 .Fn setxattr
 180 and
 181 .Fn fsetxattr
 182 first appeared in Mac OS X 10.4.