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