Add comments explainining the acl_create_entry() gymnastics.

diff --git a/src/apply-default-acl.c b/src/apply-default-acl.c
index 022e2b87a6cc97e3816f6b84cd23d4a4910d4c8c..54cf66a6ca523ce0f5d78252d9a0643dcf850ec0 100644 (file)
--- a/src/apply-default-acl.c
+++ b/src/apply-default-acl.c
@@ -269,7 +269,13 @@ int acl_set_entry(acl_t* aclp,
      ACL. */
   acl_entry_t new_entry;
 
-  /* We allocate memory here that we should release! */
+  /* 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.
+   */
   int c_result = acl_create_entry(aclp, &new_entry);
   if (c_result == ACL_ERROR) {
     perror("acl_set_entry (acl_create_entry)");
@@ -815,7 +821,22 @@ int apply_default_acl(const char* path, bool no_exec_mask) {
       }
     }
 
-    /* Finally, add the permset to the access ACL. */
+    /* 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".
+     */
     int set_result = acl_set_entry(&acl, entry);
     if (set_result == ACL_ERROR) {
       perror("apply_default_acl (acl_set_entry)");