Update: rename f_file_change_owner() to f_file_change_role().

Change owner implies changing the owner.
This is not strictly true, due to how the chown() and similar POSIX functions works.

Instead, these change owner and/or group.
To avoid confusion with thinking this function exclusively changes owner, use a completely different word.
The chosen word is "role".

diff --git a/level_0/f_file/c/file.c b/level_0/f_file/c/file.c
index 2c6bbe62d432ba263f94b462b4138cb9820d7377..d110ec183f0fc8f830ea7cbc60873eae7cb9478d 100644 (file)
--- a/level_0/f_file/c/file.c
+++ b/level_0/f_file/c/file.c
@@ -48,29 +48,29 @@ extern "C" {
   }
 #endif // _di_f_file_change_mode_at_
 
-#ifndef _di_f_file_change_owner_
-  f_return_status f_file_change_owner(const f_string path, const uid_t uid, const gid_t gid, const bool dereference) {
+#ifndef _di_f_file_change_role_
+  f_return_status f_file_change_role(const f_string path, const uid_t uid, const gid_t gid, const bool dereference) {
     #ifndef _di_level_0_parameter_checking_
       if (path == 0) return F_status_set_error(F_parameter);
       if (uid < 0 && gid < 0) return F_status_set_error(F_parameter);
       if (uid < -1 || gid < -1) return F_status_set_error(F_parameter);
     #endif // _di_level_0_parameter_checking_
 
-    return private_f_file_change_owner(path, uid, gid, dereference);
+    return private_f_file_change_role(path, uid, gid, dereference);
   }
-#endif // _di_f_file_change_owner_
+#endif // _di_f_file_change_role_
 
-#ifndef _di_f_file_change_owner_at_
-  f_return_status f_file_change_owner_at(const int at_id, const f_string path, const uid_t uid, const gid_t gid, const int flag) {
+#ifndef _di_f_file_change_role_at_
+  f_return_status f_file_change_role_at(const int at_id, const f_string path, const uid_t uid, const gid_t gid, const int flag) {
     #ifndef _di_level_0_parameter_checking_
       if (path == 0) return F_status_set_error(F_parameter);
       if (uid < 0 && gid < 0) return F_status_set_error(F_parameter);
       if (uid < -1 || gid < -1) return F_status_set_error(F_parameter);
     #endif // _di_level_0_parameter_checking_
 
-    return private_f_file_change_owner_at(at_id, path, uid, gid, flag);
+    return private_f_file_change_role_at(at_id, path, uid, gid, flag);
   }
-#endif // _di_f_file_change_owner_at_
+#endif // _di_f_file_change_role_at_
 
 #ifndef _di_f_file_clone_
   f_return_status f_file_clone(const f_string source, const f_string destination, const bool role, const f_number_unsigned size_block, const bool exclusive) {
@@ -97,7 +97,7 @@ extern "C" {
       }
 
       if (role) {
-        status = private_f_file_change_owner(destination, source_stat.st_uid, source_stat.st_gid, F_false);
+        status = private_f_file_change_role(destination, source_stat.st_uid, source_stat.st_gid, F_false);
         if (F_status_is_error(status)) return status;
       }
 
@@ -116,7 +116,7 @@ extern "C" {
       if (F_status_is_error(status)) return status;
 
       if (role) {
-        status = private_f_file_change_owner(destination, source_stat.st_uid, source_stat.st_gid, F_false);
+        status = private_f_file_change_role(destination, source_stat.st_uid, source_stat.st_gid, F_false);
         if (F_status_is_error(status)) return status;
       }
 

diff --git a/level_0/f_file/c/file.h b/level_0/f_file/c/file.h
index 4b87692543a2347cf27420047e82dd9cd42b7be7..080b1bc06cda4edcf2de4f8d7301e34bb4c0face 100644 (file)
--- a/level_0/f_file/c/file.h
+++ b/level_0/f_file/c/file.h
@@ -382,14 +382,18 @@ extern "C" {
 #endif // _di_f_file_change_mode_at_
 
 /**
- * Change owner and group of a given file at the specified path.
+ * Change owner and/or group of a given file at the specified path.
+ *
+ * At least one of uid or gid must not be -1.
  *
  * @param path
  *   The path file name.
  * @param uid
  *   The new user id to use.
+ *   Set to -1 to not change.
  * @param gid
  *   The new group id to use.
+ *   Set to -1 to not change.
  * @param dereference
  *   Set to TRUE to dereferenc symlinks (often is what is desired).
  *   Set to FALSE to operate on the symlink itself.
@@ -413,12 +417,14 @@ extern "C" {
  * @see chown()
  * @see lchown()
  */
-#ifndef _di_f_file_change_owner_
-  extern f_return_status f_file_change_owner(const f_string path, const uid_t uid, const gid_t gid, const bool dereference);
-#endif // _di_f_file_change_owner_
+#ifndef _di_f_file_change_role_
+  extern f_return_status f_file_change_role(const f_string path, const uid_t uid, const gid_t gid, const bool dereference);
+#endif // _di_f_file_change_role_
 
 /**
- * Change owner and group of a given file at the specified path.
+ * Change owner and/or group of a given file at the specified path.
+ *
+ * At least one of uid or gid must not be -1.
  *
  * @param at_id
  *   The parent directory, as an open directory file descriptor, in which path is relative to.
@@ -426,8 +432,10 @@ extern "C" {
  *   The path file name.
  * @param uid
  *   The new user id to use.
+ *   Set to -1 to not change.
  * @param gid
  *   The new group id to use.
+ *   Set to -1 to not change.
  * @param flag
  *   Any valid flag, such as f_file_at_path_empty, f_file_at_automount_no, or f_file_at_symlink_follow_no.
  *
@@ -450,9 +458,9 @@ extern "C" {
  *
  * @see fchownat()
  */
-#ifndef _di_f_file_change_owner_at_
-  extern f_return_status f_file_change_owner_at(const int at_id, const f_string path, const uid_t uid, const gid_t gid, const int flag);
-#endif // _di_f_file_change_owner_at_
+#ifndef _di_f_file_change_role_at_
+  extern f_return_status f_file_change_role_at(const int at_id, const f_string path, const uid_t uid, const gid_t gid, const int flag);
+#endif // _di_f_file_change_role_at_
 
 /**
  * Copy a file, as well as its file mode and possibly the owner and group.

diff --git a/level_0/f_file/c/private-file.c b/level_0/f_file/c/private-file.c
index 01eda4b0b16ea275be336485c705a164ceb76355..b592f3f63ed4bcbe6102247e8f706d318ee02b75 100644 (file)
--- a/level_0/f_file/c/private-file.c
+++ b/level_0/f_file/c/private-file.c
@@ -50,8 +50,8 @@ extern "C" {
   }
 #endif // !defined(_di_f_file_change_mode_at_) || !defined(_di_f_file_copy_at_)
 
-#if !defined(_di_f_file_change_owner_) || !defined(_di_f_file_copy_)
-  f_return_status private_f_file_change_owner(const f_string path, const uid_t uid, const gid_t gid, const bool dereference) {
+#if !defined(_di_f_file_change_role_) || !defined(_di_f_file_copy_)
+  f_return_status private_f_file_change_role(const f_string path, const uid_t uid, const gid_t gid, const bool dereference) {
     int result = 0;
 
     if (dereference) {
@@ -97,10 +97,10 @@ extern "C" {
 
     return F_none;
   }
-#endif // !defined(_di_f_file_change_owner_) || !defined(_di_f_file_copy_)
+#endif // !defined(_di_f_file_change_role_) || !defined(_di_f_file_copy_)
 
-#if !defined(_di_f_file_change_owner_at_) || !defined(_di_f_file_copy_at_)
-  f_return_status private_f_file_change_owner_at(const int at_id, const f_string path, const uid_t uid, const gid_t gid, const int flag) {
+#if !defined(_di_f_file_change_role_at_) || !defined(_di_f_file_copy_at_)
+  f_return_status private_f_file_change_role_at(const int at_id, const f_string path, const uid_t uid, const gid_t gid, const int flag) {
     int result = 0;
 
     if (uid != -1) {
@@ -132,7 +132,7 @@ extern "C" {
 
     return F_none;
   }
-#endif // !defined(_di_f_file_change_owner_at_) || !defined(_di_f_file_copy_at_)
+#endif // !defined(_di_f_file_change_role_at_) || !defined(_di_f_file_copy_at_)
 
 #if !defined(_di_f_file_close_) || !defined(_di_f_file_copy_)
   f_return_status private_f_file_close(int *id) {

diff --git a/level_0/f_file/c/private-file.h b/level_0/f_file/c/private-file.h
index 13d9e377cbd4b8914c9722e8c7d8db586f6b1547..7d045a580f12e10cad572207b7b92812fc5014ce 100644 (file)
--- a/level_0/f_file/c/private-file.h
+++ b/level_0/f_file/c/private-file.h
@@ -79,7 +79,7 @@ extern "C" {
 #endif // !defined(_di_f_file_change_mode_at_)
 
 /**
- * Private implementation of f_file_change_owner().
+ * Private implementation of f_file_change_role().
  *
  * Intended to be shared to each of the different implementation variations.
  *
@@ -109,15 +109,15 @@ extern "C" {
  *   F_read_only (with error bit) if file is read-only.
  *   F_failure (with error bit) for any other error.
  *
- * @see f_file_change_owner()
+ * @see f_file_change_role()
  * @see f_file_copy()
  */
-#if !defined(_di_f_file_change_owner_) || !defined(_di_f_file_copy_)
-  extern f_return_status private_f_file_change_owner(const f_string path, const uid_t uid, const gid_t gid, const bool dereference) f_gcc_attribute_visibility_internal;
-#endif // !defined(_di_f_file_change_owner_) || !defined(_di_f_file_copy_)
+#if !defined(_di_f_file_change_role_) || !defined(_di_f_file_copy_)
+  extern f_return_status private_f_file_change_role(const f_string path, const uid_t uid, const gid_t gid, const bool dereference) f_gcc_attribute_visibility_internal;
+#endif // !defined(_di_f_file_change_role_) || !defined(_di_f_file_copy_)
 
 /**
- * Private implementation of f_file_change_owner_at().
+ * Private implementation of f_file_change_role_at().
  *
  * Intended to be shared to each of the different implementation variations.
  *
@@ -149,11 +149,11 @@ extern "C" {
  *   F_read_only (with error bit) if file is read-only.
  *   F_failure (with error bit) for any other error.
  *
- * @see f_file_change_owner_at()
+ * @see f_file_change_role_at()
  */
-#if !defined(_di_f_file_change_owner_at_)
-  extern f_return_status private_f_file_change_owner_at(const int at_id, const f_string path, const uid_t uid, const gid_t gid, const int flag) f_gcc_attribute_visibility_internal;
-#endif // !defined(_di_f_file_change_owner_at_)
+#if !defined(_di_f_file_change_role_at_)
+  extern f_return_status private_f_file_change_role_at(const int at_id, const f_string path, const uid_t uid, const gid_t gid, const int flag) f_gcc_attribute_visibility_internal;
+#endif // !defined(_di_f_file_change_role_at_)
 
 /**
  * Private implementation of f_file_close().

diff --git a/level_1/fl_directory/c/directory.c b/level_1/fl_directory/c/directory.c
index f2080849837649dd9aa8de229ddf1efd3a8b24ac..e268c869f037fa2fef8318cca6682e885041b49c 100644 (file)
--- a/level_1/fl_directory/c/directory.c
+++ b/level_1/fl_directory/c/directory.c
@@ -41,7 +41,7 @@ extern "C" {
     }
 
     if (role) {
-      status = f_file_change_owner(destination, source_stat.st_uid, source_stat.st_gid, F_true);
+      status = f_file_change_role(destination, source_stat.st_uid, source_stat.st_gid, F_true);
       if (F_status_is_error(status)) return status;
     }
 

diff --git a/level_1/fl_directory/c/directory.h b/level_1/fl_directory/c/directory.h
index 83a744ecd1bf3a421f261345e617df1920b43a63..c584a46e8988e24a245ab6355d0267f38f6eb390 100644 (file)
--- a/level_1/fl_directory/c/directory.h
+++ b/level_1/fl_directory/c/directory.h
@@ -98,7 +98,7 @@ extern "C" {
  *   Errors from (with error bit): f_directory_create().
  *   Errors from (with error bit): f_directory_exists().
  *   Errors from (with error bit): f_file_change_mode().
- *   Errors from (with error bit): f_file_change_owner().
+ *   Errors from (with error bit): f_file_change_role().
  *   Errors from (with error bit): f_file_stat().
  *
  * @see f_file_clone()
@@ -220,7 +220,7 @@ extern "C" {
  *   Errors from (with error bit): f_directory_create().
  *   Errors from (with error bit): f_directory_exists().
  *   Errors from (with error bit): f_file_change_mode().
- *   Errors from (with error bit): f_file_change_owner().
+ *   Errors from (with error bit): f_file_change_role().
  *   Errors from (with error bit): f_file_stat().
  *
  * @see f_file_copy()

diff --git a/level_1/fl_directory/c/private-directory.c b/level_1/fl_directory/c/private-directory.c
index 40772ac8a7cc4d6f3ced813cf79686ee71033e9a..d42bae922a6e93ce390cc029966c5dc2bad4d570 100644 (file)
--- a/level_1/fl_directory/c/private-directory.c
+++ b/level_1/fl_directory/c/private-directory.c
@@ -121,7 +121,7 @@ extern "C" {
         }
 
         if (role) {
-          status = f_file_change_owner(destination_sub.string, source_stat.st_uid, source_stat.st_gid, F_true);
+          status = f_file_change_role(destination_sub.string, source_stat.st_uid, source_stat.st_gid, F_true);
           if (F_status_is_error(status)) break;
         }
       }