[apple/copyfile.git] / xattr_name_with_flags.3

.\"
.\" Copyright (c) 2013 Apple Computer, Inc.  All rights reserved.
.\"
.Dd October 7, 2013
.Dt XATTR_NAME_WITH_FLAGS 3
.Os
.Sh NAME
.Nm xattr_preserve_for_intent , xattr_name_with_flags , xattr_name_without_flags ,
.Nm xattr_flags_from_name , xattr_intent_with_flags
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In xattr_flags.h
.Ft int
.Fn xattr_preserve_for_intent "const char *" "xattr_operation_intent_t"
.Ft char *
.Fn xattr_name_with_flags "const char *" "xattr_flags_t"
.Ft char *
.Fn xattr_name_without_flags "const char *"
.Ft xattr_flags_t
.Fn xattr_flags_from_name "const char *"
.Ft int
.Fn xattr_intent_with_flags "xattr_operation_intent_t" "xattr_flags_t"
.Sh DESCRIPTION
These functions are used in conjunction with copying extended attributes from
one file to another.  Various types of copying (an "intent") check flags to
determine which is allowed or not.
.Pp
The
.Fn xattr_name_with_flags
function returns an extended attribute name with the appropriate flags encoded
as a string; the
.Fn xattr_name_without_flags
undoes this, giving the name of the extended attribute without the flags
encoding.  The slight inverse of that is
.Fn xattr_flags_from_name ,
which will return the flags encoded in a name.
.Pp
The values returned by
.Fn xattr_name_with_flags
and
.Fn xattr_name_without_flags
are allocated using
.Xr malloc 3 ,
and should be released by the caller, using
.Xr free 3 .
.Pp
These functions also have an internal table of pre-defined names, maintained
by the operating system.
.Pp
The function
.Fn xattr_intent_with_flags
will return 0 if the
.Ar flags
argument indicates it should not be preserved for the given
intent, or 1 if it should.
.Pp
The function
.Fn xattr_presere_for_intent
combines the functions above, and will return zero if the
named extended attribute should be preserved during a copy for
the given intent.
.Sh INTENT
The type
.Dt xattr_operation_intent_t
is an integral type, which is used to indicate what the intent for the operation
is.  The following intent values are defined:
.Bl -tag -width XATTR_OPERATION_INTENT_SHARE
.It Dv XATTR_OPERATION_INTENT_COPY
Indicates that the intent is to simply copy from the source to the destination.
E.g., with cp.  Most extended attributes should generally be preserved in this
case.
.It Dv XATTR_OPERATION_INTENT_SAVE
Indicates that intent is to perform a save (perhaps as in a "safe save").
This differs from a copy in that the content may be changing; the destination
may be over-writing or replacing the source, and som extended attributes should
not be preserved during this process.
.It Dv XATTR_OPERATION_INTENT_SHARE
Indicates that the intent is to share, or export, the object.  For example,
saving as an attachment in an email message, or placing in a public folder.
Sensitive information should probably not be preserved in this case.
.It Dv XATTR_OPERATION_INTENT_SYNC
Indicates that the intent is to sync the object to a service like iCloud.
.El
.Sh FLAGS
Various flags are defined by the type
.Dt xattr_flags_t ;
the currently-defined values for this are
.Bl -tag -width XATTR_FLAG_CONTENT_DEPENDENT
.It Dv XATTR_FLAG_NO_EXPORT
This indicates that the extended attribute should not be exported, or shared.
This is used with
.Dv XATTR_OPERATION_INTENT_SHARE .
.It Dv XATTR_FLAG_CONTENT_DEPENDENT
This indicates that the extended attribute is tied to the contents of the
file (or vice versa), such that it should be re-created when the contents
are changed.  A checksum, for example, should not be copied, and would thus
be marked with this flag.
.It Dv XATTR_FLAG_NEVER_PRESERVE
This indicates that the extended attribute should never be copied from a
source object to a destination, no matter what the given intent is.
.It Dv XATTR_FLAG_SYNCABLE
This indicates that the extended attribute should be copied when the file
is synced on services like iCloud. Sync services tends to want the metadata
synced to be kept to a bare minimum, and may enforce additional restrictions
on the acceptable size and number of extended attributes.
.El
.Sh EXAMPLE
The following example is a simple function that, given an extended attribute
name and an operation intent, will return whether or not the extended attribute
should be copied.  (This essentially does what
.Fn xattr_preserve_for_intent
does.)
.Bd -literal -offset indent
int
ShouldCopyEA(const char *eaName, xattr_operation_intent_t intent)
{
	xattr_flags_t flags = xattr_flags_from_name(eaName);
	return xattr_intent_with_flags(intent, flags);
}
.Ed
.Sh HISTORY
These functions first appeared in Mac OS in 2013.
Commit	Line	Data
618b37c8 A	1	.\"
	2	.\" Copyright (c) 2013 Apple Computer, Inc. All rights reserved.
	3	.\"
	4	.Dd October 7, 2013
	5	.Dt XATTR_NAME_WITH_FLAGS 3
	6	.Os
	7	.Sh NAME
	8	.Nm xattr_preserve_for_intent , xattr_name_with_flags , xattr_name_without_flags ,
	9	.Nm xattr_flags_from_name , xattr_intent_with_flags
	10	.Sh LIBRARY
	11	.Lb libc
	12	.Sh SYNOPSIS
