libadacl: update failure return value docs for apply_default_acl().

[apply-default-acl.git] / src / libadacl.c

/**
 * @file libadacl.c
 *
 * @brief The adacl (apply default acl) shared library.
 *
 */

/* Enables get_current_dir_name() in unistd.h */
#define _GNU_SOURCE

#include <errno.h>    /* ELOOP, EINVAL, etc. */
#include <fcntl.h>    /* openat() */
#include <libgen.h>   /* basename(), dirname() */
#include <limits.h>   /* PATH_MAX */
#include <stdbool.h>  /* the "bool" type */
#include <stdio.h>    /* perror(), snprintf() */
#include <stdlib.h>   /* free() */
#include <string.h>   /* strdup() */
#include <sys/stat.h> /* fstat() */
#include <unistd.h>   /* get_current_dir_name() */

/* ACLs */
#include <acl/libacl.h> /* acl_get_perm, not portable */
#include <sys/acl.h>    /* all other acl_foo functions */

#include "libadacl.h"


/**
 * @brief The recursive portion of the @c safe_open function, used to
 *   open a file descriptor in a symlink-safe way when combined with
 *   the @c O_NOFOLLOW flag.
 *
 * @param at_fd
 *   A file descriptor relative to which @c pathname will be opened.
 *
 * @param pathname
 *   The path to the file/directory/whatever whose descriptor you want.
 *
 * @return a file descriptor for @c pathname if everything goes well,
 *   and @c OPEN_ERROR if not.
 */
int safe_open_ex(int at_fd, char* pathname, int flags) {
  if (pathname != NULL && strlen(pathname) == 0) {
    /* Oops, went one level to deep with nothing to do. */
    return at_fd;
  }

  char* firstslash = strchr(pathname, '/');
  if (firstslash == NULL) {
    /* No more slashes, this is the base case. */
    int r = openat(at_fd, pathname, flags);
    return r;
  }

  /* Temporarily disable the slash, so that the subsequent call to
     openat() opens only the next directory (and doesn't recurse). */
   *firstslash = '\0';
   int fd = safe_open_ex(at_fd, pathname, flags);
   if (fd == OPEN_ERROR) {
     if (errno != ELOOP) {
       /* Don't output anything if we ignore a symlink */
       perror("safe_open_ex (safe_open_ex)");
     }
     return OPEN_ERROR;
   }

   /* The ++ is safe because there needs to be at least a null byte
      after the first slash, even if it's the last real character in
      the string. */
   int result = safe_open_ex(fd, firstslash+1, flags);
   if (close(fd) == CLOSE_ERROR) {
      perror("safe_open_ex (close)");
      return OPEN_ERROR;
    }
   return result;
}


/**
 * @brief A version of @c open that is completely symlink-safe when
 *   used with the @c O_NOFOLLOW flag.
 *
 * The @c openat function exists to ensure that you can anchor one
 * path to a particular directory while opening it; however, if you
 * open "b/c/d" relative to "/a", then even the @c openat function will
 * still follow symlinks in the "b" component. This can be exploited
 * by an attacker to make you open the wrong path.
 *
 * To avoid that problem, this function uses a recursive
 * implementation that opens every path from the root, one level at a
 * time. So "a" is opened relative to "/", and then "b" is opened
 * relative to "/a", and then "c" is opened relative to "/a/b",
 * etc. When the @c O_NOFOLLOW flag is used, this approach ensures
 * that no symlinks in any component are followed.
 *
 * @param pathname
 *   The path to the file/directory/whatever whose descriptor you want.
 *
 * @return a file descriptor for @c pathname if everything goes well,
 *   and @c OPEN_ERROR if not.
 */
