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