Add missing "flags" parameter documentation to the safe_open() functions.

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

diff --git a/src/libadacl.c b/src/libadacl.c
index 08b13b82395941b90956129499de8a3450177ace..d4e99aa2e48106ab51c806afc719f7890d2240c9 100644 (file)
--- a/src/libadacl.c
+++ b/src/libadacl.c
@@ -26,6 +26,15 @@
 #include "libadacl.h"
 
 
+/* Even though most other library functions reliably return -1 for
+ * error, it feels a little wrong to re-use the ACL_ERROR constant.
+ */
+#define CLOSE_ERROR -1
+#define OPEN_ERROR -1
+#define SNPRINTF_ERROR -1
+#define STAT_ERROR -1
+
+
 /**
  * @brief The recursive portion of the @c safe_open function, used to
  *   open a file descriptor in a symlink-safe way when combined with
@@ -37,6 +46,9 @@
  * @param pathname
  *   The path to the file/directory/whatever whose descriptor you want.
  *
+ * @param flags
+ *   File status flags to be passed to @c openat.
+ *
  * @return a file descriptor for @c pathname if everything goes well,
  *   and @c OPEN_ERROR if not.
  */
@@ -97,6 +109,9 @@ int safe_open_ex(int at_fd, char* pathname, int flags) {
  * @param pathname
  *   The path to the file/directory/whatever whose descriptor you want.
  *
+ * @param flags
+ *   File status flags to be passed to @c openat.
+ *
  * @return a file descriptor for @c pathname if everything goes well,
  *   and @c OPEN_ERROR if not.
  */
@@ -600,8 +615,7 @@ int wipe_acls(int fd) {
  *
  * @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_FAILURE - If symlinks or hard links are encountered.
  *   - @c ACL_ERROR - Unexpected library error.
  */
 int apply_default_acl_ex(const char* path,
@@ -851,7 +865,7 @@ int apply_default_acl_ex(const char* path,
  *
  * @return
  *   - @c ACL_SUCCESS - The parent default ACL was inherited successfully.
- *   - @c ACL_FAILURE - The target path is not a regular file/directory,
+ *   - @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.
  */