[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.
.It Dv XATTR_SHOWCOMPRESSION
.Fn removexattr
and 
.Fn fremovexattr
will remove HFS Plus Compression extended attribute
.Fa name
(if present) for the file referred to by
.Fa path
or
.Fa fd .
.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
39037602	41	.Fn removexattr
91447636 A	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.
b0d623f7 A	62	.It Dv XATTR_SHOWCOMPRESSION
	63	.Fn removexattr
	64	and
	65	.Fn fremovexattr
	66	will remove HFS Plus Compression extended attribute
	67	.Fa name
	68	(if present) for the file referred to by
	69	.Fa path
	70	or
	71	.Fa fd .
91447636 A	72	.El
	73	.Pp
	74	.Fn fremovexattr
	75	is identical to
	76	.Fn removexattr ,
	77	except that it removes an extended attribute from an open file referenced
	78	by file descriptor
	79	.Fa fd .
	80	.Sh RETURN VALUES
	81	On success, 0 is returned. On failure, -1 is returned and the global
	82	variable
	83	.Va errno
	84	is set as follows.
	85	.Sh ERRORS
	86	.Bl -tag -width Er
	87	.It Bq Er ENOATTR
	88	The specified extended attribute does not exist.
	89	.It Bq Er ENOTSUP
	90	The file system does not support extended attributes or has the feature
	91	disabled.
	92	.It Bq Er EROFS
	93	The file system is mounted read-only.
	94	.It Bq Er EPERM
	95	This type of object does not support extended attributes.
	96	.It Bq Er EINVAL
	97	.Fa name
	98	or
	99	.Fa options
	100	is invalid.
	101	.Fa name
	102	must be valid UTF-8
	103	.Fa options
	104	must make sense.
	105	.It Bq Er ENOTDIR
	106	A component of the
	107	.Fa path 's
	108	prefix is not a directory.
	109	.It Bq Er ENAMETOOLONG
	110	.Fa Name
	111	exceeded
	112	.Dv XATTR_MAXNAMELEN
	113	UTF-8 bytes, or a component of
	114	.Fa path
	115	exceeded
	116	.Dv NAME_MAX
	117	characters, or the entire
	118	.Fa path
	119	exceeded
	120	.Dv PATH_MAX
	121	characters.
	122	.It Bq Er EACCES
	123	Search permission is denied for a component
	124	.Fa path
	125	or permission to remove the attribute is denied.
	126	.It Bq Er ELOOP
	127	Too many symbolic links were encountered in
	128	.Fa path .
	129	.It Bq Er EFAULT
	130	.Fa path
	131	or
	132	.Fa name
	133	points to an invalid address.
	134	.It Bq Er EIO
	135	An I/O error occurred while reading from or writing to the file system.
136	.El
137	.Sh SEE ALSO
138	.Xr getxattr 2 ,
2d21ac55 A	139	.Xr listxattr 2 ,
2d21ac55 A	140	.Xr setxattr 2
91447636 A	141	.Sh HISTORY
	142	.Fn removexattr
	143	and
	144	.Fn fremovexattr
	145	first appeared in Mac OS X 10.4.