int safe_open(const char* pathname, int flags) {
  if (pathname == NULL || strlen(pathname) == 0 || pathname[0] == '\0') {
    errno = EINVAL;
    perror("safe_open (args)");
    return OPEN_ERROR;
  }

  char abspath[PATH_MAX];
  int snprintf_result = 0;
  if (strchr(pathname, '/') == pathname) {
    /* pathname is already absolute; just copy it. */
    snprintf_result = snprintf(abspath, PATH_MAX, "%s", pathname);
  }
  else {
    /* Concatenate the current working directory and pathname into an
     * absolute path. We use realpath() ONLY on the cwd part, and not
     * on the pathname part, because realpath() resolves symlinks. And
     * the whole point of all this crap is to avoid following symlinks
     * in the pathname.
     *
     * Using realpath() on the cwd lets us operate on relative paths
     * while we're sitting in a directory that happens to have a
     * symlink in it; for example: cd /var/run && apply-default-acl foo.
     */
    char* cwd = get_current_dir_name();
    if (cwd == NULL) {
      perror("safe_open (get_current_dir_name)");
      return OPEN_ERROR;
    }

    char abs_cwd[PATH_MAX];
    if (realpath(cwd, abs_cwd) == NULL) {
      perror("safe_open (realpath)");
      free(cwd);
      return OPEN_ERROR;
    }
    snprintf_result = snprintf(abspath, PATH_MAX, "%s/%s", abs_cwd, pathname);
    free(cwd);
  }
  if (snprintf_result == SNPRINTF_ERROR || snprintf_result > PATH_MAX) {
    perror("safe_open (snprintf)");
    return OPEN_ERROR;
  }

  int fd = open("/", flags);
  if (strcmp(abspath, "/") == 0) {
    return fd;
  }

  int result = safe_open_ex(fd, abspath+1, flags);
  if (close(fd) == CLOSE_ERROR) {
    perror("safe_open (close)");
    return OPEN_ERROR;
  }
  return result;
}




/**
 * @brief Update (or create) an entry in an @b minimal ACL.
 *
 * This function will not work if @c aclp contains extended
 * entries. This is fine for our purposes, since we call @c wipe_acls
 * 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 @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
 *   A pointer to the acl_t structure whose entry we want to modify.
 *
 * @param entry
 *   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, @c ACL_ERROR is
 *   returned. Otherwise, @c ACL_SUCCESS.
 *
 */
int acl_set_entry(acl_t* aclp, acl_entry_t entry) {

  acl_tag_t entry_tag;
  if (acl_get_tag_type(entry, &entry_tag) == ACL_ERROR) {
    perror("acl_set_entry (acl_get_tag_type)");
    return ACL_ERROR;
  }

  acl_permset_t entry_permset;
  if (acl_get_permset(entry, &entry_permset) == ACL_ERROR) {
    perror("acl_set_entry (acl_get_permset)");
    return ACL_ERROR;
  }

  acl_entry_t existing_entry;
  /* Loop through the given ACL looking for matching entries. */
  int result = acl_get_entry(*aclp, ACL_FIRST_ENTRY, &existing_entry);

  while (result == ACL_SUCCESS) {
    acl_tag_t existing_tag = ACL_UNDEFINED_TAG;

    if (acl_get_tag_type(existing_entry, &existing_tag) == ACL_ERROR) {
       perror("set_acl_tag_permset (acl_get_tag_type)");
       return ACL_ERROR;
    }

    if (existing_tag == entry_tag) {
      if (entry_tag == ACL_USER_OBJ ||
          entry_tag == ACL_GROUP_OBJ ||
          entry_tag == ACL_OTHER) {
        /* Only update for these three since all other tags will have
           been wiped. These three are guaranteed to exist, so if we
           match one of them, we're allowed to return ACL_SUCCESS
           below and bypass the rest of the function. */
        acl_permset_t existing_permset;
        if (acl_get_permset(existing_entry, &existing_permset) == ACL_ERROR) {
          perror("acl_set_entry (acl_get_permset)");
          return ACL_ERROR;
        }

        if (acl_set_permset(existing_entry, entry_permset) == ACL_ERROR) {
          perror("acl_set_entry (acl_set_permset)");
          return ACL_ERROR;
        }

        return ACL_SUCCESS;
      }

    }

    result = acl_get_entry(*aclp, ACL_NEXT_ENTRY, &existing_entry);
  }

  /* This catches both the initial acl_get_entry and the ones at the
     end of the loop. */
  if (result == ACL_ERROR) {
    perror("acl_set_entry (acl_get_entry)");
    return ACL_ERROR;
  }

  /* If we've made it this far, we need to add a new entry to the
     ACL. */
  acl_entry_t new_entry;

  /* The acl_create_entry() function can allocate new memory and/or
   * change the location of the ACL structure entirely. When that
   * happens, the value pointed to by aclp is updated, which means
   * that a new acl_t gets "passed out" to our caller, eventually to
   * be fed to acl_free(). In other words, we should still be freeing
   * the right thing, even if the value pointed to by aclp changes.
   */
  if (acl_create_entry(aclp, &new_entry) == ACL_ERROR) {
    perror("acl_set_entry (acl_create_entry)");
    return ACL_ERROR;
  }

  if (acl_set_tag_type(new_entry, entry_tag) == ACL_ERROR) {
    perror("acl_set_entry (acl_set_tag_type)");
    return ACL_ERROR;
  }

  if (acl_set_permset(new_entry, entry_permset) == ACL_ERROR) {
    perror("acl_set_entry (acl_set_permset)");
    return ACL_ERROR;
  }

  if (entry_tag == ACL_USER || entry_tag == ACL_GROUP) {
    /* We need to set the qualifier too. */
    void* entry_qual = acl_get_qualifier(entry);
    if (entry_qual == (void*)NULL) {
      perror("acl_set_entry (acl_get_qualifier)");
      return ACL_ERROR;
    }

    if (acl_set_qualifier(new_entry, entry_qual) == ACL_ERROR) {
      perror("acl_set_entry (acl_set_qualifier)");
      return ACL_ERROR;
    }
  }

  return ACL_SUCCESS;
}



