/*
* Copyright (C) 2024 Olaf Wintermann <olaf.wintermann@gmail.com>
*
* Permission to use, copy, modify, and/or distribute this software for
* anypurpose with or without fee is hereby granted.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
* REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
* AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
* INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
* LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
* OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
* PERFORMANCE OF THIS SOFTWARE.
*/
#ifndef LIBXATTR_H
#define LIBXATTR_H
#include <sys/types.h>
#include <stdlib.h>
#ifdef __cplusplus
extern "C" {
#endif
/*
* Platform specific notices
*
* Linux:
* Only attributes from the user namespace can be accessed. Attribute names
* returned by xattr_list() omit the 'user.' prefix.
* The get/set/remove functions automatically add the 'user.' prefix to the
* attribute name.
*
* FreeBSD:
* Only attributes from the EXTATTR_NAMESPACE_USER namespace can be accessed.
*
* Solaris:
* The attribute names SUNWattr_ro and SUNWattr_rw are not listed by xattr_list.
*
* macOS:
* It just works.
*/
/*
* Retrieves a list of attribute names associated with a given path.
* The length of the returned array is stored in nelm.
*
* path: File path
* nelm: Pointer to a variable to store the number of attributes in the list
* Returns: Dynamically allocated array of strings containing the
* attribute names or NULL if an error occurs.
* The returned array must be manually freed using xattr_free_list().
*/
char ** xattr_list(const char *path, ssize_t *nelm);
/*
* Retrieves the value of a specific attribute and its length.
* The value is guaranteed to be null-terminated for convenience, but the
* length stored in len excludes the null terminator.
*
* The value is dynamically allocated and must be manually freed.
*
* path: File path
* attr: Attribute name
* len Pointer to a variable to store the length of the value
* (without terminating 0-byte)
* Returns: Dynamically allocated buffer containing the attribute value
* or NULL if an error occurs.
* The buffer must be manually freed using free().
*/
char * xattr_get(const char *path, const char *attr, ssize_t *len);
/*
* Sets an attribute value.
*
* path: File path
* name: Attribute name
* value: The attribute value, that should be stored
* len: Size of the value in bytes
* Returns: 0 on success, -1 on error
*/
int xattr_set(const char *path, const char *name, const void *value, size_t len);
/*
* Removes an attribute
*
* path: file path
* name: attribute name
* Returns: 0 on success, -1 on error
*/
int xattr_remove(const char *path, const char *name);
/*
* Frees an attribute name list, returned by xattr_list.
*/
void xattr_free_list(char **attrnames, ssize_t nelm);
#ifdef __cplusplus
}
#endif
#endif /* LIBXATTR_H */