[apple/xnu.git] / bsd / man / man2 / removexattr.2

.\"
.\" Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
.\"
.\" @APPLE_LICENSE_HEADER_START@
.\"
.\" This file contains Original Code and/or Modifications of Original Code
.\" as defined in and that are subject to the Apple Public Source License
.\" Version 2.0 (the 'License'). You may not use this file except in
.\" compliance with the License. Please obtain a copy of the License at
.\" http://www.opensource.apple.com/apsl/ and read it before using this
.\" file.
.\"
.\" The Original Code and all software distributed under the License are
.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
.\" Please see the License for the specific language governing rights and
.\" limitations under the License.
.\"
.\" @APPLE_LICENSE_HEADER_END@
.\"
.Dd Oct 19, 2004
.Dt REMOVEXATTR 2
.Os "Mac OS X"
.Sh NAME
.Nm removexattr,
.Nm fremovexattr
.Nd remove an extended attribute value
.Sh SYNOPSIS
.Fd #include <sys/xattr.h>
.Ft int
.Fn removexattr "const char *path" "const char *name" "int options"
.Ft int
.Fn fremovexattr "int fd" "const char *name" "int options"
.Sh DESCRIPTION
Extended attributes extend the basic attributes associated with files and
directories in the file system.  They are stored as name:data pairs
associated with file system objects (files, directories, symlinks, etc).
.Pp
.Fn Removexattr
deletes the extended attribute
.Fa name
associated with
.Fa path .
.Pp
An extended attribute's
.Fa name
is a simple NULL-terminated UTF-8 string.
.Fa Options
is a bit mask specifying various options:
.Pp
.Bl -tag -width XATTR_NOFOLLOW
.It Dv XATTR_NOFOLLOW
do not follow symbolic links.  Normally,
.Fn removexattr
acts on the target of
.Fa path
if it is a symbolic link.  With this option,
.Fn removexattr
will act on the link itself.
.El
.Pp
.Fn fremovexattr
is identical to
.Fn removexattr ,
except that it removes an extended attribute from an open file referenced
by file descriptor
.Fa fd .
.Sh RETURN VALUES
On success, 0 is returned.  On failure, -1 is returned and the global
variable
.Va errno
is set as follows.
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er ENOATTR
The specified extended attribute does not exist.
.It Bq Er ENOTSUP
The file system does not support extended attributes or has the feature
disabled.
.It Bq Er EROFS
The file system is mounted read-only.
.It Bq Er EPERM
This type of object does not support extended attributes.
.It Bq Er EINVAL
.Fa name
or
.Fa options
is invalid.
.Fa name
must be valid UTF-8
.Fa options
must make sense.
.It Bq Er ENOTDIR
A component of the
.Fa path 's
prefix is not a directory.
.It Bq Er ENAMETOOLONG
.Fa Name
exceeded
.Dv XATTR_MAXNAMELEN
UTF-8 bytes, or a component of
.Fa path
exceeded
.Dv NAME_MAX
characters, or the entire
.Fa path
exceeded
.Dv PATH_MAX
characters.
.It Bq Er EACCES
Search permission is denied for a component
.Fa path
or permission to remove the attribute is denied.
.It Bq Er ELOOP
Too many symbolic links were encountered in
.Fa path .
.It Bq Er EFAULT
.Fa path
or
.Fa name
points to an invalid address.
.It Bq Er EIO
An I/O error occurred while reading from or writing to the file system.
.El
.Sh SEE ALSO
.Xr getxattr 2 ,
.Xr listxattr 2 ,
.Xr setxattr 2
.Sh HISTORY
.Fn removexattr
and
.Fn fremovexattr
first appeared in Mac OS X 10.4.
Commit	Line	Data
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.
91447636 A	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.
91447636 A	20	.\"
6601e61a	21	.\" @APPLE_LICENSE_HEADER_END@
91447636 A	22	.\"
	23	.Dd Oct 19, 2004
	24	.Dt REMOVEXATTR 2
	25	.Os "Mac OS X"
	26	.Sh NAME
	27	.Nm removexattr,
	28	.Nm fremovexattr
	29	.Nd remove an extended attribute value
	30	.Sh SYNOPSIS
	31	.Fd #include <sys/xattr.h>
	32	.Ft int
	33	.Fn removexattr "const char path" "const char name" "int options"
	34	.Ft int
	35	.Fn fremovexattr "int fd" "const char *name" "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
	39	associated with file system objects (files, directories, symlinks, etc).
	40	.Pp
	41	.Fn Removexattr
	42	deletes the extended attribute
	43	.Fa name
	44	associated with
	45	.Fa path .
	46	.Pp
	47	An extended attribute's
	48	.Fa name
	49	is a simple NULL-terminated UTF-8 string.
	50	.Fa Options
	51	is a bit mask specifying various options:
	52	.Pp
	53	.Bl -tag -width XATTR_NOFOLLOW
	54	.It Dv XATTR_NOFOLLOW
	55	do not follow symbolic links. Normally,
	56	.Fn removexattr
	57	acts on the target of
	58	.Fa path
	59	if it is a symbolic link. With this option,
	60	.Fn removexattr
	61	will act on the link itself.
	62	.El
	63	.Pp
	64	.Fn fremovexattr
	65	is identical to
	66	.Fn removexattr ,
	67	except that it removes an extended attribute from an open file referenced
	68	by file descriptor
	69	.Fa fd .
	70	.Sh RETURN VALUES
	71	On success, 0 is returned. On failure, -1 is returned and the global
	72	variable
	73	.Va errno
	74	is set as follows.
	75	.Sh ERRORS
	76	.Bl -tag -width Er
	77	.It Bq Er ENOATTR
	78	The specified extended attribute does not exist.
	79	.It Bq Er ENOTSUP
	80	The file system does not support extended attributes or has the feature
	81	disabled.
	82	.It Bq Er EROFS
	83	The file system is mounted read-only.
	84	.It Bq Er EPERM
	85	This type of object does not support extended attributes.
86	.It Bq Er EINVAL
87	.Fa name
88	or
89	.Fa options
90	is invalid.
91	.Fa name
92	must be valid UTF-8
93	.Fa options
94	must make sense.
95	.It Bq Er ENOTDIR
96	A component of the
97	.Fa path 's
98	prefix is not a directory.
99	.It Bq Er ENAMETOOLONG
100	.Fa Name
101	exceeded
102	.Dv XATTR_MAXNAMELEN
103	UTF-8 bytes, or a component of
104	.Fa path
105	exceeded
106	.Dv NAME_MAX
107	characters, or the entire
108	.Fa path
109	exceeded
110	.Dv PATH_MAX
111	characters.
112	.It Bq Er EACCES
113	Search permission is denied for a component
114	.Fa path
115	or permission to remove the attribute is denied.
116	.It Bq Er ELOOP
117	Too many symbolic links were encountered in
118	.Fa path .
119	.It Bq Er EFAULT
120	.Fa path
121	or
122	.Fa name
123	points to an invalid address.
124	.It Bq Er EIO
125	An I/O error occurred while reading from or writing to the file system.
126	.El
127	.Sh SEE ALSO
128	.Xr getxattr 2 ,
2d21ac55 A	129	.Xr listxattr 2 ,
2d21ac55 A	130	.Xr setxattr 2
91447636 A	131	.Sh HISTORY
	132	.Fn removexattr
	133	and
	134	.Fn fremovexattr
	135	first appeared in Mac OS X 10.4.