]> git.saurik.com Git - apple/xnu.git/blame - bsd/man/man2/listxattr.2
xnu-2782.30.5.tar.gz
[apple/xnu.git] / bsd / man / man2 / listxattr.2
CommitLineData
91447636
A
1.\"
2.\" Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
3.\"
6601e61a 4.\" @APPLE_LICENSE_HEADER_START@
91447636 5.\"
8f6c56a5
A
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
91447636
A
11.\" file.
12.\"
8f6c56a5
A
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
91447636
A
19.\" limitations under the License.
20.\"
6601e61a 21.\" @APPLE_LICENSE_HEADER_END@
91447636
A
22.\"
23.Dd Oct 19, 2004
24.Dt LISTXATTR 2
25.Os "Mac OS X"
26.Sh NAME
27.Nm listxattr,
28.Nm flistxattr
b0d623f7 29.Nd list extended attribute names
91447636
A
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
37Extended attributes extend the basic attributes associated with files and
38directories in the file system. They are stored as name:data pairs associated
39with file system objects (files, directories, symlinks, etc).
40.Pp
41.Fn listxattr
42retrieves a list of names of extended attributes associated with the given
43.Fa path
44in the file system.
45.Pp
46.Fa namebuf
47is a data buffer of
48.Pa size
49bytes for the names of the extended attributes associated with
50.Fa path .
51The extended attribute names are simple NULL-terminated UTF-8 strings and
52are returned in arbitrary order. No extra padding is provided between
53names in the buffer. The list will only include names of extended
54attributes to which the calling process has access. The function returns
55the size of the list of names.
56.Pp
57.Fa options
58controls how the attribute list is generated:
59.Pp
60.Bl -tag -width XATTR_NOFOLLOW
61.It Dv XATTR_NOFOLLOW
62do not follow symbolic links.
63.Fn listxattr
64normally lists attributes of the target of
65.Fa path
66if it is a symbolic link. With this option,
67.Fn listxattr
68will list attributes of the link itself.
b0d623f7
A
69.It Dv XATTR_SHOWCOMPRESSION
70.Fn listxattr
71and
72.Fn flistxattr
73will list HFS Plus Compression extended attribute(s) (if present) for the file referred to by
74.Fa path
75or
76.Fa fd .
91447636
A
77.El
78.Pp
79If
80.Fa namebuf
81is set to NULL,
82the function returns the size of the list of extended attribute names.
83This facility can be used to determine the size of a buffer sufficiently
84large to hold the names of the attributes currently associated with
85.Fa path .
86.Pp
87.Fn flistxattr
88is identical to
89.Fn listxattr ,
90except that it returns the list of extended attribute names associated
91with the open file referenced by file descriptor
92.Fa fd .
93.Sh RETURN VALUES
94On success, the size of the extended attribute name list is returned. If
95no accessible extended attributes are associated with the given
96.Fa path
97or
98.Fa fd ,
99the function returns zero. On failure, -1 is returned and the global
100variable
101.Va errno
102is set as follows.
103.Sh ERRORS
104.Bl -tag -width Er
105.It Bq Er ENOTSUP
106The file system does not support extended attributes or has the feature
107disabled.
108.It Bq Er ERANGE
109.Fa namebuf
110(as indicated by
111.Fa size )
112is too small to hold the list of names.
113.It Bq Er EPERM
114.Fa path
115or
116.Fa fd
117refer to a file system object that does not support extended attributes.
118For example, resource forks don't support extended attributes.
119.\" If only EFTYPE was a POSIX error
120.It Bq Er ENOTDIR
121A component of
122.Fa path 's
123prefix is not a directory.
124.It Bq Er ENAMETOOLONG
125.Fa name
126exceeds
127.Dv XATTR_MAXNAMELEN
128UTF-8 bytes, or a component of
129.Fa path
130exceeds
131.Dv NAME_MAX
132characters, or the entire
133.Fa path
134exceeds
135.Dv PATH_MAX
136characters.
137.It Bq Er EACCES
138Search permission is denied for a component of
139.Fa path
140or permission is denied to read the list of attributes from this file.
141.It Bq Er ELOOP
142Too many symbolic links were encountered resolving
143.Fa path .
144.It Bq Er EFAULT
145.Fa path
146points to an invalid address.
147.It Bq Er EIO
148An I/O error occurred.
149.It Bq Er EINVAL
150.Fa options
151does not make sense.
152.El
153.Sh SEE ALSO
91447636 154.Xr getxattr 2 ,
2d21ac55
A
155.Xr removexattr 2 ,
156.Xr setxattr 2
91447636
A
157.Sh HISTORY
158.Fn listxattr
159and
160.Fn flistxattr
161first appeared in Mac OS X 10.4.