913df16a	13	.In xattr_flags.h
618b37c8 A	14	.Ft int
	15	.Fn xattr_preserve_for_intent "const char *" "xattr_operation_intent_t"
	16	.Ft char *
	17	.Fn xattr_name_with_flags "const char *" "xattr_flags_t"
	18	.Ft char *
	19	.Fn xattr_name_without_flags "const char *"
	20	.Ft xattr_flags_t
	21	.Fn xattr_flags_from_name "const char *"
	22	.Ft int
	23	.Fn xattr_intent_with_flags "xattr_operation_intent_t" "xattr_flags_t"
	24	.Sh DESCRIPTION
	25	These functions are used in conjunction with copying extended attributes from
	26	one file to another. Various types of copying (an "intent") check flags to
	27	determine which is allowed or not.
	28	.Pp
	29	The
	30	.Fn xattr_name_with_flags
	31	function returns an extended attribute name with the appropriate flags encoded
	32	as a string; the
	33	.Fn xattr_name_without_flags
	34	undoes this, giving the name of the extended attribute without the flags
	35	encoding. The slight inverse of that is
	36	.Fn xattr_flags_from_name ,
	37	which will return the flags encoded in a name.
	38	.Pp
	39	The values returned by
	40	.Fn xattr_name_with_flags
	41	and
	42	.Fn xattr_name_without_flags
	43	are allocated using
	44	.Xr malloc 3 ,
	45	and should be released by the caller, using
	46	.Xr free 3 .
	47	.Pp
	48	These functions also have an internal table of pre-defined names, maintained
	49	by the operating system.
	50	.Pp
	51	The function
	52	.Fn xattr_intent_with_flags
	53	will return 0 if the
	54	.Ar flags
	55	argument indicates it should not be preserved for the given
	56	intent, or 1 if it should.
	57	.Pp
	58	The function
	59	.Fn xattr_presere_for_intent
	60	combines the functions above, and will return zero if the
	61	named extended attribute should be preserved during a copy for
	62	the given intent.
	63	.Sh INTENT
	64	The type
	65	.Dt xattr_operation_intent_t
	66	is an integral type, which is used to indicate what the intent for the operation
	67	is. The following intent values are defined:
	68	.Bl -tag -width XATTR_OPERATION_INTENT_SHARE
	69	.It Dv XATTR_OPERATION_INTENT_COPY
	70	Indicates that the intent is to simply copy from the source to the destination.
	71	E.g., with cp. Most extended attributes should generally be preserved in this
	72	case.
	73	.It Dv XATTR_OPERATION_INTENT_SAVE
	74	Indicates that intent is to perform a save (perhaps as in a "safe save").
	75	This differs from a copy in that the content may be changing; the destination
	76	may be over-writing or replacing the source, and som extended attributes should
	77	not be preserved during this process.
78	.It Dv XATTR_OPERATION_INTENT_SHARE
79	Indicates that the intent is to share, or export, the object. For example,
80	saving as an attachment in an email message, or placing in a public folder.
81	Sensitive information should probably not be preserved in this case.
82	.It Dv XATTR_OPERATION_INTENT_SYNC
83	Indicates that the intent is to sync the object to a service like iCloud.
84	.El
85	.Sh FLAGS
86	Various flags are defined by the type
87	.Dt xattr_flags_t ;
88	the currently-defined values for this are
89	.Bl -tag -width XATTR_FLAG_CONTENT_DEPENDENT
90	.It Dv XATTR_FLAG_NO_EXPORT
91	This indicates that the extended attribute should not be exported, or shared.
92	This is used with
93	.Dv XATTR_OPERATION_INTENT_SHARE .
94	.It Dv XATTR_FLAG_CONTENT_DEPENDENT
95	This indicates that the extended attribute is tied to the contents of the
96	file (or vice versa), such that it should be re-created when the contents
97	are changed. A checksum, for example, should not be copied, and would thus
98	be marked with this flag.
99	.It Dv XATTR_FLAG_NEVER_PRESERVE
100	This indicates that the extended attribute should never be copied from a
101	source object to a destination, no matter what the given intent is.
102	.It Dv XATTR_FLAG_SYNCABLE
103	This indicates that the extended attribute should be copied when the file
104	is synced on services like iCloud. Sync services tends to want the metadata
105	synced to be kept to a bare minimum, and may enforce additional restrictions
106	on the acceptable size and number of extended attributes.
107	.El
108	.Sh EXAMPLE
109	The following example is a simple function that, given an extended attribute
110	name and an operation intent, will return whether or not the extended attribute
111	should be copied. (This essentially does what
112	.Fn xattr_preserve_for_intent
113	does.)
114	.Bd -literal -offset indent
115	int
116	ShouldCopyEA(const char *eaName, xattr_operation_intent_t intent)
117	{
118	xattr_flags_t flags = xattr_flags_from_name(eaName);
119	return xattr_intent_with_flags(intent, flags);
120	}
121	.Ed
122	.Sh HISTORY
123	These functions first appeared in Mac OS in 2013.