/**
 * @brief Determine the number of entries in the given ACL.
 *
 * @param acl
 *   The ACL to inspect.
 *
 * @return Either the non-negative number of entries in @c acl, or
 *   @c ACL_ERROR on error.
 */
int acl_entry_count(acl_t acl) {

  acl_entry_t entry;
  int entry_count = 0;
  int result = acl_get_entry(acl, ACL_FIRST_ENTRY, &entry);

  while (result == ACL_SUCCESS) {
    entry_count++;
    result = acl_get_entry(acl, ACL_NEXT_ENTRY, &entry);
  }

  if (result == ACL_ERROR) {
    perror("acl_entry_count (acl_get_entry)");
    return ACL_ERROR;
  }

  return entry_count;
}



/**
 * @brief Determine whether or not the given ACL is minimal.
 *
 * An ACL is minimal if it has fewer than four entries.
 *
 * @param acl
 *   The ACL whose minimality is in question.
 *
 * @return
 *   - @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) {

  int ec = acl_entry_count(acl);

  if (ec == ACL_ERROR) {
    perror("acl_is_minimal (acl_entry_count)");
    return ACL_ERROR;
  }

  if (ec < 4) {
    return ACL_SUCCESS;
  }
  else {
    return ACL_FAILURE;
  }
}



/**
 * @brief Determine whether the given ACL's mask denies execute.
 *
 * @param acl
 *   The ACL whose mask we want to check.
 *
 * @return
 *   - @c ACL_SUCCESS - The @c acl has a mask which denies execute.
 *   - @c ACL_FAILURE - The @c acl has a mask which does not deny execute.
 *   - @c ACL_ERROR - Unexpected library error.
 */
int acl_execute_masked(acl_t acl) {

  acl_entry_t entry;
  int ge_result = acl_get_entry(acl, ACL_FIRST_ENTRY, &entry);

  while (ge_result == ACL_SUCCESS) {
    acl_tag_t tag = ACL_UNDEFINED_TAG;

    if (acl_get_tag_type(entry, &tag) == ACL_ERROR) {
       perror("acl_execute_masked (acl_get_tag_type)");
       return ACL_ERROR;
    }

    if (tag == ACL_MASK) {
      /* This is the mask entry, get its permissions, and see if
         execute is specified. */
      acl_permset_t permset;

      if (acl_get_permset(entry, &permset) == ACL_ERROR) {
        perror("acl_execute_masked (acl_get_permset)");
        return ACL_ERROR;
      }

      int gp_result = acl_get_perm(permset, ACL_EXECUTE);
      if (gp_result == ACL_ERROR) {
        perror("acl_execute_masked (acl_get_perm)");
        return ACL_ERROR;
      }

      if (gp_result == ACL_FAILURE) {
        /* No execute bit set in the mask; execute not allowed. */
        return ACL_SUCCESS;
      }
    }

    ge_result = acl_get_entry(acl, ACL_NEXT_ENTRY, &entry);
  }

  return ACL_FAILURE;
}



/**
 * @brief Determine whether @c fd is executable by anyone.
 *
 *
 * This is used as part of the heuristic to determine whether or not
 * we should mask the execute bit when inheriting an ACL. If @c fd
 * describes a file, we check the @a effective permissions, contrary
 * to what setfacl does.
 *
 * @param fd
 *   The file descriptor to check.
 *
 * @param sp
 *   A pointer to a stat structure for @c fd.
 *
 * @return
 *   - @c ACL_SUCCESS - Someone has effective execute permissions on @c fd.
 *   - @c ACL_FAILURE - Nobody can execute @c fd.
 *   - @c ACL_ERROR - Unexpected library error.
 */
