From da3a4143da4b6d0815de10e029d23a6bc387241e Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Wed, 23 Jan 2013 11:08:20 -0500 Subject: [PATCH] Finish Doxygen documentation. --- src/apply-default-acl.c | 152 +++++++++++++++++++++++++++------------- 1 file changed, 102 insertions(+), 50 deletions(-) diff --git a/src/apply-default-acl.c b/src/apply-default-acl.c index 9c48b97..7c480a9 100644 --- a/src/apply-default-acl.c +++ b/src/apply-default-acl.c @@ -125,9 +125,9 @@ bool is_directory(const char* path) { * on each path before applying the default to it. * * The assumption that there are no extended entries makes things much - * simpler. For example, we only have to update the ACL_USER_OBJ, - * ACL_GROUP_OBJ, and ACL_OTHER entries -- all others can simply be - * created anew. This means we don't have to fool around comparing + * simpler. For example, we only have to update the @c ACL_USER_OBJ, + * @c ACL_GROUP_OBJ, and @c ACL_OTHER entries -- all others can simply + * be created anew. This means we don't have to fool around comparing * named-user/group entries. * * @param aclp @@ -137,8 +137,8 @@ bool is_directory(const char* path) { * The new entry. If @c entry contains a user/group/other entry, we * update the existing one. Otherwise we create a new entry. * - * @return If there is an unexpected library error, ACL_ERROR is - * returned. Otherwise, ACL_SUCCESS. + * @return If there is an unexpected library error, @c ACL_ERROR is + * returned. Otherwise, @c ACL_SUCCESS. * */ int acl_set_entry(acl_t* aclp, @@ -254,10 +254,10 @@ int acl_set_entry(acl_t* aclp, * @brief Determine the number of entries in the given ACL. * * @param acl - * A pointer to an acl_t structure. + * A pointer to an @c acl_t structure. * * @return Either the non-negative number of entries in @c acl, or - * ACL_ERROR on error. + * @c ACL_ERROR on error. */ int acl_entry_count(acl_t* acl) { @@ -289,9 +289,9 @@ int acl_entry_count(acl_t* acl) { * A pointer to an acl_t structure. * * @return - * - ACL_SUCCESS - @c acl is minimal - * - ACL_FAILURE - @c acl is not minimal - * - ACL_ERROR - Unexpected library error + * - @c ACL_SUCCESS - @c acl is minimal + * - @c ACL_FAILURE - @c acl is not minimal + * - @c ACL_ERROR - Unexpected library error */ int acl_is_minimal(acl_t* acl) { @@ -320,10 +320,10 @@ int acl_is_minimal(acl_t* acl) { * The path to check. * * @return - * - ACL_SUCCESS - @c path has a mask which denies execute. - * - ACL_FAILURE - The ACL for @c path does not deny execute, + * - @c ACL_SUCCESS - @c path has a mask which denies execute. + * - @c ACL_FAILURE - The ACL for @c path does not deny execute, * or @c path has no extended ACL at all. - * - ACL_ERROR - Unexpected library error. + * - @c ACL_ERROR - Unexpected library error. */ int acl_execute_masked(const char* path) { @@ -400,10 +400,11 @@ int acl_execute_masked(const char* path) { * The path to check. * * @return - * - ACL_SUCCESS - @c path is a directory, or someone has effective + * - @c ACL_SUCCESS - @c path is a directory, or someone has effective execute permissions. - * - ACL_FAILURE - @c path is a regular file and nobody can execute it. - * - ACL_ERROR - Unexpected library error. + * - @c ACL_FAILURE - @c path is a regular file and nobody can execute + it. + * - @c ACL_ERROR - Unexpected library error. */ int any_can_execute_or_dir(const char* path) { @@ -492,15 +493,11 @@ int any_can_execute_or_dir(const char* path) { * The target directory whose ACL we wish to overwrite (or create). * * @return - * - ACL_SUCCESS - The default ACL was inherited successfully. - * - ACL_FAILURE - Either @c parent or @c path is not a directory. - * - ACL_ERROR - Unexpected library error. + * - @c ACL_SUCCESS - The default ACL was inherited successfully. + * - @c ACL_FAILURE - Either @c parent or @c path is not a directory. + * - @c ACL_ERROR - Unexpected library error. */ int inherit_default_acl(const char* path, const char* parent) { - /* Inherit the default ACL from parent to path. This overwrites any - * existing default ACL. Returns 1 for success, 0 for failure, and - * -1 on error. - */ /* Our return value. */ int result = ACL_SUCCESS; @@ -541,16 +538,26 @@ int inherit_default_acl(const char* path, const char* parent) { } + +/** + * @brief Remove @c ACL_USER, @c ACL_GROUP, and @c ACL_MASK entries + * from the given path. + * + * @param path + * The path whose ACLs we want to wipe. + * + * @return + * - @c ACL_SUCCESS - The ACLs were wiped successfully, or none + * existed in the first place. + * - @c ACL_ERROR - Unexpected library error. + */ int wipe_acls(const char* path) { - /* Remove ACL_USER, ACL_GROUP, and ACL_MASK entries from - path. Returns 1 for success, 0 for failure, and -1 on error. */ if (path == NULL) { errno = ENOENT; return ACL_ERROR; } - /* Finally, remove individual named/mask entries. */ acl_t acl = acl_get_file(path, ACL_TYPE_ACCESS); if (acl == (acl_t)NULL) { perror("wipe_acls (acl_get_file)"); @@ -595,14 +602,26 @@ int wipe_acls(const char* path) { } + +/** + * @brief Apply parent default ACL to a path. + * + * This overwrites any existing ACLs on @c path. + * + * @param path + * The path whose ACL we would like to reset to its default. + * + * @return + * - @c ACL_SUCCESS - The parent default ACL was inherited successfully. + * - @c ACL_FAILURE - The target path is not a regular file/directory, + * or the parent of @c path is not a directory. + * - @c ACL_ERROR - Unexpected library error. + */ int apply_default_acl(const char* path) { - /* Really apply the default ACL by looping through it. Returns one - * for success, zero for failure (i.e. no ACL), and -1 on unexpected - * errors. - */ if (path == NULL) { - return ACL_FAILURE; + errno = ENOENT; + return ACL_ERROR; } if (!is_regular_file(path) && !is_directory(path)) { @@ -749,10 +768,15 @@ int apply_default_acl(const char* path) { } + +/** + * @brief Display program usage information. + * + * @param program_name + * The program name to use in the output. + * + */ void usage(char* program_name) { - /* - * Print usage information. - */ printf("Apply any applicable default ACLs to the given files or " "directories.\n\n"); printf("Usage: %s [flags] [ [ ...]]\n\n", @@ -766,16 +790,24 @@ void usage(char* program_name) { } +/** + * @brief Wrapper around @c apply_default_acl() for use with @c nftw(). + * + * For parameter information, see the @c nftw man page. + * + * @return If the ACL was applied to @c target successfully, we return + * @c FTW_CONTINUE to signal to @ nftw() that we should proceed onto + * the next file or directory. Otherwise, we return @c FTW_STOP to + * signal failure. + * + */ int apply_default_acl_nftw(const char *target, const struct stat *s, int info, struct FTW *ftw) { - /* A wrapper around the apply_default_acl() function for use with - * nftw(). We need to adjust the return value so that nftw() doesn't - * think we've failed. - */ - bool reapp_result = apply_default_acl(target); - if (reapp_result) { + + bool app_result = apply_default_acl(target); + if (app_result) { return FTW_CONTINUE; } else { @@ -784,14 +816,27 @@ int apply_default_acl_nftw(const char *target, } + +/** + * @brief Recursive version of @c apply_default_acl(). + * + * If @c target is a directory, we use @c nftw() to call @c + * apply_default_acl() recursively on all of its children. Otherwise, + * we just delegate to @c apply_default_acl(). + * + * We ignore symlinks for consistency with chmod -r. + * + * @return + * If @c target is not a directory, we return the result of + * calling @c apply_default_acl() on @c target. Otherwise, we convert + * the return value of @c nftw(). If @c nftw() succeeds (returns 0), + * then we return @c true. Otherwise, we return @c false. + * \n\n + * If there is an error, it will be reported via @c perror, but + * we still return @c false. + */ bool apply_default_acl_recursive(const char *target) { - /* Attempt to apply default ACLs recursively. If target is a - * directory, we recurse through its entries. If not, we just - * apply the default ACL to target. - * - * We ignore symlinks for consistency with chmod -r. - * - */ + if (!is_directory(target)) { return apply_default_acl(target); } @@ -821,10 +866,17 @@ bool apply_default_acl_recursive(const char *target) { } + +/** + * @brief Call apply_default_acl (possibly recursively) on each + * command-line argument. + * + * @return Either @c EXIT_FAILURE or @c EXIT_SUCCESS. If everything + * goes as expected, we return @c EXIT_SUCCESS. Otherwise, we return + * @c EXIT_FAILURE. + */ int main(int argc, char* argv[]) { - /* - * Call apply_default_acl on each command-line argument. - */ + if (argc < 2) { usage(argv[0]); return EXIT_FAILURE; -- 2.44.2