1 /* 2 * Copyright (c) 2001-2002,2004 Silicon Graphics, Inc. 3 * All Rights Reserved. 4 * 5 * This program is free software: you can redistribute it and/or modify it 6 * under the terms of the GNU Lesser General Public License as published by 7 * the Free Software Foundation, either version 2.1 of the License, or 8 * (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with this program. If not, see <http://www.gnu.org/licenses/>. 17 */ 18 #ifndef __ATTRIBUTES_H__ 19 #define __ATTRIBUTES_H__ 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /* 26 * An almost-IRIX-compatible extended attributes API 27 * (the IRIX attribute "list" operation is missing, added ATTR_SECURE). 28 */ 29 30 /* 31 * The maximum size (into the kernel or returned from the kernel) of an 32 * attribute value or the buffer used for an attr_list() call. Larger 33 * sizes will result in an E2BIG return code. 34 */ 35 #define ATTR_MAX_VALUELEN (64*1024) /* max length of a value */ 36 37 38 /* 39 * Flags that can be used with any of the simple attribute calls. 40 * All desired flags should be bit-wise OR'ed together. 41 */ 42 #define ATTR_DONTFOLLOW 0x0001 /* do not follow symlinks for a pathname */ 43 #define ATTR_ROOT 0x0002 /* use root namespace attributes in op */ 44 #define ATTR_TRUST 0x0004 /* tell server we can be trusted to properly 45 handle extended attributes */ 46 #define ATTR_SECURE 0x0008 /* use security namespace attributes in op */ 47 48 /* 49 * Additional flags that can be used with the set() attribute call. 50 * All desired flags (from both lists) should be bit-wise OR'ed together. 51 */ 52 #define ATTR_CREATE 0x0010 /* pure create: fail if attr already exists */ 53 #define ATTR_REPLACE 0x0020 /* pure set: fail if attr does not exist */ 54 55 /* 56 * Define how lists of attribute names are returned to the user from 57 * the attr_list() call. A large, 32bit aligned, buffer is passed in 58 * along with its size. We put an array of offsets at the top that each 59 * reference an attrlist_ent_t and pack the attrlist_ent_t's at the bottom. 60 */ 61 typedef struct attrlist { 62 int32_t al_count; /* number of entries in attrlist */ 63 int32_t al_more; /* T/F: more attrs (do call again) */ 64 int32_t al_offset[1]; /* byte offsets of attrs [var-sized] */ 65 } attrlist_t; 66 67 /* 68 * Show the interesting info about one attribute. This is what the 69 * al_offset[i] entry points to. 70 */ 71 typedef struct attrlist_ent { /* data from attr_list() */ 72 u_int32_t a_valuelen; /* number bytes in value of attr */ 73 char a_name[1]; /* attr name (NULL terminated) */ 74 } attrlist_ent_t; 75 76 /* 77 * Given a pointer to the (char*) buffer containing the attr_list() result, 78 * and an index, return a pointer to the indicated attribute in the buffer. 79 */ 80 #define ATTR_ENTRY(buffer, index) \ 81 ((attrlist_ent_t *) \ 82 &((char *)buffer)[ ((attrlist_t *)(buffer))->al_offset[index] ]) 83 84 /* 85 * Implement a "cursor" for use in successive attr_list() calls. 86 * It provides a way to find the last attribute that was returned in the 87 * last attr_list() call so that we can get the next one without missing 88 * any. This should be bzero()ed before use and whenever it is desired to 89 * start over from the beginning of the attribute list. The only valid 90 * operation on a cursor is to bzero() it. 91 */ 92 typedef struct attrlist_cursor { 93 u_int32_t opaque[4]; /* an opaque cookie */ 94 } attrlist_cursor_t; 95 96 /* 97 * Multi-attribute operation vector. 98 */ 99 typedef struct attr_multiop { 100 int32_t am_opcode; /* operation to perform (ATTR_OP_GET, etc.) */ 101 int32_t am_error; /* [out arg] result of this sub-op (an errno) */ 102 char *am_attrname; /* attribute name to work with */ 103 char *am_attrvalue; /* [in/out arg] attribute value (raw bytes) */ 104 int32_t am_length; /* [in/out arg] length of value */ 105 int32_t am_flags; /* flags (bit-wise OR of #defines above) */ 106 } attr_multiop_t; 107 #define ATTR_MAX_MULTIOPS 128 /* max number ops in an oplist array */ 108 109 /* 110 * Valid values of am_opcode. 111 */ 112 #define ATTR_OP_GET 1 /* return the indicated attr's value */ 113 #define ATTR_OP_SET 2 /* set/create the indicated attr/value pair */ 114 #define ATTR_OP_REMOVE 3 /* remove the indicated attr */ 115 116 /* 117 * Get the value of an attribute. 118 * Valuelength must be set to the maximum size of the value buffer, it will 119 * be set to the actual number of bytes used in the value buffer upon return. 120 * The return value is -1 on error (w/errno set appropriately), 0 on success. 121 */ 122 extern int attr_get (const char *__path, const char *__attrname, 123 char *__attrvalue, int *__valuelength, int __flags); 124 extern int attr_getf (int __fd, const char *__attrname, char *__attrvalue, 125 int *__valuelength, int __flags); 126 127 /* 128 * Set the value of an attribute, creating the attribute if necessary. 129 * The return value is -1 on error (w/errno set appropriately), 0 on success. 130 */ 131 extern int attr_set (const char *__path, const char *__attrname, 132 const char *__attrvalue, const int __valuelength, 133 int __flags); 134 extern int attr_setf (int __fd, const char *__attrname, 135 const char *__attrvalue, const int __valuelength, 136 int __flags); 137 138 /* 139 * Remove an attribute. 140 * The return value is -1 on error (w/errno set appropriately), 0 on success. 141 */ 142 extern int attr_remove (const char *__path, const char *__attrname, 143 int __flags); 144 extern int attr_removef (int __fd, const char *__attrname, int __flags); 145 146 /* 147 * List the names and sizes of the values of all the attributes of an object. 148 * "Cursor" must be allocated and zeroed before the first call, it is used 149 * to maintain context between system calls if all the attribute names won't 150 * fit into the buffer on the first system call. 151 * The return value is -1 on error (w/errno set appropriately), 0 on success. 152 */ 153 int attr_list(const char *__path, char *__buffer, const int __buffersize, 154 int __flags, attrlist_cursor_t *__cursor); 155 int attr_listf(int __fd, char *__buffer, const int __buffersize, 156 int __flags, attrlist_cursor_t *__cursor); 157 158 /* 159 * Operate on multiple attributes of the same object simultaneously. 160 * 161 * This call will save on system call overhead when many attributes are 162 * going to be operated on. 163 * 164 * The return value is -1 on error (w/errno set appropriately), 0 on success. 165 * Note that this call will not return -1 as a result of failure of any 166 * of the sub-operations, their return value is stored in each element 167 * of the operation array. This call will return -1 for a failure of the 168 * call as a whole, eg: if the pathname doesn't exist, or the fd is bad. 169 * 170 * The semantics and allowable values for the fields in a attr_multiop_t 171 * are the same as the semantics and allowable values for the arguments to 172 * the corresponding "simple" attribute interface. For example: the args 173 * to a ATTR_OP_GET are the same as the args to an attr_get() call. 174 */ 175 extern int attr_multi (const char *__path, attr_multiop_t *__oplist, 176 int __count, int __flags); 177 extern int attr_multif (int __fd, attr_multiop_t *__oplist, 178 int __count, int __flags); 179 180 #ifdef __cplusplus 181 } 182 #endif 183 184 #endif /* __ATTRIBUTES_H__ */ 185