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 <linux/xattr.h> 37 #include <sys/cdefs.h> 38 #include <sys/types.h> 39 40 __BEGIN_DECLS 41 42 /** 43 * [fsetxattr(2)](http://man7.org/linux/man-pages/man2/fsetxattr.2.html) 44 * sets an extended attribute on the file referred to by the given file 45 * descriptor. 46 * 47 * A `size` of 0 can be used to set an empty value, in which case `value` is 48 * ignored and may be null. Setting an xattr to an empty value is not the same 49 * as removing an xattr; see removexattr() for the latter operation. 50 * 51 * Valid flags are `XATTR_CREATE` and `XATTR_REPLACE`. 52 * 53 * Returns 0 on success and returns -1 and sets `errno` on failure. 54 */ 55 int fsetxattr(int __fd, const char* _Nonnull __name, const void* _Nullable __value, size_t __size, int __flags); 56 57 /** 58 * [setxattr(2)](http://man7.org/linux/man-pages/man2/setxattr.2.html) 59 * sets an extended attribute on the file referred to by the given path. 60 * 61 * A `size` of 0 can be used to set an empty value, in which case `value` is 62 * ignored and may be null. Setting an xattr to an empty value is not the same 63 * as removing an xattr; see removexattr() for the latter operation. 64 * 65 * Valid flags are `XATTR_CREATE` and `XATTR_REPLACE`. 66 * 67 * Returns 0 on success and returns -1 and sets `errno` on failure. 68 */ 69 int setxattr(const char* _Nonnull __path, const char* _Nonnull __name, const void* _Nullable __value, size_t __size, int __flags); 70 71 /** 72 * [lsetxattr(2)](http://man7.org/linux/man-pages/man2/lsetxattr.2.html) 73 * sets an extended attribute on the file referred to by the given path, which 74 * is the link itself rather than its target in the case of a symbolic link. 75 * 76 * A `size` of 0 can be used to set an empty value, in which case `value` is 77 * ignored and may be null. Setting an xattr to an empty value is not the same 78 * as removing an xattr; see removexattr() for the latter operation. 79 * 80 * Valid flags are `XATTR_CREATE` and `XATTR_REPLACE`. 81 * 82 * Returns 0 on success and returns -1 and sets `errno` on failure. 83 */ 84 int lsetxattr(const char* _Nonnull __path, const char* _Nonnull __name, const void* _Nullable __value, size_t __size, int __flags); 85 86 /** 87 * [fgetxattr(2)](http://man7.org/linux/man-pages/man2/fgetxattr.2.html) 88 * gets an extended attribute on the file referred to by the given file 89 * descriptor. 90 * 91 * A `size` of 0 can be used to query the current length, in which case `value` is ignored and may be null. 92 * 93 * Returns the non-negative length of the value on success, or 94 * returns -1 and sets `errno` on failure. 95 */ 96 ssize_t fgetxattr(int __fd, const char* _Nonnull __name, void* _Nullable __value, size_t __size); 97 98 /** 99 * [getxattr(2)](http://man7.org/linux/man-pages/man2/getxattr.2.html) 100 * gets an extended attribute on the file referred to by the given path. 101 * 102 * A `size` of 0 can be used to query the current length, in which case `value` is ignored and may be null. 103 * 104 * Returns the non-negative length of the value on success, or 105 * returns -1 and sets `errno` on failure. 106 */ 107 ssize_t getxattr(const char* _Nonnull __path, const char* _Nonnull __name, void* _Nullable __value, size_t __size); 108 109 /** 110 * [lgetxattr(2)](http://man7.org/linux/man-pages/man2/lgetxattr.2.html) 111 * gets an extended attribute on the file referred to by the given path, which 112 * is the link itself rather than its target in the case of a symbolic link. 113 * 114 * A `size` of 0 can be used to query the current length, in which case `value` is ignored and may be null. 115 * 116 * Returns the non-negative length of the value on success, or 117 * returns -1 and sets `errno` on failure. 118 */ 119 ssize_t lgetxattr(const char* _Nonnull __path, const char* _Nonnull __name, void* _Nullable __value, size_t __size); 120 121 /** 122 * [flistxattr(2)](http://man7.org/linux/man-pages/man2/flistxattr.2.html) 123 * lists the extended attributes on the file referred to by the given file 124 * descriptor. 125 * 126 * A `size` of 0 can be used to query the current length, in which case `list` is ignored and may be null. 127 * 128 * Returns the non-negative length of the list on success, or 129 * returns -1 and sets `errno` on failure. 130 */ 131 ssize_t flistxattr(int __fd, char* _Nullable __list, size_t __size); 132 133 /** 134 * [listxattr(2)](http://man7.org/linux/man-pages/man2/listxattr.2.html) 135 * lists the extended attributes on the file referred to by the given path. 136 * 137 * A `size` of 0 can be used to query the current length, in which case `list` is ignored and may be null. 138 * 139 * Returns the non-negative length of the list on success, or 140 * returns -1 and sets `errno` on failure. 141 */ 142 ssize_t listxattr(const char* _Nonnull __path, char* _Nullable __list, size_t __size); 143 144 /** 145 * [llistxattr(2)](http://man7.org/linux/man-pages/man2/llistxattr.2.html) 146 * lists the extended attributes on the file referred to by the given path, which 147 * is the link itself rather than its target in the case of a symbolic link. 148 * 149 * A `size` of 0 can be used to query the current length, in which case `list` is ignored and may be null. 150 * 151 * Returns the non-negative length of the list on success, or 152 * returns -1 and sets `errno` on failure. 153 */ 154 ssize_t llistxattr(const char* _Nonnull __path, char* _Nullable __list, size_t __size); 155 156 /** 157 * [fremovexattr(2)](http://man7.org/linux/man-pages/man2/fremovexattr.2.html) 158 * removes an extended attribute on the file referred to by the given file 159 * descriptor. 160 * 161 * Returns 0 on success and returns -1 and sets `errno` on failure. 162 */ 163 int fremovexattr(int __fd, const char* _Nonnull __name); 164 165 /** 166 * [lremovexattr(2)](http://man7.org/linux/man-pages/man2/lremovexattr.2.html) 167 * removes an extended attribute on the file referred to by the given path, which 168 * is the link itself rather than its target in the case of a symbolic link. 169 * 170 * Returns 0 on success and returns -1 and sets `errno` on failure. 171 */ 172 int lremovexattr(const char* _Nonnull __path, const char* _Nonnull __name); 173 174 /** 175 * [removexattr(2)](http://man7.org/linux/man-pages/man2/removexattr.2.html) 176 * removes an extended attribute on the file referred to by the given path. 177 * 178 * Returns 0 on success and returns -1 and sets `errno` on failure. 179 */ 180 int removexattr(const char* _Nonnull __path, const char* _Nonnull __name); 181 182 __END_DECLS 183