git.saurik.com Git - apple/xnu.git/blame_incremental

... / ...

Commit	Line	Data
	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 GETXATTR 2
	25	.Os "Mac OS X"
	26	.Sh NAME
	27	.Nm getxattr,
	28	.Nm fgetxattr
	29	.Nd get an extended attribute value
	30	.Sh SYNOPSIS
	31	.Fd #include <sys/xattr.h>
	32	.Ft ssize_t
	33	.Fn getxattr "const char path" "const char name" "void *value" "size_t size" "u_int32_t position" "int options"
	34	.Ft ssize_t
	35	.Fn fgetxattr "int fd" "const char name" "void value" "size_t size" "u_int32_t position" "int options"
	36	.Sh DESCRIPTION
	37	Extended attributes extend the basic attributes of 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	The
	42	.Fn getxattr
	43	function retrieves up to
	44	.Fa size
	45	bytes of data from the extended attribute identified by
	46	.Fa name
	47	associated with
	48	.Fa path
	49	into the pre-allocated buffer pointed to by
	50	.Fa value .
	51	The function returns the number of bytes of data retrieved.
	52	.Pp
	53	An extended attribute's
	54	.Fa name
	55	is a simple NULL-terminated UTF-8 string.
	56	.Fa position
	57	specifies an offset within the extended attribute. In the current
	58	implementation, this argument is only used with the resource fork attribute.
	59	For all other extended attributes, this parameter is reserved and should
	60	be zero.
	61	.Pp
	62	On success,
	63	.Fa value
	64	contains the data associated with
	65	.Fa name .
	66	When
	67	.Fa value
	68	is set to NULL,
	69	.Fn getxattr
	70	returns current size of the named attribute. This facility can be used
	71	to determine the size of a buffer sufficiently large to hold the data
	72	currently associated with the attribute.
	73	.Pp
	74	.Fa options
	75	specify options for retrieving extended attributes:
	76	.Pp
	77	.Bl -tag -width XATTR_NOFOLLOW
	78	.It Dv XATTR_NOFOLLOW
	79	do not follow symbolic links.
	80	.Fn getxattr
	81	normally returns information from the target of
	82	.Fa path
	83	if it is a symbolic link. With this option,
	84	.Fn getxattr
	85	will return extended attribute data from the symbolic link instead.
	86	.It Dv XATTR_SHOWCOMPRESSION
	87	.Fn getxattr
	88	and
	89	.Fn fgetxattr
	90	will return HFS Plus Compression extended attribute
	91	.Fa name
	92	(if present) for the file referred to by
	93	.Fa path
	94	or
	95	.Fa fd .
	96	.El
	97	.Pp
	98	.Fn fgetxattr
	99	is identical to
	100	.Fn getxattr ,
	101	except that it retrieves extended attribute data from the open file
	102	referenced by the file descriptor
	103	.Fa fd .
	104	.Sh RETURN VALUES
	105	On success, the size of the extended attribute data is returned. On
	106	failure, -1 is returned and the global variable
	107	.Va errno
	108	is set as follows.
	109	.Sh ERRORS
	110	.Bl -tag -width Er
	111	.It Bq Er ENOATTR
	112	The extended attribute does not exist.
	113	.It Bq Er ENOTSUP
	114	The file system does not support extended attributes or has the feature
	115	disabled.
	116	.It Bq Er ERANGE
	117	.Fa value
	118	(as indicated by
	119	.Fa size )
	120	is too small to hold the extended attribute data.
	121	.It Bq Er EPERM
	122	The named attribute is not permitted for this type of object.
	123	.It Bq Er EINVAL
	124	.Fa name
	125	is invalid or
	126	.Fa options
	127	has an unsupported bit set.
	128	.It Bq Er EISDIR
	129	.Fa path
	130	or
	131	.Fa fd
	132	do not refer to a regular file and the attribute in question is only
	133	applicable to files. Similar to EPERM.
	134	.It Bq Er ENOTDIR
	135	A component of
	136	.Fa path 's
	137	prefix is not a directory.
	138	.It Bq Er ENAMETOOLONG
	139	The length of
	140	.Fa name
	141	exceeds
	142	.Dv XATTR_MAXNAMELEN
	143	UTF-8 bytes, or a component of
	144	.Fa path
	145	exceeds
	146	.Dv NAME_MAX
	147	characters, or the entire
	148	.Fa path
	149	exceeds
	150	.Dv PATH_MAX
	151	characters.
	152	.It Bq Er EACCES
	153	Search permission is denied for a component of
	154	.Fa path
	155	or the attribute is not allowed to be read (e.g. an ACL prohibits reading
	156	the attributes of this file).
	157	.It Bq Er ELOOP
	158	Too many symbolic links were encountered in translating the pathname.
	159	.It Bq Er EFAULT
	160	.Fa path
	161	or
	162	.Fa name
	163	points to an invalid address.
	164	.It Bq Er EIO
	165	An I/O error occurred while reading from or writing to the file system.
	166	.El
	167	.Sh SEE ALSO
	168	.Xr listxattr 2 ,
	169	.Xr removexattr 2 ,
	170	.Xr setxattr 2
	171	.Sh HISTORY
	172	.Fn getxattr
	173	and
	174	.Fn fgetxattr
	175	first appeared in Mac OS X 10.4.