mirror of
https://github.com/darlinghq/darling-copyfile.git
synced 2024-11-26 22:20:26 +00:00
127 lines
4.5 KiB
Groff
127 lines
4.5 KiB
Groff
.\"
|
|
.\" Copyright (c) 2013 Apple Computer, Inc. All rights reserved.
|
|
.\"
|
|
.Dd October 9, 2018
|
|
.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
|
|
.Nd obtain properties related to extended attributes, for use in copying
|
|
.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_preserve_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
|
|
.Vt 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 some 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 Drive.
|
|
.El
|
|
.Sh FLAGS
|
|
Various flags are defined by the type
|
|
.Vt 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 Drive.
|
|
Sync services 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.
|