include/attributes.h

   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__ */