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_PROPERTIES_H
25#define _XATTR_PROPERTIES_H
26
27#include <stdint.h>
28
29#include <sys/cdefs.h>
30#include <Availability.h>
31
32__BEGIN_DECLS
33
34/*
35 * CopyOperationIntent_t is used to declare what the intent of the copy is.
36 * Not a bit-field (for now, at least).
37 *
38 * CopyOperationIntentCopy indicates that the EA is attached to an object
39 * that is simply being copied.  E.g., cp src dst
40 *
41 * CopyOperationIntentSave 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 * CopyOperationIntentShare 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
51typedef enum {
52	CopyOperationIntentCopy = 1,
53	CopyOperationIntentSave,
54	CopyOperationIntentShare,
55} CopyOperationIntent_t;
56
57typedef uint64_t CopyOperationProperties_t;
58
59/*
60 * Various properties used to determine how to handle the xattr during
61 * copying.  The intent is that the default is reasonable for most xattrs.
62 */
63
64/*
65 * kCopyOperationPropertyNoExport
66 * Declare that the extended property should not be exported; this is
67 * deliberately a bit vague, but this is used by CopyOperationIntentShare
68 * to indicate not to preserve the xattr.
69 */
70#define kCopyOperationPropertyNoExport	((CopyOperationProperties_t)0x0001)
71
72/*
73 * kCopyOperationPropertyContentDependent
74 * Declares the extended attribute to be tied to the contents of the file (or
75 * vice versa), such that it should be re-created when the contents of the
76 * file change.  Examples might include cryptographic keys, checksums, saved
77 * position or search information, and text encoding.
78 *
79 * This property causes the EA to be preserved for copy and share, but not for
80 * safe save.  (In a safe save, the EA exists on the original, and will not
81 * be copied to the new version.)
82 */
83#define	kCopyOperationPropertyContentDependent	((CopyOperationProperties_t)0x0002)
84
85/*
86 * kCopyOperationPropertyNeverPreserve
87 * Declares that the extended attribute is never to be copied, for any
88 * intention type.
89 */
90#define kCopyOperationPropertyNeverPreserve	((CopyOperationProperties_t)0x0004)
91
92#if 0
93/*
94 * These are all going to be removed, and I don't believe anyone used them.
95 */
96/*
97 * Given an extended attribute name, and a set of properties, return an
98 *  allocated C string with the name.  This will return NULL on error;
99 * errno may be set to ENOMEM if the new name cannot be allocated, or
100 * ENAMETOOLONG if the new name is longer than the maximum for EAs (127 UTF8
101 * characters).  The caller must deallocate the return value otherwise.
102 *
103 * If no properties are set, it returns a copy of the EA name.
104 *
105 * If the EA name is in the internal list, and the properties are the same as
106 * defined there, then it will also return an unmodified copy of the EA name.
107 */
108extern char *_xattrNameWithProperties(const char *, CopyOperationProperties_t) DEPRECATED_IN_MAC_OS_X_VERSION_10_10_AND_LATER;
109
110/*
111 * Given an extended attribute name, which may or may not have properties encoded
112 * as a suffix, return just the name of the attribute.  E.g., com.example.mine#P
113 * would return "com.example.mine".  The return value will be NULL on error;
114 * errno will be set to ENOMEM if it cannot be allocated.  The caller must deallocate
115 * the return value.
116 */
117extern char *_xattrNameWithoutProperties(const char *) DEPRECATED_IN_MAC_OS_X_VERSION_10_10_AND_LATER;
118
119/*
120 * Given an EA name, return the properties.  If the name is in the internal list,
121 * those properties will be returned.  Unknown property encodings are ignored.
122 */
123extern CopyOperationProperties_t _xattrPropertiesFromName(const char *) DEPRECATED_IN_MAC_OS_X_VERSION_10_10_AND_LATER;
124#endif /* 0 */
125
126__END_DECLS
127
128#endif /* _XATTR_PROPERTIES_H */
129