xattr_flags.h

   1 /*
   2  * Copyright (c) 2013-19 Apple, 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
  24 #ifndef _XATTR_FLAGS_H
  25 #define _XATTR_FLAGS_H
  26
  27 #include <stdint.h>
  28
  29 #include <sys/cdefs.h>
  30 #include <Availability.h>
  31
  32 __BEGIN_DECLS
  33
  34 /*
  35  * xattr_operation_intent_t is used to declare what the intent of the copy is.
  36  * Not a bit-field (for now, at least).
  37  *
  38  * XATTR_OPERATION_INTENT_COPY indicates that the EA is attached to an object
  39  * that is simply being copied.  E.g., cp src dst
  40  *
  41  * XATTR_OPERATION_INTENT_SAVE indicates that the EA is attached to an object
  42  * being saved; as in a "safe save," the destination is being replaced by
  43  * the source, so the question is whether the EA should be applied to the
  44  * destination, or generated anew.
  45  *
  46  * XATTR_OPERATION_INTENT_SHARE  indicates that the EA is attached to an object that
  47  * is being given out to other people.  For example, saving to a public folder,
  48  * or attaching to an email message.
  49  *
  50  * XATTR_OPERATION_INTENT_SYNC  indicates that the EA is attached to an object that
  51  * is being synced to other storages for the same user.  For example synced to
  52  * iCloud.
  53  */
  54
  55 #define XATTR_OPERATION_INTENT_COPY     1
  56 #define XATTR_OPERATION_INTENT_SAVE     2
  57 #define XATTR_OPERATION_INTENT_SHARE    3
  58 #define XATTR_OPERATION_INTENT_SYNC     4
  59
  60 typedef unsigned int xattr_operation_intent_t;
  61
  62 typedef uint64_t xattr_flags_t;
  63
  64 /*
  65  * Various properties used to determine how to handle the xattr during
  66  * copying.  The intent is that the default is reasonable for most xattrs.
  67  */
  68
  69 /*
  70  * XATTR_FLAG_NO_EXPORT
  71  * Declare that the extended property should not be exported; this is
  72  * deliberately a bit vague, but this is used by XATTR_OPERATION_INTENT_SHARE
  73  * to indicate not to preserve the xattr.
  74  */
  75 #define XATTR_FLAG_NO_EXPORT    ((xattr_flags_t)0x0001)
  76
  77 /*
  78  * XATTR_FLAG_CONTENT_DEPENDENT
  79  * Declares the extended attribute to be tied to the contents of the file (or
  80  * vice versa), such that it should be re-created when the contents of the
  81  * file change.  Examples might include cryptographic keys, checksums, saved
  82  * position or search information, and text encoding.
  83  *
  84  * This property causes the EA to be preserved for copy and share, but not for
  85  * safe save.  (In a safe save, the EA exists on the original, and will not
  86  * be copied to the new version.)
  87  */
  88 #define XATTR_FLAG_CONTENT_DEPENDENT    ((xattr_flags_t)0x0002)
  89
  90 /*
  91  * XATTR_FLAG_NEVER_PRESERVE
  92  * Declares that the extended attribute is never to be copied, for any
  93  * intention type.
  94  */
  95 #define XATTR_FLAG_NEVER_PRESERVE       ((xattr_flags_t)0x0004)
  96
  97 /*
  98  * XATTR_FLAG_SYNCABLE
  99  * Declares that the extended attribute is to be synced, used by the
 100  * XATTR_OPERATION_ITENT_SYNC intention.  Syncing tends to want to minimize the
 101  * amount of metadata synced around, hence the default behavior is for the EA
 102  * NOT to be synced, even if it would else be preserved for the
 103  * XATTR_OPERATION_ITENT_COPY intention.
 104  */
 105 #define XATTR_FLAG_SYNCABLE     ((xattr_flags_t)0x0008)
 106
 107 /* Given a named extended attribute, and a copy intent, should the EA be preserved? */
 108 extern int xattr_preserve_for_intent(const char *, xattr_operation_intent_t) __OSX_AVAILABLE_STARTING( __MAC_10_10, __IPHONE_8_0);
 109
 110 /*
 111  * Given an extended attribute name, and a set of properties, return an
 112  *  allocated C string with the name.  This will return NULL on error;
 113  * errno may be set to ENOMEM if the new name cannot be allocated, or
 114  * ENAMETOOLONG if the new name is longer than the maximum for EAs (127 UTF8
 115  * characters).  The caller must deallocate the return value otherwise.
 116  *
 117  * If no properties are set, it returns a copy of the EA name.
 118  *
 119  * If the EA name is in the internal list, and the properties are the same as
 120  * defined there, then it will also return an unmodified copy of the EA name.
 121  */
 122 extern char *xattr_name_with_flags(const char *, xattr_flags_t) __OSX_AVAILABLE_STARTING( __MAC_10_10, __IPHONE_8_0);
 123
 124 /*
 125  * Given an extended attribute name, which may or may not have properties encoded
 126  * as a suffix, return just the name of the attribute.  E.g., com.example.mine#P
 127  * would return "com.example.mine".  The return value will be NULL on error;
 128  * errno will be set to ENOMEM if it cannot be allocated.  The caller must deallocate
 129  * the return value.
 130  */
 131 extern char *xattr_name_without_flags(const char *) __OSX_AVAILABLE_STARTING( __MAC_10_10, __IPHONE_8_0);
 132
 133 /*
 134  * Given an EA name, return the properties.  If the name is in the internal list,
 135  * those properties will be returned.  Unknown property encodings are ignored.
 136  */
 137 extern xattr_flags_t xattr_flags_from_name(const char *) __OSX_AVAILABLE_STARTING( __MAC_10_10, __IPHONE_8_0);
 138
 139 /*
 140  * Given an xattr_operation_intent_t and an xattr_flags_t, return whether it should
 141  * be preserved.  The default (in case either flags or intent is 0, or unknown
 142  * values) is to return 1; it only returns 0 if the flags and intent indicate it
 143  * should not be preserved.
 144  */
 145 extern int xattr_intent_with_flags(xattr_operation_intent_t, xattr_flags_t) __OSX_AVAILABLE_STARTING( __MAC_10_10, __IPHONE_8_0);
 146
 147 __END_DECLS
 148
 149 #endif /* _XATTR_FLAGS_H */