1/*
2 * Copyright (c) 2013 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
60typedef unsigned int xattr_operation_intent_t;
61
62typedef 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? */
108extern 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 */
122extern 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 */
131extern 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 */
137extern 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 */
145extern 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 */
150