From 2bc413854052c267be237d4587101b95e52706f1 Mon Sep 17 00:00:00 2001 From: Jarkko Sakkinen Date: Mon, 30 Sep 2013 16:18:32 +0300 Subject: [PATCH] Major documentation cleanup. smack.h was starting to rotten so I did a major cleanup for it. Also fixed couple of minor doxygen issues by removing deprecated variables. --- doc/Doxyfile | 18 +------- libsmack/sys/smack.h | 123 ++++++++++++++++++++++++++++----------------------- 2 files changed, 68 insertions(+), 73 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index 9a5274d..9945b8c 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -319,22 +319,6 @@ INLINE_SIMPLE_STRUCTS = NO TYPEDEF_HIDES_STRUCT = NO -# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to -# determine which symbols to keep in memory and which to flush to disk. -# When the cache is full, less often used symbols will be written to disk. -# For small to medium size projects (<1000 input files) the default value is -# probably good enough. For larger projects a too small cache size can cause -# doxygen to be busy swapping symbols to and from disk most of the time -# causing a significant performance penalty. -# If the system has enough physical memory increasing the cache will improve the -# performance by keeping more symbols in memory. Note that the value works on -# a logarithmic scale so increasing the size by one will roughly double the -# memory usage. The cache size is given by this formula: -# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, -# corresponding to a cache size of 2^16 = 65536 symbols. - -SYMBOL_CACHE_SIZE = 0 - # Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be # set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given # their name and scope. Since this can be an expensive process and often the @@ -1617,7 +1601,7 @@ DOT_NUM_THREADS = 0 # the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the # directory containing the font. -DOT_FONTNAME = FreeSans +DOT_FONTNAME = # The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. # The default size is 10pt. diff --git a/libsmack/sys/smack.h b/libsmack/sys/smack.h index 5bb5380..bc6a0f1 100644 --- a/libsmack/sys/smack.h +++ b/libsmack/sys/smack.h @@ -49,53 +49,57 @@ extern "C" { #endif /*! - * Creates a new empty smack_accesses instance. + * Allocates memory for a new empty smack_accesses instance. The returned + * instance must be later freed with smack_accesses_free(). * - * @param accesses created instance - * @return 0 on success and negative value on failure. + * @param handle output variable for the struct smack_accesses instance + * @return Returns 0 on success and negative on failure. If the operation + * is succesful 'accesses' variable will contain a valid pointer. */ -int smack_accesses_new(struct smack_accesses **accesses); +int smack_accesses_new(struct smack_accesses **handle); /*! - * Destroy a struct smack_accesses *instance. + * Destroys a struct smack_accesses instance. * - * @param handle handle to a struct smack_accesses *instance + * @param handle handle to a struct smack_accesses instance */ void smack_accesses_free(struct smack_accesses *handle); /*! * Write access rules to a given file. * - * @param handle handle to a rules - * @param fd file descriptor - * @return 0 on success and negative value on failure. + * @param handle handle to a struct smack_accesses instance + * @param fd file descriptor to the open file + * @return Returns 0 on success and negative on failure. */ int smack_accesses_save(struct smack_accesses *handle, int fd); /*! - * Write rules to kernel. + * Apply access rules to the kernel. * - * @param handle handle to a rules - * @return 0 on success and negative value on failure. + * @param handle handle to a struct smack_accesses instance + * @return Returns 0 on success and negative on failure. */ int smack_accesses_apply(struct smack_accesses *handle); /*! - * Clear rules from kernel. + * Clear access rules from the kernel. Clears the rules by writing + * corresponding rules with zero access. Note that this function + * does not check whether the rules pre-exist or not. * - * @param handle handle to a rules - * @return 0 on success and negative value on failure. + * @param handle handle to a struct smack_accesses instance + * @return Returns 0 on success and negative on failure. */ int smack_accesses_clear(struct smack_accesses *handle); /*! - * Add new rule to a rule set. + * Add a new rule to the given access rules. * - * @param handle handle to a rule set + * @param handle handle to a struct smack_accesses instance * @param subject subject of the rule * @param object object of the rule * @param access_type access type - * @return Returns 0 on success. + * @return Returns 0 on success and negative on failure. */ int smack_accesses_add(struct smack_accesses *handle, const char *subject, const char *object, const char *access_type); @@ -108,70 +112,77 @@ int smack_accesses_add(struct smack_accesses *handle, const char *subject, * it will be modified. Otherwise a new rule will be created, with permissions * from access_add minus permissions from access_del. * - * @param handle handle to a rule set + * @param handle handle to a struct smack_accesses instance * @param subject subject of the rule * @param object object of the rule * @param access_add access type * @param access_del access type - * @return Returns 0 on success. + * @return Returns 0 on success and negative on failure. */ int smack_accesses_add_modify(struct smack_accesses *handle, const char *subject, const char *object, const char *access_add, const char *access_del); /*! - * Add rules from file. + * Load access rules from the given file. * - * @param accesses instance + * @param handle handle to a struct smack_accesses instance * @param fd file descriptor - * @return 0 on success and negative value on failure. + * @return Returns 0 on success and negative on failure. */ -int smack_accesses_add_from_file(struct smack_accesses *accesses, int fd); +int smack_accesses_add_from_file(struct smack_accesses *handle, int fd); /*! - * Check for Smack access. + * Check whether SMACK allows access for given subject, object and requested + * access. * * @param subject subject of the rule * @param object object of the rule - * @param access_type access type - * @return 1 if access, 0 if no access and -1 on error. + * @param access_type requested access type + * @return Returns 1 if access is allowed, 0 if access is not allowed and + * negative on error. */ int smack_have_access(const char *subject, const char *object, const char *access_type); /*! - * Creates a new empty smack_cipso instance. + * Allocates memory for a new empty smack_cipso instance. The returned + * instance must be later freed with smack_cipso_free(). * - * @param cipso created instance - * @return 0 on success and negative value on failure. + * @param handle output variable for the struct smack_cipso instance + * @return Returns 0 on success and negative on failure. If the operation + * is succesful 'cipso' variable will contain a valid pointer. */ int smack_cipso_new(struct smack_cipso **cipso); /*! - * Destroy a struct smack_cipso *instance. + * Destroys a struct smack_cipso instance. * - * @param handle handle to a struct smack_cipso *instance + * @param handle handle to a struct smack_cipso instance */ void smack_cipso_free(struct smack_cipso *handle); /*! - * Write rules to kernel. + * Apply CIPSO rules to the kernel. * - * @param handle handle to a rules - * @return 0 on success and negative value on failure. + * @param handle handle to a struct smack_cipso instance + * @return Returns 0 on success and negative on failure. */ int smack_cipso_apply(struct smack_cipso *handle); /*! - * Add rules from file. + * Add CIPSO rules from the given file. * * @param cipso instance - * @param fd file descriptor - * @return 0 on success and negative value on failure. + * @param handle handle to a struct smack_cipso instance + * @return Returns 0 on success and negative on failure. */ int smack_cipso_add_from_file(struct smack_cipso *cipso, int fd); /*! - * Get the smackfs directory. + * Get pointer to a string containing path to the mounted SmackFS. + * + * @return Returns a string contain path to the mount SmackFS if SMACK is + * enabled and SmackFS is mounted. Otherwise, NULL is returned. */ const char *smack_smackfs_path(void); @@ -179,20 +190,20 @@ const char *smack_smackfs_path(void); * Get the label that is associated with the callers process. * Caller is responsible of freeing the returned label. * - * @param label returned label - * @return Returns lenght of the label on success and negative value + * @param label output variable for the label + * @return Returns length of the label on success and negative value * on failure. */ ssize_t smack_new_label_from_self(char **label); /*! - * Get the label that is associated with a peer on the other end of an - * Unix socket (SO_PEERSEC). Caller is responsible of freeing the - * returned label. + * Get the label that is associated with a peer on the other end of a + * UDS socket (SO_PEERSEC). Caller is responsible of freeing the returned + * label. * - * @param fd socket file descriptor - * @param label returned label - * @return Returns lenght of the label on success and negative value + * @param fd file descriptor of the socket + * @param label output variable for the label + * @return Returns length of the label on success and negative value * on failure. */ ssize_t smack_new_label_from_socket(int fd, char **label); @@ -202,10 +213,10 @@ ssize_t smack_new_label_from_socket(int fd, char **label); * Caller is responsible of freeing the returned label. * * @param path path of the file - * @param xattr extended attribute containing the SMACK label + * @param xattr the extended attribute containing the SMACK label * @param follow whether or not to follow symbolic link - * @param label returned label - * @return Returns lenght of the label on success and negative value + * @param label output variable for the returned label + * @return Returns length of the label on success and negative value * on failure. */ ssize_t smack_new_label_from_path(const char *path, @@ -214,19 +225,19 @@ ssize_t smack_new_label_from_path(const char *path, char **label); /*! - * Set the label associated with the callers process. - * Caller must be run by privileged user to succeed. + * Set the label associated with the callers process. The caller must have + * CAP_MAC_ADMIN POSIX capability in order to do this. * - * @param label to set - * @return 0 on success and negative value on failure. + * @param label a string containing the new label + * @return Returns 0 on success and negative on failure. */ int smack_set_label_for_self(const char *label); /*! - * Revoke all rules for a subject label. + * Revoke all rules for the given subject label. * * @param subject subject to revoke - * @return 0 on success and negative value on failure. + * @return Returns 0 on success and negative on failure. */ int smack_revoke_subject(const char *subject); -- 2.7.4