xattr_name_with_flags(3) BSD Library Functions Manual xattr_name_with_flags(3)
NAME
xattr_preserve_for_intent, xattr_name_with_flags,
xattr_name_without_flags, xattr_flags_from_name, xattr_intent_with_flags
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <xattr_flags.h>
int
xattr_preserve_for_intent(const char *, xattr_operation_intent_t);
char *
xattr_name_with_flags(const char *, xattr_flags_t);
char *
xattr_name_without_flags(const char *);
xattr_flags_t
xattr_flags_from_name(const char *);
int
xattr_intent_with_flags(xattr_operation_intent_t, xattr_flags_t);
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.
The xattr_name_with_flags() function returns an extended attribute name
with the appropriate flags encoded as a string; the
xattr_name_without_flags() undoes this, giving the name of the extended
attribute without the flags encoding. The slight inverse of that is
xattr_flags_from_name(), which will return the flags encoded in a name.
The values returned by xattr_name_with_flags() and
xattr_name_without_flags() are allocated using malloc(3), and should be
released by the caller, using free(3).
These functions also have an internal table of pre-defined names, main-
tained by the operating system.
The function xattr_intent_with_flags() will return 0 if the flags argu-
ment indicates it should not be preserved for the given intent, or 1 if
it should.
The function 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.
INTENT
The type is an integral type, which is used to indicate what the intent
for the operation is. The following intent values are defined:
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.
XATTR_OPERATION_INTENT_SAVE Indicates that intent is to perform a save
(perhaps as in a "safe save"). This dif-
fers from a copy in that the content may be
changing; the destination may be over-writ-
ing or replacing the source, and some
extended attributes should not be preserved
during this process.
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 plac-
ing in a public folder. Sensitive informa-
tion should probably not be preserved in
this case.
XATTR_OPERATION_INTENT_SYNC Indicates that the intent is to sync the
object to a service like iCloud.
FLAGS
Various flags are defined by the type the currently-defined values for
this are
XATTR_FLAG_NO_EXPORT This indicates that the extended attribute
should not be exported, or shared. This is
used with XATTR_OPERATION_INTENT_SHARE.
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-cre-
ated when the contents are changed. A
checksum, for example, should not be
copied, and would thus be marked with this
flag.
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.
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.
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
xattr_preserve_for_intent() does.)
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);
}
HISTORY
These functions first appeared in Mac OS in 2013.
BSD December 21, 2016 BSD
Mac OS X 10.13.1 - Generated Wed Nov 8 19:13:37 CST 2017