man/man3/attr_set.3

   1 .\" Copyright (C) 2001, 2002, 2003, 2006 Silicon Graphics, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual.  If not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\"
  23 .TH ATTR_SET 3 "Extended Attributes" "Dec 2001" "XFS Compatibility API"
  24 .SH NAME
  25 attr_set, attr_setf \- set the value of a user attribute of a filesystem object
  26 .SH C SYNOPSIS
  27 .PP
  28 .sp
  29 .nf
  30 .B #include <attr/attributes.h>
  31 .sp
  32 .B "int attr_set (const char *\f2path\f3, const char *\f2attrname\f3, "
  33 .B "              const char *\f2attrvalue\f3, const int \f2valuelength\f3,"
  34 .B "              int \f2flags\f3);"
  35 .PP
  36 .B "int attr_setf (int \f2fd\f3, const char *\f2attrname\f3, "
  37 .B "               const char *\f2attrvalue\f3, const int \f2valuelength\f3,"
  38 .B "               int \f2flags\f3);"
  39 .Op
  40 .SH DESCRIPTION
  41 The
  42 .B attr_set
  43 and
  44 .B attr_setf
  45 functions provide a way to create attributes and set/change their values.
  46 .P
  47 .I Path\^
  48 points to a path name for a filesystem object, and
  49 .I fd\^
  50 refers to the file descriptor associated with a file.
  51 If the attribute
  52 .I attrname
  53 does not exist, an attribute with the given name and value will be created
  54 and associated with that indicated filesystem object.
  55 If an attribute with that name already exists on that filesystem object,
  56 the existing value is replaced with the new value given in this call.
  57 The new attribute value is copied from the
  58 .I attrvalue
  59 buffer for a total of
  60 .I valuelength
  61 bytes.
  62 The
  63 .I flags
  64 argument can contain the following symbols bitwise OR'ed together:
  65 .TP
  66 .SM
  67 \%ATTR_ROOT
  68 Look for
  69 .I attrname
  70 in the
  71 .B root
  72 address space, not in the
  73 .B user
  74 address space.
  75 (limited to use by super-user only)
  76 .TP
  77 .SM
  78 \%ATTR_DONTFOLLOW
  79 Do not follow symbolic links when resolving a
  80 .I path
  81 on an
  82 .B attr_set
  83 function call.
  84 The default is to follow symbolic links.
  85 .TP
  86 .SM
  87 \%ATTR_CREATE
  88 Return an error (EEXIST) if an attribute of the given name
  89 already exists on the indicated filesystem object,
  90 otherwise create an attribute with the given name and value.
  91 This flag is used to implement a pure create operation,
  92 without this flag
  93 .B attr_set
  94 will create the attribute if it does not already exist.
  95 An error (EINVAL) will be returned if both ATTR_CREATE and ATTR_REPLACE
  96 are set in the same call.
  97 .TP
  98 .SM
  99 \%ATTR_REPLACE
 100 Return an error (ENOATTR) if an attribute of the given name
 101 does not already exist on the indicated filesystem object,
 102 otherwise replace the existing attribute\'s value with the given value.
 103 This flag is used to implement a pure replacement operation,
 104 without this flag
 105 .B attr_set
 106 will create the attribute if it does not already exist.
 107 An error (EINVAL) will be returned if both ATTR_CREATE and ATTR_REPLACE
 108 are set in the same call.
 109 .PP
 110 .B attr_set
 111 will fail if one or more of the following are true:
 112 .TP 17
 113 .SM
 114 \%[ENOATTR]
 115 The attribute name given is not associated with the indicated
 116 filesystem object and the ATTR_REPLACE flag bit was set.
 117 .TP
 118 .SM
 119 \%[E2BIG]
 120 The value of the given attribute is too large, it exceeds the
 121 maximum allowable size of an attribute value.
 122 .TP
 123 .SM
 124 \%[EEXIST]
 125 The attribute name given is already associated with the indicated
 126 filesystem object and the ATTR_CREATE flag bit was set.
 127 .TP
 128 .SM
 129 \%[ENOENT]
 130 The named file does not exist.
 131 .TP
 132 .SM
 133 \%[EPERM]
 134 The effective user
 135 .SM ID
 136 does not match the owner of the file
 137 and the effective user
 138 .SM ID
 139 is not super-user.
 140 .TP
 141 .SM
 142 \%[ENOTDIR]
 143 A component of the
 144 path prefix
 145 is not a directory.
 146 .TP
 147 .SM
 148 \%[EACCES]
 149 Search permission is denied on a
 150 component of the
 151 path prefix.
 152 .TP
 153 .SM
 154 \%[EINVAL]
 155 A bit was set in the
 156 .I flag
 157 argument that is not defined for this system call,
 158 or both the ATTR_CREATE and ATTR_REPLACE flags bits were set.
 159 .TP
 160 .SM
 161 \%[EFAULT]
 162 .I Path,
 163 .I attrname,
 164 or
 165 .I attrvalue
 166 points outside the allocated address space of the process.
 167 .TP
 168 .SM
 169 \%[ELOOP]
 170 A path name lookup involved too many symbolic links.
 171 .TP
 172 .SM
 173 \%[ENAMETOOLONG]
 174 The length of
 175 .I path
 176 exceeds
 177 .SM
 178 .RI { MAXPATHLEN },
 179 or a pathname component is longer than
 180 .SM
 181 .RI { MAXNAMELEN }.
 182 .PP
 183 .B attr_setf\^
 184 will fail if:
 185 .TP 15
 186 .SM
 187 \%[ENOATTR]
 188 The attribute name given is not associated with the indicated
 189 filesystem object and the ATTR_REPLACE flag bit was set.
 190 .TP
 191 .SM
 192 \%[E2BIG]
 193 The value of the given attribute is too large, it exceeds the
 194 maximum allowable size of an attribute value.
 195 .TP
 196 .SM
 197 \%[EEXIST]
 198 The attribute name given is already associated with the indicated
 199 filesystem object and the ATTR_CREATE flag bit was set.
 200 .TP
 201 .SM
 202 \%[EINVAL]
 203 A bit was set in the
 204 .I flag
 205 argument that is not defined for this system call,
 206 or both the ATTR_CREATE and ATTR_REPLACE flags bits were set, or
 207 .I fd\^
 208 refers to a socket, not a file.
 209 .TP
 210 .SM
 211 \%[EFAULT]
 212 .I Attrname,
 213 or
 214 .I attrvalue
 215 points outside the allocated address space of the process.
 216 .TP
 217 .SM
 218 \%[EBADF]
 219 .I Fd\^
 220 does not refer to a valid descriptor.
 221 .SH "DIAGNOSTICS"
 222 On success, zero is returned.  On error, \-1 is returned, and
 223 .I errno
 224 is set appropriately.
 225 .SH "SEE ALSO"
 226 .BR attr (1),
 227 .BR attr_get (3),
 228 .BR attr_list (3),
 229 .BR attr_multi (3),
 230 and
 231 .BR attr_remove (3).