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	.El
	87	.Pp
	88	.Fn fgetxattr
	89	is identical to
	90	.Fn getxattr ,
	91	except that it retrieves extended attribute data from the open file
	92	referenced by the file descriptor
	93	.Fa fd .
	94	.Sh RETURN VALUES
	95	On success, the size of the extended attribute data is returned. On
	96	failure, -1 is returned and the global variable
	97	.Va errno
	98	is set as follows.
	99	.Sh ERRORS
	100	.Bl -tag -width Er
	101	.It Bq Er ENOATTR
	102	The extended attribute does not exist.
	103	.It Bq Er ENOTSUP
	104	The file system does not support extended attributes or has the feature
	105	disabled.
	106	.It Bq Er ERANGE
	107	.Fa value
	108	(as indicated by
	109	.Fa size )
	110	is too small to hold the extended attribute data.
	111	.It Bq Er EPERM
	112	The named attribute is not permitted for this type of object.
	113	.It Bq Er EINVAL
	114	.Fa name
	115	is invalid or
	116	.Fa options
	117	has an unsupported bit set.
	118	.It Bq Er EISDIR
	119	.Fa path
	120	or
	121	.Fa fd
	122	do not refer to a regular file and the attribute in question is only
	123	applicable to files. Similar to EPERM.
	124	.It Bq Er ENOTDIR
	125	A component of
	126	.Fa path 's
	127	prefix is not a directory.
	128	.It Bq Er ENAMETOOLONG
	129	The length of
	130	.Fa name
	131	exceeds
	132	.Dv XATTR_MAXNAMELEN
	133	UTF-8 bytes, or a component of
	134	.Fa path
	135	exceeds
	136	.Dv NAME_MAX
	137	characters, or the entire
	138	.Fa path
	139	exceeds
	140	.Dv PATH_MAX
	141	characters.
	142	.It Bq Er EACCES
	143	Search permission is denied for a component of
	144	.Fa path
	145	or the attribute is not allowed to be read (e.g. an ACL prohibits reading
	146	the attributes of this file).
	147	.It Bq Er ELOOP
	148	Too many symbolic links were encountered in translating the pathname.
	149	.It Bq Er EFAULT
	150	.Fa path
	151	or
	152	.Fa name
	153	points to an invalid address.
	154	.It Bq Er EIO
	155	An I/O error occurred while reading from or writing to the file system.
	156	.El
	157	.Sh SEE ALSO
	158	.Xr listxattr 2 ,
	159	.Xr removexattr 2 ,
	160	.Xr setxattr 2
	161	.Sh HISTORY
	162	.Fn getxattr
	163	and
	164	.Fn fgetxattr
	165	first appeared in Mac OS X 10.4.