int any_can_execute(int fd, const struct stat* sp) {
  acl_t acl = acl_get_fd(fd);

  if (acl == (acl_t)NULL) {
    perror("any_can_execute (acl_get_file)");
    return ACL_ERROR;
  }

  /* Our return value. */
  int result = ACL_FAILURE;

  if (acl_is_minimal(acl)) {
    if (sp->st_mode & (S_IXUSR | S_IXOTH | S_IXGRP)) {
      result = ACL_SUCCESS;
      goto cleanup;
    }
    else {
      result = ACL_FAILURE;
      goto cleanup;
    }
  }

  acl_entry_t entry;
  int ge_result = acl_get_entry(acl, ACL_FIRST_ENTRY, &entry);

  while (ge_result == ACL_SUCCESS) {
    /* The first thing we do is check to see if this is a mask
       entry. If it is, we skip it entirely. */
    acl_tag_t tag = ACL_UNDEFINED_TAG;

    if (acl_get_tag_type(entry, &tag) == ACL_ERROR) {
      perror("any_can_execute_or (acl_get_tag_type)");
      result = ACL_ERROR;
      goto cleanup;
    }

    if (tag == ACL_MASK) {
      ge_result = acl_get_entry(acl, ACL_NEXT_ENTRY, &entry);
      continue;
    }

    /* Ok, so it's not a mask entry. Check the execute perms. */
    acl_permset_t permset;

    if (acl_get_permset(entry, &permset) == ACL_ERROR) {
      perror("any_can_execute_or (acl_get_permset)");
      result = ACL_ERROR;
      goto cleanup;
    }

    int gp_result = acl_get_perm(permset, ACL_EXECUTE);
    if (gp_result == ACL_ERROR) {
      perror("any_can_execute (acl_get_perm)");
      result = ACL_ERROR;
      goto cleanup;
    }

    if (gp_result == ACL_SUCCESS) {
      /* Only return ACL_SUCCESS if this execute bit is not masked. */
      if (acl_execute_masked(acl) != ACL_SUCCESS) {
        result = ACL_SUCCESS;
        goto cleanup;
      }
    }

    ge_result = acl_get_entry(acl, ACL_NEXT_ENTRY, &entry);
  }

  if (ge_result == ACL_ERROR) {
    perror("any_can_execute (acl_get_entry)");
    result = ACL_ERROR;
    goto cleanup;
  }

 cleanup:
  acl_free(acl);
  return result;
}



/**
 * @brief Set @c acl as the default ACL on @c path.
 *
 * This overwrites any existing default ACL on @c path. If @c path is
 * not a directory, we return ACL_ERROR and @c errno is set.
 *
 * @param path
 *   The target directory whose ACL we wish to replace or create.
 *
  * @param acl
 *   The ACL to set as default on @c path.
 *
 * @return
 *   - @c ACL_SUCCESS - The default ACL was assigned successfully.
 *   - @c ACL_ERROR - Unexpected library error.
 */
int assign_default_acl(const char* path, acl_t acl) {

  if (path == NULL) {
    errno = EINVAL;
    perror("assign_default_acl (args)");
    return ACL_ERROR;
  }

  /* Our return value; success unless something bad happens. */
  int result = ACL_SUCCESS;
  acl_t path_acl = acl_dup(acl);

  if (path_acl == (acl_t)NULL) {
    perror("assign_default_acl (acl_dup)");
    return ACL_ERROR; /* Nothing to clean up in this case. */
  }

  if (acl_set_file(path, ACL_TYPE_DEFAULT, path_acl) == ACL_ERROR) {
    perror("assign_default_acl (acl_set_file)");
    result = ACL_ERROR;
  }

  acl_free(path_acl);
  return result;
}



/**
 * @brief Remove all @c ACL_TYPE_ACCESS entries from the given file
 *   descriptor, leaving the UNIX permission bits.
 *
 * @param fd
 *   The file descriptor 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(int fd) {
  /* Initialize an empty ACL, and then overwrite the one on "fd" with it. */
  acl_t empty_acl = acl_init(0);

  if (empty_acl == (acl_t)NULL) {
    perror("wipe_acls (acl_init)");
    return ACL_ERROR;
  }

  if (acl_set_fd(fd, empty_acl) == ACL_ERROR) {
    perror("wipe_acls (acl_set_fd)");
    acl_free(empty_acl);
    return ACL_ERROR;
  }

  acl_free(empty_acl);
  return ACL_SUCCESS;
}



