1 /*
2 * Copyright (C) 2024 Olaf Wintermann <olaf.wintermann@gmail.com>
3 *
4 * Permission to use, copy, modify, and/or distribute this software for
5 * anypurpose with or without fee is hereby granted.
6 *
7 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
8 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
9 * AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
10 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
11 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
12 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
13 * PERFORMANCE OF THIS SOFTWARE.
14 */
15
16 #ifndef LIBXATTR_H
17 #define LIBXATTR_H
18
19 #include <sys/types.h>
20 #include <stdlib.h>
21
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25
26
27 /*
28 * Platform specific notices
29 *
30 * Linux:
31 * Only attributes from the user namespace can be accessed. Attribute names
32 * returned by xattr_list() omit the 'user.' prefix.
33 * The get/set/remove functions automatically add the 'user.' prefix to the
34 * attribute name.
35 *
36 * FreeBSD:
37 * Only attributes from the EXTATTR_NAMESPACE_USER namespace can be accessed.
38 *
39 * Solaris:
40 * The attribute names SUNWattr_ro and SUNWattr_rw are not listed by xattr_list.
41 *
42 * macOS:
43 * It just works.
44 */
45
46
47 /*
48 * Retrieves a list of attribute names associated with a given path.
49 * The length of the returned array is stored in nelm.
50 *
51 * path: File path
52 * nelm: Pointer to a variable to store the number of attributes in the list
53 * Returns: Dynamically allocated array of strings containing the
54 * attribute names or NULL if an error occurs.
55 * The returned array must be manually freed using xattr_free_list().
56 */
57 char ** xattr_list(const char *path, ssize_t *nelm);
58
59 /*
60 * Retrieves the value of a specific attribute and its length.
61 * The value is guaranteed to be null-terminated for convenience, but the
62 * length stored in len excludes the null terminator.
63 *
64 * The value is dynamically allocated and must be manually freed.
65 *
66 * path: File path
67 * attr: Attribute name
68 * len Pointer to a variable to store the length of the value
69 * (without terminating 0-byte)
70 * Returns: Dynamically allocated buffer containing the attribute value
71 * or NULL if an error occurs.
72 * The buffer must be manually freed using free().
73 */
74 char * xattr_get(const char *path, const char *attr, ssize_t *len);
75
76 /*
77 * Sets an attribute value.
78 *
79 * path: File path
80 * name: Attribute name
81 * value: The attribute value, that should be stored
82 * len: Size of the value in bytes
83 * Returns: 0 on success, -1 on error
84 */
85 int xattr_set(const char *path, const char *name, const void *value, size_t len);
86
87 /*
88 * Removes an attribute
89 *
90 * path: file path
91 * name: attribute name
92 * Returns: 0 on success, -1 on error
93 */
94 int xattr_remove(const char *path, const char *name);
95
96 /*
97 * Frees an attribute name list, returned by xattr_list.
98 */
99 void xattr_free_list(char **attrnames, ssize_t nelm);
100
101 #ifdef __cplusplus
102 }
103 #endif
104
105 #endif /* LIBXATTR_H */
106
107