bsd/man/man2/setxattr.2

   1 .\"
   2 .\" Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
   3 .\"
   4 .\" @APPLE_LICENSE_OSREFERENCE_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.  The rights granted to you under the
  10 .\" License may not be used to create, or enable the creation or
  11 .\" redistribution of, unlawful or unlicensed copies of an Apple operating
  12 .\" system, or to circumvent, violate, or enable the circumvention or
  13 .\" violation of, any terms of an Apple operating system software license
  14 .\" agreement.
  15 .\"
  16 .\" Please obtain a copy of the License at
  17 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  18 .\" file.
  19 .\"
  20 .\" The Original Code and all software distributed under the License are
  21 .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25 .\" Please see the License for the specific language governing rights and
  26 .\" limitations under the License.
  27 .\"
  28 .\" @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29 .\"
  30 .Dd Oct 19, 2004
  31 .Dt SETXATTR 2
  32 .Os "Mac OS X"
  33 .Sh NAME
  34 .Nm setxattr,
  35 .Nm fsetxattr
  36 .Nd set an extended attribute value
  37 .Sh SYNOPSIS
  38 .Fd #include <sys/xattr.h>
  39 .Ft int
  40 .Fn setxattr "const char *path" "const char *name" "void *value" "size_t size" "u_int32_t position" "int options"
  41 .Ft int
  42 .Fn fsetxattr "int fd" "const char *name" "void *value" "size_t size" "u_int32_t position" "int options"
  43 .Sh DESCRIPTION
  44 Extended attributes extend the basic attributes associated with files and
  45 directories in the file system.  They are stored as name:data pairs
  46 associated with file system objects (files, directories, symlinks, etc).
  47 .Pp
  48 .Fn setxattr
  49 associates
  50 .Fa name
  51 and
  52 .Fa data
  53 together as an attribute of
  54 .Fa path .
  55 .Pp
  56 An extended attribute's
  57 .Fa name
  58 is a simple NULL-terminated UTF-8 string.
  59 .Fa Value
  60 is a pointer to a data buffer of
  61 .Fa size
  62 bytes containing textual or binary data to be associated with the
  63 extended attribute.
  64 .Fa Position
  65 specifies the offset within the extended attribute.  In the current
  66 implementation, only the resource fork extended attribute makes use of
  67 this argument.  For all others,
  68 .Fa position
  69 is reserved and should be
  70 set to zero.
  71 .Pp
  72 .Fa options
  73 controls how the attribute is set:
  74 .Pp
  75 .Bl -tag -width XATTR_NOFOLLOW
  76 .It Dv XATTR_NOFOLLOW
  77 do not follow symbolic links.
  78 .Fn setxattr
  79 normally sets attributes on the target of
  80 .Fa path
  81 if it is a symbolic link.
  82 With this option,
  83 .Fn setxattr
  84 will act on the link itself.
  85 .It Dv XATTR_CREATE
  86 fail if the named attribute already exists.
  87 .It Dv XATTR_REPLACE
  88 fail if the named attribute does not exist.  Failure to specify
  89 .Dv XATTR_REPLACE
  90 or
  91 .Dv XATTR_CREATE
  92 allows creation and replacement.
  93 .El
  94 .Pp
  95 .Fn fsetxattr
  96 is identical to
  97 .Fn setxattr ,
  98 except that it sets an extended attribute on an open file referenced by
  99 file descriptor
 100 .Fa fd .
 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 removexattr 2 ,
 177 .Xr listxattr 2
 178 .Sh HISTORY
 179 .Fn setxattr
 180 and
 181 .Fn fsetxattr
 182 first appeared in Mac OS X 10.4.