man/man3/attr_list.3

   1 .\" Copyright (C) 2001, 2002, 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_LIST 3 "Extended Attributes" "Dec 2005" "XFS Compatibility API"
  24 .SH NAME
  25 attr_list, attr_listf \- list the names of the user attributes of a filesystem object
  26 .SH C SYNOPSIS
  27 .PP
  28 .sp
  29 .nf
  30 .B #include <sys/attributes.h>
  31 .sp
  32 .B "int attr_list (const char \(**path, char \(**buffer, "
  33 .B "               const int buffersize, int flags,"
  34 .B "               attrlist_cursor_t \(**cursor);"
  35 .PP
  36 .B "int attr_listf (int fd, char \(**buffer, "
  37 .B "                const int buffersize, int flags,"
  38 .B "                attrlist_cursor_t \(**cursor);"
  39 .Op
  40 .SH DESCRIPTION
  41 The
  42 .B attr_list
  43 and
  44 .B attr_listf
  45 functions provide a way to list the existing attributes of a
  46 filesystem object.
  47 .P
  48 .I Path\^
  49 points to a path name for a filesystem object, and
  50 .I fd\^
  51 refers to the file descriptor associated with a file.
  52 The
  53 .I buffer
  54 will be filled with a structure describing at least a portion of the
  55 attributes associated with the given filesystem object.
  56 .I Buffer
  57 will be overwritten with an \f4attrlist_t\fP structure
  58 containing a list of the attributes associated with
  59 that filesystem object, up to a maximum of
  60 .I buffersize
  61 bytes.
  62 The
  63 .I buffer
  64 must be sufficiently large to hold the appropriate data structures
  65 plus at least one maximally sized attribute name,
  66 but cannot be more than ATTR_MAX_VALUELEN (currently 64KB) bytes in length.
  67 .PP
  68 .Op c p a
  69 The contents of an \f4attrlist_t\fP structure include the following members:
  70 .P
  71 .RS 3
  72 .nf
  73 .ft 4
  74 .ta 9n 22n
  75 __int32_t al_count; /\(** number of entries in attrlist \(**/
  76 __int32_t al_more; /\(** T/F: more attrs (do syscall again) \(**/
  77 __int32_t al_offset[1]; /\(** byte offsets of attrs [var-sized] \(**/
  78 .ft 1
  79 .fi
  80 .RE
  81 .PP
  82 The
  83 .I al_count
  84 field shows the number of attributes represented in this buffer,
  85 which is also the number of elements in the
  86 .I al_offset
  87 array.
  88 The
  89 .I al_more
  90 field will be non-zero if another
  91 .B attr_list
  92 call would result in more attributes.
  93 The
  94 .I al_offset
  95 array contains the byte offset within the
  96 .I buffer
  97 of the structure describing each of the attributes,
  98 an \f4attrlist_ent_t\fP structure.
  99 The \f4ATTR_ENTRY(buffer, index)\fP macro will help with decoding the list.
 100 It takes a pointer to the
 101 .I buffer
 102 and an
 103 .I index
 104 into the
 105 .I al_offset
 106 array and returns a pointer to the corresponding
 107 \f4attrlist_ent_t\fP structure.
 108 .PP
 109 The contents of an \f4attrlist_ent_t\fP structure
 110 include the following members:
 111 .P
 112 .RS 3
 113 .nf
 114 .ft 4
 115 .ta 9n 22n
 116 u_int32_t a_valuelen; /\(** number bytes in value of attr \(**/
 117 char a_name[]; /\(** attr name (NULL terminated) \(**/
 118 .ft 1
 119 .fi
 120 .Op
 121 .RE
 122 .PP
 123 The
 124 .I a_valuelen
 125 field shows the size in bytes of the value
 126 associated with the attribute whose name is stored in the
 127 .I a_name
 128 field.
 129 The name is a NULL terminated string.
 130 .PP
 131 Note that the value of the attribute cannot be obtained through
 132 this interface, the
 133 .B attr_get
 134 call should be used to get the value.
 135 The
 136 .B attr_list
 137 interface tells the calling process how large of a buffer
 138 it must have in order to get the attribute\'s value.
 139 .PP
 140 The
 141 .I flags
 142 argument can contain the following symbols bitwise OR\'ed together:
 143 .TP
 144 .SM
 145 \%ATTR_ROOT
 146 List the attributes that are in the
 147 .B root
 148 address space, not in the
 149 .B user
 150 address space.
 151 (limited to use by super-user only)
 152 .TP
 153 .SM
 154 \%ATTR_DONTFOLLOW
 155 Do not follow symbolic links when resolving a
 156 .I path
 157 on an
 158 .B attr_list
 159 function call.
 160 The default is to follow symbolic links.
 161 .PP
 162 The
 163 .I cursor
 164 argument is a pointer to an opaque data structure that the kernel uses
 165 to track the calling process\'s position in the attribute list.
 166 The only valid operations on a
 167 .I cursor
 168 are to pass it into an
 169 .B attr_list
 170 function call or to zero it out.
 171 It should be zero\'ed out before the first
 172 .B attr_list
 173 call.
 174 Note that multi-threaded applications may keep more than one
 175 .I cursor
 176 in order to serve multiple contexts, ie: the
 177 .B attr_list
 178 call is "thread-safe".
 179 .PP
 180 .B attr_list
 181 will fail if one or more of the following are true:
 182 .TP 17
 183 .SM
 184 \%[ENOENT]
 185 The named file does not exist.
 186 .TP
 187 .SM
 188 \%[EPERM]
 189 The effective user
 190 .SM ID
 191 does not match the owner of the file
 192 and the effective user
 193 .SM ID
 194 is not super-user.
 195 .TP
 196 .SM
 197 \%[ENOTDIR]
 198 A component of the
 199 path prefix
 200 is not a directory.
 201 .TP
 202 .SM
 203 \%[EACCES]
 204 Search permission is denied on a
 205 component of the
 206 path prefix.
 207 .TP
 208 .SM
 209 \%[EINVAL]
 210 A bit was set in the
 211 .I flag
 212 argument that is not defined for this system call,
 213 or the buffer was too small or too large.
 214 .TP
 215 .SM
 216 \%[EFAULT]
 217 Either
 218 .I Path
 219 or
 220 .I buffer
 221 points outside the allocated address space of the process, or
 222 .I buffer
 223 or
 224 .I bufsize
 225 are not 32bit aligned.
 226 .TP
 227 .SM
 228 \%[ELOOP]
 229 A path name lookup involved too many symbolic links.
 230 .TP
 231 .SM
 232 \%[ENAMETOOLONG]
 233 The length of
 234 .I path
 235 exceeds
 236 .SM
 237 .RI { MAXPATHLEN },
 238 or a pathname component is longer than
 239 .SM
 240 .RI { MAXNAMELEN }.
 241 .TP
 242 .SM
 243 \%[ENOATTR]
 244 .I attribute\^
 245 does not exist for this file.
 246 .PP
 247 .B attr_listf\^
 248 will fail if:
 249 .TP 15
 250 .SM
 251 \%[EINVAL]
 252 A bit was set in the
 253 .I flag
 254 argument that is not defined for this system call, or
 255 .I fd\^
 256 refers to a socket, not a file,
 257 or the buffer was too small or too large.
 258 .TP
 259 .SM
 260 \%[EFAULT]
 261 Either
 262 .I Path
 263 or
 264 .I buffer
 265 points outside the allocated address space of the process, or
 266 .I buffer
 267 or
 268 .I bufsize
 269 are not 32bit aligned.
 270 .TP
 271 .SM
 272 \%[EBADF]
 273 .I Fd\^
 274 does not refer to a valid descriptor.
 275 .SH "DIAGNOSTICS"
 276 Upon successful completion, a value of 0 is returned.
 277 Otherwise, a value of \-1 is returned and
 278 .I errno\^
 279 is set to indicate the error.
 280 .SH "SEE ALSO"
 281 .BR attr (1),
 282 .BR attr_multi (3),
 283 .BR attr_remove (3),
 284 and
 285 .BR attr_set (3).