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 extended attribute names
  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 .It Dv XATTR_SHOWCOMPRESSION
  70 .Fn listxattr
  71 and
  72 .Fn flistxattr
  73 will list HFS Plus Compression extended attribute(s) (if present) for the file referred to by
  74 .Fa path
  75 or
  76 .Fa fd .
  77 .El
  78 .Pp
  79 If
  80 .Fa namebuf
  81 is set to NULL,
  82 the function returns the size of the list of extended attribute names.
  83 This facility can be used to determine the size of a buffer sufficiently
  84 large to hold the names of the attributes currently associated with
  85 .Fa path .
  86 .Pp
  87 .Fn flistxattr
  88 is identical to
  89 .Fn listxattr ,
  90 except that it returns the list of extended attribute names associated
  91 with the open file referenced by file descriptor
  92 .Fa fd .
  93 .Sh RETURN VALUES
  94 On success, the size of the extended attribute name list is returned.  If
  95 no accessible extended attributes are associated with the given
  96 .Fa path
  97 or
  98 .Fa fd ,
  99 the function returns zero.  On failure, -1 is returned and the global
 100 variable
 101 .Va errno
 102 is set as follows.
 103 .Sh ERRORS
 104 .Bl -tag -width Er
 105 .It Bq Er ENOTSUP
 106 The file system does not support extended attributes or has the feature
 107 disabled.
 108 .It Bq Er ERANGE
 109 .Fa namebuf
 110 (as indicated by
 111 .Fa size )
 112 is too small to hold the list of names.
 113 .It Bq Er EPERM
 114 .Fa path
 115 or
 116 .Fa fd
 117 refer to a file system object that does not support extended attributes.
 118 For example, resource forks don't support extended attributes.
 119 .\" If only EFTYPE was a POSIX error
 120 .It Bq Er ENOTDIR
 121 A component of
 122 .Fa path 's
 123 prefix is not a directory.
 124 .It Bq Er ENAMETOOLONG
 125 .Fa name
 126 exceeds
 127 .Dv XATTR_MAXNAMELEN
 128 UTF-8 bytes, or a component of
 129 .Fa path
 130 exceeds
 131 .Dv NAME_MAX
 132 characters, or the entire
 133 .Fa path
 134 exceeds
 135 .Dv PATH_MAX
 136 characters.
 137 .It Bq Er EACCES
 138 Search permission is denied for a component of
 139 .Fa path
 140 or permission is denied to read the list of attributes from this file.
 141 .It Bq Er ELOOP
 142 Too many symbolic links were encountered resolving
 143 .Fa path .
 144 .It Bq Er EFAULT
 145 .Fa path
 146 points to an invalid address.
 147 .It Bq Er EIO
 148 An I/O error occurred.
 149 .It Bq Er EINVAL
 150 .Fa options
 151 does not make sense.
 152 .El
 153 .Sh SEE ALSO
 154 .Xr getxattr 2 ,
 155 .Xr removexattr 2 ,
 156 .Xr setxattr 2
 157 .Sh HISTORY
 158 .Fn listxattr
 159 and
 160 .Fn flistxattr
 161 first appeared in Mac OS X 10.4.