bsd/man/man2/listxattr.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 LISTXATTR 2
  25 .Os "Mac OS X"
  26 .Sh NAME
  27 .Nm listxattr,
  28 .Nm flistxattr
  29 .Nd list an extended attribute value
  30 .Sh SYNOPSIS
  31 .Fd #include <sys/xattr.h>
  32 .Ft ssize_t
  33 .Fn listxattr "const char *path" "char *namebuf" "size_t size" "int options"
  34 .Ft ssize_t
  35 .Fn flistxattr "int fd" "char *namebuf" "size_t size" "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 associated
  39 with file system objects (files, directories, symlinks, etc).
  40 .Pp
  41 .Fn listxattr
  42 retrieves a list of names of extended attributes associated with the given
  43 .Fa path
  44 in the file system.
  45 .Pp
  46 .Fa namebuf
  47 is a data buffer of
  48 .Pa size
  49 bytes for the names of the extended attributes associated with
  50 .Fa path .
  51 The extended attribute names are simple NULL-terminated UTF-8 strings and
  52 are returned in arbitrary order.  No extra padding is provided between
  53 names in the buffer.  The list will only include names of extended
  54 attributes to which the calling process has access.  The function returns
  55 the size of the list of names.
  56 .Pp
  57 .Fa options
  58 controls how the attribute list is generated:
  59 .Pp
  60 .Bl -tag -width XATTR_NOFOLLOW
  61 .It Dv XATTR_NOFOLLOW
  62 do not follow symbolic links.
  63 .Fn listxattr
  64 normally lists attributes of the target of
  65 .Fa path
  66 if it is a symbolic link.  With this option,
  67 .Fn listxattr
  68 will list attributes of the link itself.
  69 .El
  70 .Pp
  71 If
  72 .Fa namebuf
  73 is set to NULL,
  74 the function returns the size of the list of extended attribute names.
  75 This facility can be used to determine the size of a buffer sufficiently
  76 large to hold the names of the attributes currently associated with
  77 .Fa path .
  78 .Pp
  79 .Fn flistxattr
  80 is identical to
  81 .Fn listxattr ,
  82 except that it returns the list of extended attribute names associated
  83 with the open file referenced by file descriptor
  84 .Fa fd .
  85 .Sh RETURN VALUES
  86 On success, the size of the extended attribute name list is returned.  If
  87 no accessible extended attributes are associated with the given
  88 .Fa path
  89 or
  90 .Fa fd ,
  91 the function returns zero.  On failure, -1 is returned and the global
  92 variable
  93 .Va errno
  94 is set as follows.
  95 .Sh ERRORS
  96 .Bl -tag -width Er
  97 .It Bq Er ENOTSUP
  98 The file system does not support extended attributes or has the feature
  99 disabled.
 100 .It Bq Er ERANGE
 101 .Fa namebuf
 102 (as indicated by
 103 .Fa size )
 104 is too small to hold the list of names.
 105 .It Bq Er EPERM
 106 .Fa path
 107 or
 108 .Fa fd
 109 refer to a file system object that does not support extended attributes.
 110 For example, resource forks don't support extended attributes.
 111 .\" If only EFTYPE was a POSIX error
 112 .It Bq Er ENOTDIR
 113 A component of
 114 .Fa path 's
 115 prefix is not a directory.
 116 .It Bq Er ENAMETOOLONG
 117 .Fa name
 118 exceeds
 119 .Dv XATTR_MAXNAMELEN
 120 UTF-8 bytes, or a component of
 121 .Fa path
 122 exceeds
 123 .Dv NAME_MAX
 124 characters, or the entire
 125 .Fa path
 126 exceeds
 127 .Dv PATH_MAX
 128 characters.
 129 .It Bq Er EACCES
 130 Search permission is denied for a component of
 131 .Fa path
 132 or permission is denied to read the list of attributes from this file.
 133 .It Bq Er ELOOP
 134 Too many symbolic links were encountered resolving
 135 .Fa path .
 136 .It Bq Er EFAULT
 137 .Fa path
 138 points to an invalid address.
 139 .It Bq Er EIO
 140 An I/O error occurred.
 141 .It Bq Er EINVAL
 142 .Fa options
 143 does not make sense.
 144 .El
 145 .Sh SEE ALSO
 146 .Xr getxattr 2 ,
 147 .Xr removexattr 2 ,
 148 .Xr setxattr 2
 149 .Sh HISTORY
 150 .Fn listxattr
 151 and
 152 .Fn flistxattr
 153 first appeared in Mac OS X 10.4.