1 /* 2 * Copyright (C) 2012 The Android Open Source Project 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * * Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * * Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in 12 * the documentation and/or other materials provided with the 13 * distribution. 14 * 15 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 16 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 17 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 18 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 19 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 21 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 22 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 23 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 25 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26 * SUCH DAMAGE. 27 */ 28 29 #pragma once 30 31 /** 32 * @file sys/xattr.h 33 * @brief Extended attribute functions. 34 */ 35 36 #include <sys/cdefs.h> 37 38 #include <linux/xattr.h> 39 #include <sys/types.h> 40 41 __BEGIN_DECLS 42 43 /** 44 * [fsetxattr(2)](https://man7.org/linux/man-pages/man2/fsetxattr.2.html) 45 * sets an extended attribute on the file referred to by the given file 46 * descriptor. 47 * 48 * A `size` of 0 can be used to set an empty value, in which case `value` is 49 * ignored and may be null. Setting an xattr to an empty value is not the same 50 * as removing an xattr; see removexattr() for the latter operation. 51 * 52 * Valid flags are `XATTR_CREATE` and `XATTR_REPLACE`. 53 * 54 * Returns 0 on success and returns -1 and sets `errno` on failure. 55 */ 56 int fsetxattr(int __fd, const char* _Nonnull __name, const void* _Nullable __value, size_t __size, int __flags); 57 58 /** 59 * [setxattr(2)](https://man7.org/linux/man-pages/man2/setxattr.2.html) 60 * sets an extended attribute on the file referred to by the given path. 61 * 62 * A `size` of 0 can be used to set an empty value, in which case `value` is 63 * ignored and may be null. Setting an xattr to an empty value is not the same 64 * as removing an xattr; see removexattr() for the latter operation. 65 * 66 * Valid flags are `XATTR_CREATE` and `XATTR_REPLACE`. 67 * 68 * Returns 0 on success and returns -1 and sets `errno` on failure. 69 */ 70 int setxattr(const char* _Nonnull __path, const char* _Nonnull __name, const void* _Nullable __value, size_t __size, int __flags); 71 72 /** 73 * [lsetxattr(2)](https://man7.org/linux/man-pages/man2/lsetxattr.2.html) 74 * sets an extended attribute on the file referred to by the given path, which 75 * is the link itself rather than its target in the case of a symbolic link. 76 * 77 * A `size` of 0 can be used to set an empty value, in which case `value` is 78 * ignored and may be null. Setting an xattr to an empty value is not the same 79 * as removing an xattr; see removexattr() for the latter operation. 80 * 81 * Valid flags are `XATTR_CREATE` and `XATTR_REPLACE`. 82 * 83 * Returns 0 on success and returns -1 and sets `errno` on failure. 84 */ 85 int lsetxattr(const char* _Nonnull __path, const char* _Nonnull __name, const void* _Nullable __value, size_t __size, int __flags); 86 87 /** 88 * [fgetxattr(2)](https://man7.org/linux/man-pages/man2/fgetxattr.2.html) 89 * gets an extended attribute on the file referred to by the given file 90 * descriptor. 91 * 92 * A `size` of 0 can be used to query the current length, in which case `value` is ignored and may be null. 93 * 94 * Returns the non-negative length of the value on success, or 95 * returns -1 and sets `errno` on failure. 96 */ 97 ssize_t fgetxattr(int __fd, const char* _Nonnull __name, void* _Nullable __value, size_t __size); 98 99 /** 100 * [getxattr(2)](https://man7.org/linux/man-pages/man2/getxattr.2.html) 101 * gets an extended attribute on the file referred to by the given path. 102 * 103 * A `size` of 0 can be used to query the current length, in which case `value` is ignored and may be null. 104 * 105 * Returns the non-negative length of the value on success, or 106 * returns -1 and sets `errno` on failure. 107 */ 108 ssize_t getxattr(const char* _Nonnull __path, const char* _Nonnull __name, void* _Nullable __value, size_t __size); 109 110 /** 111 * [lgetxattr(2)](https://man7.org/linux/man-pages/man2/lgetxattr.2.html) 112 * gets an extended attribute on the file referred to by the given path, which 113 * is the link itself rather than its target in the case of a symbolic link. 114 * 115 * A `size` of 0 can be used to query the current length, in which case `value` is ignored and may be null. 116 * 117 * Returns the non-negative length of the value on success, or 118 * returns -1 and sets `errno` on failure. 119 */ 120 ssize_t lgetxattr(const char* _Nonnull __path, const char* _Nonnull __name, void* _Nullable __value, size_t __size); 121 122 /** 123 * [flistxattr(2)](https://man7.org/linux/man-pages/man2/flistxattr.2.html) 124 * lists the extended attributes on the file referred to by the given file 125 * descriptor. 126 * 127 * A `size` of 0 can be used to query the current length, in which case `list` is ignored and may be null. 128 * 129 * Returns the non-negative length of the list on success, or 130 * returns -1 and sets `errno` on failure. 131 */ 132 ssize_t flistxattr(int __fd, char* _Nullable __list, size_t __size); 133 134 /** 135 * [listxattr(2)](https://man7.org/linux/man-pages/man2/listxattr.2.html) 136 * lists the extended attributes on the file referred to by the given path. 137 * 138 * A `size` of 0 can be used to query the current length, in which case `list` is ignored and may be null. 139 * 140 * Returns the non-negative length of the list on success, or 141 * returns -1 and sets `errno` on failure. 142 */ 143 ssize_t listxattr(const char* _Nonnull __path, char* _Nullable __list, size_t __size); 144 145 /** 146 * [llistxattr(2)](https://man7.org/linux/man-pages/man2/llistxattr.2.html) 147 * lists the extended attributes on the file referred to by the given path, which 148 * is the link itself rather than its target in the case of a symbolic link. 149 * 150 * A `size` of 0 can be used to query the current length, in which case `list` is ignored and may be null. 151 * 152 * Returns the non-negative length of the list on success, or 153 * returns -1 and sets `errno` on failure. 154 */ 155 ssize_t llistxattr(const char* _Nonnull __path, char* _Nullable __list, size_t __size); 156 157 /** 158 * [fremovexattr(2)](https://man7.org/linux/man-pages/man2/fremovexattr.2.html) 159 * removes an extended attribute on the file referred to by the given file 160 * descriptor. 161 * 162 * Returns 0 on success and returns -1 and sets `errno` on failure. 163 */ 164 int fremovexattr(int __fd, const char* _Nonnull __name); 165 166 /** 167 * [lremovexattr(2)](https://man7.org/linux/man-pages/man2/lremovexattr.2.html) 168 * removes an extended attribute on the file referred to by the given path, which 169 * is the link itself rather than its target in the case of a symbolic link. 170 * 171 * Returns 0 on success and returns -1 and sets `errno` on failure. 172 */ 173 int lremovexattr(const char* _Nonnull __path, const char* _Nonnull __name); 174 175 /** 176 * [removexattr(2)](https://man7.org/linux/man-pages/man2/removexattr.2.html) 177 * removes an extended attribute on the file referred to by the given path. 178 * 179 * Returns 0 on success and returns -1 and sets `errno` on failure. 180 */ 181 int removexattr(const char* _Nonnull __path, const char* _Nonnull __name); 182 183 __END_DECLS 184