/**
 * @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.
 *
 * @param sp
 *   A pointer to a stat structure for @c path, or @c NULL if you don't
 *   have one handy.
 *
 * @param no_exec_mask
 *   The value (either true or false) of the --no-exec-mask flag.
 *
 * @return
 *   - @c ACL_SUCCESS - The parent default ACL was inherited successfully.
 *   - @c ACL_FAILURE - If symlinks or hard links are encountered.
 *   - @c ACL_ERROR - Unexpected library error.
 */
int apply_default_acl_ex(const char* path,
                         const struct stat* sp,
                         bool no_exec_mask) {

  if (path == NULL) {
    errno = EINVAL;
    perror("apply_default_acl_ex (args)");
    return ACL_ERROR;
  }

  /* Define these next three variables here because we may have to
   * jump to the cleanup routine which expects them to exist.
   */

  /* Our return value. */
  int result = ACL_SUCCESS;

  /* The default ACL on path's parent directory */
  acl_t defacl = (acl_t)NULL;

  /* The file descriptor corresponding to "path" */
  int fd = 0;

  /* Get the parent directory of "path" with dirname(), which happens
   * to murder its argument and necessitates a path_copy.
   */
  char* path_copy = strdup(path);
  if (path_copy == NULL) {
    perror("apply_default_acl_ex (strdup)");
    return ACL_ERROR;
  }
  char* parent = dirname(path_copy);

  fd = safe_open(path, O_NOFOLLOW);
  if (fd == OPEN_ERROR) {
    if (errno == ELOOP) {
      result = ACL_FAILURE; /* hit a symlink */
      goto cleanup;
    }
    else {
      perror("apply_default_acl_ex (open fd)");
      result = ACL_ERROR;
      goto cleanup;
    }
  }


  /* Refuse to operate on hard links, which can be abused by an
   * attacker to trick us into changing the ACL on a file we didn't
   * intend to; namely the "target" of the hard link. There is TOCTOU
   * race condition here, but the window is as small as possible
   * between when we open the file descriptor (look above) and when we
   * fstat it.
   *
   * Note: we only need to call fstat ourselves if we weren't passed a
   * valid pointer to a stat structure (nftw does that).
  */
  if (sp == NULL) {
    struct stat s;
    if (fstat(fd, &s) == STAT_ERROR) {
      perror("apply_default_acl_ex (fstat)");
      goto cleanup;
    }

    sp = &s;
  }

  if (!S_ISDIR(sp->st_mode)) {
    /* If it's not a directory, make sure it's a regular,
       non-hard-linked file. */
    if (!S_ISREG(sp->st_mode) || sp->st_nlink != 1) {
      result = ACL_FAILURE;
      goto cleanup;
    }
  }


  /* Default to not masking the exec bit; i.e. applying the default
     ACL literally. If --no-exec-mask was not specified, then we try
     to "guess" whether or not to mask the exec bit. This behavior
     is modeled after the capital 'X' perms of setfacl. */
  bool allow_exec = true;

  if (!no_exec_mask) {
    /* Never mask the execute bit on directories. */
    int ace_result = any_can_execute(fd,sp) || S_ISDIR(sp->st_mode);

    if (ace_result == ACL_ERROR) {
      perror("apply_default_acl_ex (any_can_execute)");
      result = ACL_ERROR;
      goto cleanup;
    }

    allow_exec = (bool)ace_result;
  }

  defacl = acl_get_file(parent, ACL_TYPE_DEFAULT);

  if (defacl == (acl_t)NULL) {
    perror("apply_default_acl_ex (acl_get_file)");
    result = ACL_ERROR;
    goto cleanup;
  }

  if (wipe_acls(fd) == ACL_ERROR) {
    perror("apply_default_acl_ex (wipe_acls)");
    result = ACL_ERROR;
    goto cleanup;
  }

  /* Do this after wipe_acls(), otherwise we'll overwrite the wiped
     ACL with this one. */
  acl_t acl = acl_get_fd(fd);
  if (acl == (acl_t)NULL) {
    perror("apply_default_acl_ex (acl_get_fd)");
    result = ACL_ERROR;
    goto cleanup;
  }

  /* If it's a directory, inherit the parent's default. We sure hope
   * that "path" still points to the same thing that "fd" and this
   * "sp" describe. If not, we may wind up trying to set a default ACL
   * on a file, and this will throw an error. I guess that's what we
   * want to do?
   */
  if (S_ISDIR(sp->st_mode) && assign_default_acl(path, defacl) == ACL_ERROR) {
    perror("apply_default_acl_ex (assign_default_acl)");
    result = ACL_ERROR;
    goto cleanup;
  }

  acl_entry_t entry;
  int ge_result = acl_get_entry(defacl, ACL_FIRST_ENTRY, &entry);

  while (ge_result == ACL_SUCCESS) {
    acl_tag_t tag = ACL_UNDEFINED_TAG;

    if (acl_get_tag_type(entry, &tag) == ACL_ERROR) {
       perror("apply_default_acl_ex (acl_get_tag_type)");
       result = ACL_ERROR;
       goto cleanup;
    }


    /* We've got an entry/tag from the default ACL. Get its permset. */
    acl_permset_t permset;
    if (acl_get_permset(entry, &permset) == ACL_ERROR) {
      perror("apply_default_acl_ex (acl_get_permset)");
      result = ACL_ERROR;
      goto cleanup;
    }

    /* If this is a default mask, fix it up. */
    if (tag == ACL_MASK ||
        tag == ACL_USER_OBJ ||
        tag == ACL_GROUP_OBJ ||
        tag == ACL_OTHER) {

      if (!allow_exec) {
        /* The mask doesn't affect acl_user_obj, acl_group_obj (in
           minimal ACLs) or acl_other entries, so if execute should be
           masked, we have to do it manually. */
        if (acl_delete_perm(permset, ACL_EXECUTE) == ACL_ERROR) {
          perror("apply_default_acl_ex (acl_delete_perm)");
          result = ACL_ERROR;
          goto cleanup;
        }

        if (acl_set_permset(entry, permset) == ACL_ERROR) {
          perror("apply_default_acl_ex (acl_set_permset)");
          result = ACL_ERROR;
          goto cleanup;
        }
      }
    }

    /* Finally, add the permset to the access ACL. It's actually
     * important that we pass in the address of "acl" here, and not
     * "acl" itself. Why? The call to acl_create_entry() within
     * acl_set_entry() can allocate new memory for the entry.
     * Sometimes that can be done in-place, in which case everything
     * is cool and the new memory gets released when we call
     * acl_free(acl).
     *
     * But occasionally, the whole ACL structure will have to be moved
     * in order to allocate the extra space. When that happens,
     * acl_create_entry() modifies the pointer it was passed (in this
     * case, &acl) to point to the new location. We want to call
     * acl_free() on the new location, and since acl_free() gets
     * called right here, we need acl_create_entry() to update the
     * value of "acl". To do that, it needs the address of "acl".
     */
    if (acl_set_entry(&acl, entry) == ACL_ERROR) {
      perror("apply_default_acl_ex (acl_set_entry)");
      result = ACL_ERROR;
      goto cleanup;
    }

    ge_result = acl_get_entry(defacl, ACL_NEXT_ENTRY, &entry);
  }

  /* Catches the first acl_get_entry as well as the ones at the end of
     the loop. */
  if (ge_result == ACL_ERROR) {
    perror("apply_default_acl_ex (acl_get_entry)");
    result = ACL_ERROR;
    goto cleanup;
  }

  if (acl_set_fd(fd, acl) == ACL_ERROR) {
    perror("apply_default_acl_ex (acl_set_fd)");
    result = ACL_ERROR;
    goto cleanup;
  }

 cleanup:
  free(path_copy);
  if (defacl != (acl_t)NULL) {
    acl_free(defacl);
  }
  if (fd >= 0 && close(fd) == CLOSE_ERROR) {
    perror("apply_default_acl_ex (close)");
    result = ACL_ERROR;
  }
  return result;
}



/**
 * @brief The friendly interface to @c apply_default_acl_ex.
 *
 * The @c apply_default_acl_ex function holds the real implementation
 * of this function, but it takes a weird second argument that most
 * people won't care about (a stat structure). But, we use that
 * argument for the recursive mode of the CLI, so it's there.
 *
 * If you don't have a stat structure for your @c path, use this instead.
 *
 * @param path
 *   The path whose ACL we would like to reset to its default.
 *
 * @param no_exec_mask
 *   The value (either true or false) of the --no-exec-mask flag.
 *
 * @return
 *   - @c ACL_SUCCESS - The parent default ACL was inherited successfully.
 *   - @c ACL_FAILURE - If symlinks or hard links are encountered.
 *     or the parent of @c path is not a directory.
 *   - @c ACL_ERROR - Unexpected library error.
 */
int apply_default_acl(const char* path, bool no_exec_mask) {
  return apply_default_acl_ex(path, NULL, no_exec_mask);
}