aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/eina/eina_xattr.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/eina/eina_xattr.h')
-rw-r--r--src/lib/eina/eina_xattr.h281
1 files changed, 123 insertions, 158 deletions
diff --git a/src/lib/eina/eina_xattr.h b/src/lib/eina/eina_xattr.h
index b37262ee31..a5237d18ef 100644
--- a/src/lib/eina/eina_xattr.h
+++ b/src/lib/eina/eina_xattr.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2011 Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -29,253 +29,218 @@
/**
* @typedef Eina_Xattr_Flags
- * define extended attribute creation
+ * @brief Enumeration of extended attribute creation.
*
* @since 1.1
*/
typedef enum {
- EINA_XATTR_INSERT, /**< This is the default behaviour, it will either create or replace the extended attribute */
- EINA_XATTR_REPLACE, /**< This will only succeed if the extended attribute previously existed */
- EINA_XATTR_CREATED /**< This will only succeed if the extended attribute wasn't previously set */
+ EINA_XATTR_INSERT, /**< This is the default behaviour, it either creates or replaces the extended attribute */
+ EINA_XATTR_REPLACE, /**< This only succeeds if the extended attribute previously existed */
+ EINA_XATTR_CREATED /**< This only succeeds if the extended attribute isn't previously set */
} Eina_Xattr_Flags;
typedef struct _Eina_Xattr Eina_Xattr;
struct _Eina_Xattr
{
- const char *name; /**< The eXtended attribute name @since 1.2 */
- const char *value; /**< The eXtended attribute value @since 1.2 */
+ const char *name; /**< The extended attribute name @since 1.2 */
+ const char *value; /**< The extended attribute value @since 1.2 */
- size_t length; /**< The length of the eXtended attribute value @since 1.2 */
+ size_t length; /**< The length of the extended attribute value @since 1.2 */
};
/**
- * @brief Get an iterator that list all extended attribute of a file.
- *
- * @param file The filename to retrieve the extended attribute list from.
- * @return an iterator.
- *
- * The iterator will not allocate any data during the iteration step, so you need to copy them yourself
- * if you need.
+ * @brief Gets an iterator that lists all the extended attributes of a file.
*
* @since 1.1
- */
-EAPI Eina_Iterator *eina_xattr_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
-
-/**
- * @brief Get an iterator that list all extended attribute value related to a fd.
*
- * @param file The filename to retrieve the extended attribute list from.
- * @return an iterator.
+ * @since_tizen 2.3
*
- * The iterator will not allocate any data during the iteration step, so you need to copy them yourself
- * if you need. The iterator will provide an Eina_Xattr structure.
+ * @remarks The iterator does not allocate any data during the iteration step, so you need to copy them yourself
+ * if you need.
+ *
+ * @param[in] file The file name to retrieve the extended attribute list from
+ * @return An iterator
*
- * @since 1.2
*/
-EAPI Eina_Iterator *eina_xattr_value_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
+EAPI Eina_Iterator *eina_xattr_ls(const char *file);
/**
- * @brief Get an iterator that list all extended attribute related to a fd.
+ * @brief Gets an iterator that lists all the extended attribute values related to a file.
*
- * @param fd The file descriptor to retrieve the extended attribute list from.
- * @return an iterator.
+ * @since 1.2
*
- * The iterator will not allocate any data during the iteration step, so you need to copy them yourself
- * if you need.
+ * @since_tizen 2.3
+ *
+ * @remarks The iterator does not allocate any data during the iteration step, so you need to copy them yourself
+ * if you need them. The iterator provides an Eina_Xattr structure.
+ *
+ * @param[in] file The file name to retrieve the extended attribute list from
+ * @return An iterator
*
- * @since 1.2
*/
-EAPI Eina_Iterator *eina_xattr_fd_ls(int fd) EINA_WARN_UNUSED_RESULT;
+EAPI Eina_Iterator *eina_xattr_value_ls(const char *file);
/**
- * @brief Get an iterator that list all extended attribute value related to a fd.
+ * @brief Gets an iterator that lists all extended attribute related to a file.
*
- * @param fd The file descriptor to retrieve the extended attribute list from.
- * @return an iterator.
+ * @since 1.2
*
- * The iterator will not allocate any data during the iteration step, so you need to copy them yourself
- * if you need. The iterator will provide an Eina_Xattr structure.
+ * @since_tizen 2.3
+ *
+ * @remarks The iterator does not allocate any data during the iteration step, so you need to copy them yourself
+ * if you need them.
+ *
+ * @param[in] fd The file descriptor to retrieve the extended attribute list from
+ * @return An iterator
*
- * @since 1.2
- */
-EAPI Eina_Iterator *eina_xattr_value_fd_ls(int fd) EINA_WARN_UNUSED_RESULT;
-
-/**
- * @brief Copy the extended attribute from one file to another.
- * @param src source file to use as input.
- * @param dst destination file to use as output.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
- * @see eina_xattr_fd_copy()
- * @since 1.8
- */
-EAPI Eina_Bool eina_xattr_copy(const char *src, const char *dst) EINA_ARG_NONNULL(1, 2);
-
-/**
- * @brief Copy the extended attribute from one file descriptor to another.
- * @param src source file descriptor to use as input.
- * @param dst destination file descriptor to use as output.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
- * @see eina_xattr_copy()
- * @since 1.8
*/
-EAPI Eina_Bool eina_xattr_fd_copy(int src, int dst);
+EAPI Eina_Iterator *eina_xattr_fd_ls(int fd);
/**
- * @brief Retrieve an extended attribute from a file.
+ * @brief Gets an iterator that lists all extended attribute value related to a file.
*
- * @param file The file to retrieve the extended attribute from.
- * @param attribute The extended attribute name to retrieve.
- * @param size The size of the retrieved extended attribute.
- * @return the allocated data that hold the extended attribute value.
+ * @since 1.2
*
- * It will return @c NULL and *size will be @c 0 if it fails.
+ * @since_tizen 2.3
+ *
+ * @remarks The iterator does not allocate any data during the iteration step, so you need to copy them yourself
+ * if you need them. The iterator provides an Eina_Xattr structure.
+ *
+ * @param[in] fd The file descriptor to retrieve the extended attribute list from
+ * @return An iterator
*
- * @since 1.1
*/
-EAPI void *eina_xattr_get(const char *file, const char *attribute, ssize_t *size) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT;
+EAPI Eina_Iterator *eina_xattr_value_fd_ls(int fd);
/**
- * @brief Retrieve an extended attribute from a file descriptor.
+ * @brief Gets an extended attribute from a file.
*
- * @param fd The file descriptor to retrieve the extended attribute from.
- * @param attribute The extended attribute name to retrieve.
- * @param size The size of the retrieved extended attribute.
- * @return the allocated data that hold the extended attribute value.
+ * @since 1.1
*
- * It will return @c NULL and *size will be @c 0 if it fails.
+ * @since_tizen 2.3
*
- * @since 1.8
- */
-EAPI void *eina_xattr_fd_get(int fd, const char *attribute, ssize_t *size) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
-
-/**
- * @brief Set an extended attribute on a file.
+ * @remarks It returns @c NULL and *size is @c 0 if it fails.
*
- * @param file The file to set the extended attribute to.
- * @param attribute The attribute to set.
- * @param data The data to set.
- * @param length The length of the data to set.
- * @param flags Define the set policy.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @param[in] file The file to retrieve the extended attribute from
+ * @param[in] attribute The extended attribute name to retrieve
+ * @param[out] size The size of the retrieved extended attribute
+ * @return The allocated data that hold the extended attribute value
*
- * @since 1.1
*/
-EAPI Eina_Bool eina_xattr_set(const char *file, const char *attribute, const void *data, ssize_t length, Eina_Xattr_Flags flags) EINA_ARG_NONNULL(1, 2, 3);
+EAPI void *eina_xattr_get(const char *file, const char *attribute, ssize_t *size);
/**
- * @brief Set an extended attribute on a file descriptor.
+ * @brief Sets an extended attribute to a file.
*
- * @param fd The file descriptor to set the extended attribute to.
- * @param attribute The attribute to set.
- * @param data The data to set.
- * @param length The length of the data to set.
- * @param flags Define the set policy.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @since 1.1
*
- * @since 1.8
- */
-EAPI Eina_Bool eina_xattr_fd_set(int fd, const char *attribute, const void *data, ssize_t length, Eina_Xattr_Flags flags) EINA_ARG_NONNULL(2, 3);
-
-
-/**
- * @brief Delete (remove) an extended attribute from a file.
+ * @since_tizen 2.3
*
- * @param file The file to del the extended attribute from.
- * @param attribute The attribute to del.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @param[in] file The file to set the extended attribute to
+ * @param[in] attribute The attribute to set
+ * @param[in] data The data to set
+ * @param[in] length The length of the data to set
+ * @param[in] flags The flag that defines the set policy
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * @since 1.8
*/
-EAPI Eina_Bool eina_xattr_del(const char *file, const char *attribute) EINA_ARG_NONNULL(1, 2);
+EAPI Eina_Bool eina_xattr_set(const char *file, const char *attribute, const void *data, ssize_t length, Eina_Xattr_Flags flags);
/**
- * @brief Delete (remove) an extended attribute from a file descriptor.
+ * @brief Sets a string as an extended attribute property.
*
- * @param fd The file descriptor to del the extended attribute from.
- * @param attribute The attribute to del.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @since 1.1
*
- * @since 1.8
- */
-EAPI Eina_Bool eina_xattr_fd_del(int fd, const char *attribute) EINA_ARG_NONNULL(2);
-
-/**
- * @brief Set a string as a extended attribute properties.
+ * @since_tizen 2.3
*
- * @param file The file to set the string to.
- * @param attribute The attribute to set.
- * @param data The NULL-terminated string to set.
- * @param flags Define the set policy.
- * @return EINA_TRUE on success, EINA_FALSE otherwise.
+ * @param[in] file The file to set the string to
+ * @param[in] attribute The attribute to set
+ * @param[in] data The NULL-terminated string to set
+ * @param[in] flags The flag that defines the set policy
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * @since 1.1
*/
EAPI Eina_Bool eina_xattr_string_set(const char *file, const char *attribute, const char *data, Eina_Xattr_Flags flags);
/**
- * @brief Get a string from an extended attribute properties.
+ * @brief Gets a string from an extended attribute property.
*
- * @param file The file to get the string from.
- * @param attribute The attribute to get.
- * @return A valid string on success, @c NULL otherwise.
+ * @since 1.1
*
- * This call check that the string is properly NULL-terminated before returning it.
+ * @since_tizen 2.3
+ *
+ * @remarks This call makes sure that the string is properly NULL-terminated before returning it.
+ *
+ * @param[in] file The file to get the string from
+ * @param[in] attribute The attribute to get
+ * @return A valid string on success, otherwise @c NULL
*
- * @since 1.1
*/
EAPI char *eina_xattr_string_get(const char *file, const char *attribute);
/**
- * @brief Set a double as a extended attribute properties.
- *
- * @param file The file to set the double to.
- * @param attribute The attribute to set.
- * @param value The NULL-terminated double to set.
- * @param flags Define the set policy.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @brief Sets a double as an extended attribute property.
*
* @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] file The file to set the double to
+ * @param[in] attribute The attribute to set
+ * @param[in] value The NULL-terminated double to set
+ * @param[in] flags The flag that defines the set policy
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
+ *
*/
EAPI Eina_Bool eina_xattr_double_set(const char *file, const char *attribute, double value, Eina_Xattr_Flags flags);
/**
- * @brief Get a double from an extended attribute properties.
+ * @brief Gets a double from an extended attribute property.
+ *
+ * @since 1.1
*
- * @param file The file to get the string from.
- * @param attribute The attribute to get.
- * @param value Where to put the extracted value
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @since_tizen 2.3
*
- * This call check that the double is correctly set.
+ * @remarks This call makes sure that the double is correctly set.
+ *
+ * @param[in] file The file to get the string from
+ * @param[in] attribute The attribute to get
+ * @param[out] value The extracted value
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * @since 1.1
*/
EAPI Eina_Bool eina_xattr_double_get(const char *file, const char *attribute, double *value);
/**
- * @brief Set an int as a extended attribute properties.
- *
- * @param file The file to set the int to.
- * @param attribute The attribute to set.
- * @param value The NULL-terminated int to set.
- * @param flags Define the set policy.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @brief Sets an integer as a extended attribute property.
*
* @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] file The file to set the integer to
+ * @param[in] attribute The attribute to set
+ * @param[in] value The NULL-terminated integer to set
+ * @param[in] flags The flag that defines the set policy
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
+ *
*/
EAPI Eina_Bool eina_xattr_int_set(const char *file, const char *attribute, int value, Eina_Xattr_Flags flags);
/**
- * @brief Get a int from an extended attribute properties.
+ * @brief Gets a integer from an extended attribute property.
*
- * @param file The file to get the string from.
- * @param attribute The attribute to get.
- * @param value Where to put the extracted value
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @since 1.1
*
- * This call check that the int is correctly set.
+ * @since_tizen 2.3
+ *
+ * @remarks This call makes sure that the integer is correctly set.
+ *
+ * @param[in] file The file to get the string from
+ * @param[in] attribute The attribute to get
+ * @param[out] value The extracted value
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * @since 1.1
*/
EAPI Eina_Bool eina_xattr_int_get(const char *file, const char *attribute, int *value);