capng_c 0.1.6 → 0.1.7

data/ext/capng/capng.c

@@ -13,21 +13,50 @@
 
 #include <capng.h>
 
-struct CapNG {};
-
-static void capng_free(void* capng);
-
-static const rb_data_type_t rb_capng_type = {
-  "capng/capng",
-  {
-    0,
-    capng_free,
-    0,
-  },
-  NULL,
-  NULL,
-  RUBY_TYPED_FREE_IMMEDIATELY
-};
+/* clang-format off */
+/*
+ * Document-class: CapNG
+ *
+ * CapNG class.
+ *
+ * @example
+ *  # Current process capability example
+ *  require 'capng'
+ *
+ *  @capng = CapNG.new(:current_process)
+ *  @capng.have_capability?(:effective, :dac_read_search)
+ *
+ * @example
+ *  # Other process capability example
+ *  require 'capng'
+ *
+ *  @capng = CapNG.new(:other_process, 12345)
+ *  @capng.have_capability?(:effective, :dac_override)
+ *
+ * @example
+ *  # File capability example
+ *  require 'capng'
+ *
+ *  @capng = CapNG.new(:file, "/path/to/file")
+ *  @capng.have_capability?(:effective, :chown)
+ */
+/* clang-format on */
+
+struct CapNG
+{};
+
+static void
+capng_free(void* capng);
+
+static const rb_data_type_t rb_capng_type = { "capng/capng",
+                                              {
+                                                0,
+                                                capng_free,
+                                                0,
+                                              },
+                                              NULL,
+                                              NULL,
+                                              RUBY_TYPED_FREE_IMMEDIATELY };
 
 static void
 capng_free(void* ptr)
@@ -40,19 +69,27 @@ rb_capng_alloc(VALUE klass)
 {
   VALUE obj;
   struct CapNG* capng;
-  obj = TypedData_Make_Struct(
-    klass, struct CapNG, &rb_capng_type, capng);
+  obj = TypedData_Make_Struct(klass, struct CapNG, &rb_capng_type, capng);
   return obj;
 }
 
+/*
+ * Initalize CapNG class.
+ *
+ * @overload initialize(target=nil, pid_or_file=nil)
+ *   @option param target [String or Symbol] Specify capability target.
+ *   @option param pid_or_file [String or Symbol] Querying XPath.
+ * @return [nil]
+ *
+ */
 static VALUE
-rb_capng_initialize(int argc, VALUE *argv, VALUE self)
+rb_capng_initialize(int argc, VALUE* argv, VALUE self)
 {
   VALUE rb_target, rb_pid_or_file;
   int result = 0;
-  char *target = NULL;
+  char* target = NULL;
   int pid = 0, fd = 0;
-  rb_io_t *fptr = NULL;
+  rb_io_t* fptr = NULL;
 
   rb_scan_args(argc, argv, "02", &rb_target, &rb_pid_or_file);
 
@@ -96,29 +133,46 @@ rb_capng_initialize(int argc, VALUE *argv, VALUE self)
   return Qnil;
 }
 
+/*
+ * Retrieve capability API status code on [CapNG#initialize] and file capability target.
+ *
+ * @return [@return_code]
+ *
+ */
 static VALUE
 rb_capng_return_code(VALUE self)
 {
   return rb_iv_get(self, "@return_code");
 }
 
+/*
+ * Clear capabilities on specified target.
+ *
+ * @param rb_select_name_or_enum [Symbol or String or Fixnum] targets are CAPS, BOUNDS,
+ *   BOTH, and AMBIENT for supported platform.
+ *
+ * @return [nil]
+ *
+ */
 static VALUE
 rb_capng_clear(VALUE self, VALUE rb_select_name_or_enum)
 {
   capng_select_t select = 0;
 
   switch (TYPE(rb_select_name_or_enum)) {
-  case T_SYMBOL:
-    select = select_name_to_select_type(RSTRING_PTR(rb_sym2str(rb_select_name_or_enum)));
-    break;
-  case T_STRING:
-    select = select_name_to_select_type(StringValuePtr(rb_select_name_or_enum));
-    break;
-  case T_FIXNUM:
-    select = NUM2INT(rb_select_name_or_enum);
-    break;
-  default:
-    rb_raise(rb_eArgError, "Expected a String or a Symbol instance, or a capability type constant");
+    case T_SYMBOL:
+      select =
+        select_name_to_select_type(RSTRING_PTR(rb_sym2str(rb_select_name_or_enum)));
+      break;
+    case T_STRING:
+      select = select_name_to_select_type(StringValuePtr(rb_select_name_or_enum));
+      break;
+    case T_FIXNUM:
+      select = NUM2INT(rb_select_name_or_enum);
+      break;
+    default:
+      rb_raise(rb_eArgError,
+               "Expected a String or a Symbol instance, or a capability type constant");
   }
 
   capng_clear(select);
@@ -126,23 +180,34 @@ rb_capng_clear(VALUE self, VALUE rb_select_name_or_enum)
   return Qnil;
 }
 
+/*
+ * Fill capabilities on specified target.
+ *
+ * @param rb_select_name_or_enum [Symbol or String or Fixnum] targets are CAPS, BOUNDS,
+ *   BOTH, and AMBIENT for supported platform.
+ *
+ * @return [nil]
+ *
+ */
 static VALUE
 rb_capng_fill(VALUE self, VALUE rb_select_name_or_enum)
 {
   capng_select_t select = 0;
 
   switch (TYPE(rb_select_name_or_enum)) {
-  case T_SYMBOL:
-    select = select_name_to_select_type(RSTRING_PTR(rb_sym2str(rb_select_name_or_enum)));
-    break;
-  case T_STRING:
-    select = select_name_to_select_type(StringValuePtr(rb_select_name_or_enum));
-    break;
-  case T_FIXNUM:
-    select = NUM2INT(rb_select_name_or_enum);
-    break;
-  default:
-    rb_raise(rb_eArgError, "Expected a String or a Symbol instance, or a capability type constant");
+    case T_SYMBOL:
+      select =
+        select_name_to_select_type(RSTRING_PTR(rb_sym2str(rb_select_name_or_enum)));
+      break;
+    case T_STRING:
+      select = select_name_to_select_type(StringValuePtr(rb_select_name_or_enum));
+      break;
+    case T_FIXNUM:
+      select = NUM2INT(rb_select_name_or_enum);
+      break;
+    default:
+      rb_raise(rb_eArgError,
+               "Expected a String or a Symbol instance, or a capability type constant");
   }
 
   capng_fill(select);
@@ -150,6 +215,14 @@ rb_capng_fill(VALUE self, VALUE rb_select_name_or_enum)
   return Qnil;
 }
 
+/*
+ * Specify process ID to retrieve other process capabilities.
+ *
+ * @param rb_pid [Fixnum] Process ID.
+ *
+ * @return [nil]
+ *
+ */
 static VALUE
 rb_capng_setpid(VALUE self, VALUE rb_pid)
 {
@@ -160,6 +233,13 @@ rb_capng_setpid(VALUE self, VALUE rb_pid)
   return Qnil;
 }
 
+/*
+ * Specify process ID to retrieve process capabilities.  If not
+ * calling #setpid before, it returns current process' capabilities.
+ *
+ * @return [Boolean]
+ *
+ */
 static VALUE
 rb_capng_get_caps_process(VALUE self)
 {
@@ -172,9 +252,21 @@ rb_capng_get_caps_process(VALUE self)
     return Qfalse;
 }
 
+/*
+ * Update capabilities.
+ *
+ * @param rb_action_name_or_action [Symbol or String or Fixnum] ADD or DROP.
+ * @param rb_capability_name_or_type [Symbol or String or Fixnum]
+ *   Effective/Inheritable/Permitted/Ambient (If supported) or their combinations
+ * @param rb_capability_or_name [Symbol or String or Fixnum] Capability name or constants.
+ *
+ * @see: [CapNG::Capability])
+ *
+ * @return [Boolean]
+ */
 static VALUE
-rb_capng_update(VALUE self,
-                VALUE rb_action_name_or_action, VALUE rb_capability_name_or_type, VALUE rb_capability_or_name)
+rb_capng_update(VALUE self, VALUE rb_action_name_or_action,
+                VALUE rb_capability_name_or_type, VALUE rb_capability_or_name)
 {
   int result = 0;
   unsigned int capability = 0;
@@ -182,45 +274,52 @@ rb_capng_update(VALUE self,
   capng_act_t action = 0;
 
   switch (TYPE(rb_action_name_or_action)) {
-  case T_SYMBOL:
-    action = action_name_to_action_type(RSTRING_PTR(rb_sym2str(rb_action_name_or_action)));
-    break;
-  case T_STRING:
-    action = action_name_to_action_type(StringValuePtr(rb_action_name_or_action));
-    break;
-  case T_FIXNUM:
-    action = NUM2INT(rb_action_name_or_action);
-    break;
-  default:
-    rb_raise(rb_eArgError, "Expected a String or a Symbol instance, or a capability type constant");
+    case T_SYMBOL:
+      action =
+        action_name_to_action_type(RSTRING_PTR(rb_sym2str(rb_action_name_or_action)));
+      break;
+    case T_STRING:
+      action = action_name_to_action_type(StringValuePtr(rb_action_name_or_action));
+      break;
+    case T_FIXNUM:
+      action = NUM2INT(rb_action_name_or_action);
+      break;
+    default:
+      rb_raise(rb_eArgError,
+               "Expected a String or a Symbol instance, or a capability type constant");
   }
 
   switch (TYPE(rb_capability_name_or_type)) {
-  case T_SYMBOL:
-    capability_type = capability_type_name_to_capability_type(RSTRING_PTR(rb_sym2str(rb_capability_name_or_type)));
-    break;
-  case T_STRING:
-    capability_type = capability_type_name_to_capability_type(StringValuePtr(rb_capability_name_or_type));
-    break;
-  case T_FIXNUM:
-    capability_type = NUM2INT(rb_capability_name_or_type);
-    break;
-  default:
-    rb_raise(rb_eArgError, "Expected a String or a Symbol instance, or a capability type constant");
+    case T_SYMBOL:
+      capability_type = capability_type_name_to_capability_type(
+        RSTRING_PTR(rb_sym2str(rb_capability_name_or_type)));
+      break;
+    case T_STRING:
+      capability_type = capability_type_name_to_capability_type(
+        StringValuePtr(rb_capability_name_or_type));
+      break;
+    case T_FIXNUM:
+      capability_type = NUM2INT(rb_capability_name_or_type);
+      break;
+    default:
+      rb_raise(rb_eArgError,
+               "Expected a String or a Symbol instance, or a capability type constant");
   }
 
   switch (TYPE(rb_capability_or_name)) {
-  case T_SYMBOL:
-    capability = capng_name_to_capability(RSTRING_PTR(rb_sym2str(rb_capability_or_name)));
-    break;
-  case T_STRING:
-    capability = capng_name_to_capability(StringValuePtr(rb_capability_or_name));
-    break;
-  case T_FIXNUM:
-    capability = NUM2INT(rb_capability_or_name);
-    break;
-  default:
-    rb_raise(rb_eArgError, "Expected a String or a Symbol instance, or a capability constant");
+    case T_SYMBOL:
+      capability =
+        capng_name_to_capability(RSTRING_PTR(rb_sym2str(rb_capability_or_name)));
+      break;
+    case T_STRING:
+      capability = capng_name_to_capability(StringValuePtr(rb_capability_or_name));
+      break;
+    case T_FIXNUM:
+      capability = NUM2INT(rb_capability_or_name);
+      break;
+    default:
+      rb_raise(rb_eArgError,
+               "Expected a String or a Symbol instance, or a capability constant");
   }
 
   result = capng_update(action, capability_type, capability);
@@ -231,6 +330,15 @@ rb_capng_update(VALUE self,
     return Qfalse;
 }
 
+/*
+ * Apply capabilities on specified target.
+ *
+ * @param rb_select_name_or_enum [Symbol or String or Fixnum]
+ *   targets are CAPS, BOUNDS, BOTH, and AMBIENT for supported platform.
+ *
+ * @return [Boolean]
+ *
+ */
 static VALUE
 rb_capng_apply(VALUE self, VALUE rb_select_name_or_enum)
 {
@@ -238,17 +346,19 @@ rb_capng_apply(VALUE self, VALUE rb_select_name_or_enum)
   capng_select_t select = 0;
 
   switch (TYPE(rb_select_name_or_enum)) {
-  case T_SYMBOL:
-    select = select_name_to_select_type(RSTRING_PTR(rb_sym2str(rb_select_name_or_enum)));
-    break;
-  case T_STRING:
-    select = select_name_to_select_type(StringValuePtr(rb_select_name_or_enum));
-    break;
-  case T_FIXNUM:
-    select = NUM2INT(rb_select_name_or_enum);
-    break;
-  default:
-    rb_raise(rb_eArgError, "Expected a String or a Symbol instance, or a capability type constant");
+    case T_SYMBOL:
+      select =
+        select_name_to_select_type(RSTRING_PTR(rb_sym2str(rb_select_name_or_enum)));
+      break;
+    case T_STRING:
+      select = select_name_to_select_type(StringValuePtr(rb_select_name_or_enum));
+      break;
+    case T_FIXNUM:
+      select = NUM2INT(rb_select_name_or_enum);
+      break;
+    default:
+      rb_raise(rb_eArgError,
+               "Expected a String or a Symbol instance, or a capability type constant");
   }
 
   result = capng_apply(select);
@@ -259,6 +369,12 @@ rb_capng_apply(VALUE self, VALUE rb_select_name_or_enum)
     return Qfalse;
 }
 
+/*
+ * Lock capabilities.
+ *
+ * @return [Boolean]
+ *
+ */
 static VALUE
 rb_capng_lock(VALUE self)
 {
@@ -272,6 +388,14 @@ rb_capng_lock(VALUE self)
     return Qfalse;
 }
 
+/*
+ *  Change the credentials retaining capabilities.
+ * @param rb_uid [Fixnum] User ID.
+ * @param rb_gid [Fixnum] Group ID.
+ * @param rb_flags [Fixnum] CapNG::Flags constants.
+ *
+ * @see: capng_change_id(3)
+ */
 static VALUE
 rb_capng_change_id(VALUE self, VALUE rb_uid, VALUE rb_gid, VALUE rb_flags)
 {
@@ -282,9 +406,20 @@ rb_capng_change_id(VALUE self, VALUE rb_uid, VALUE rb_gid, VALUE rb_flags)
   if (result == 0)
     return Qtrue;
   else
-    rb_raise(rb_eRuntimeError, "Calling capng_change_id is failed with: (exitcode: %d)\n", result);
+    rb_raise(rb_eRuntimeError,
+             "Calling capng_change_id is failed with: (exitcode: %d)\n",
+             result);
 }
 
+/*
+ * Check whether capabilities on specified target or not.
+ *
+ * @param rb_select_name_or_enum [Symbol or String or Fixnum]
+ *   targets are CAPS, BOUNDS, BOTH, and AMBIENT for supported platform.
+ *
+ * @return [Integer]
+ *
+ */
 static VALUE
 rb_capng_have_capabilities_p(VALUE self, VALUE rb_select_name_or_enum)
 {
@@ -292,56 +427,77 @@ rb_capng_have_capabilities_p(VALUE self, VALUE rb_select_name_or_enum)
   capng_select_t select = 0;
 
   switch (TYPE(rb_select_name_or_enum)) {
-  case T_SYMBOL:
-    select = select_name_to_select_type(RSTRING_PTR(rb_sym2str(rb_select_name_or_enum)));
-    break;
-  case T_STRING:
-    select = select_name_to_select_type(StringValuePtr(rb_select_name_or_enum));
-    break;
-  case T_FIXNUM:
-    select = NUM2INT(rb_select_name_or_enum);
-    break;
-  default:
-    rb_raise(rb_eArgError, "Expected a String or a Symbol instance, or a capability type constant");
+    case T_SYMBOL:
+      select =
+        select_name_to_select_type(RSTRING_PTR(rb_sym2str(rb_select_name_or_enum)));
+      break;
+    case T_STRING:
+      select = select_name_to_select_type(StringValuePtr(rb_select_name_or_enum));
+      break;
+    case T_FIXNUM:
+      select = NUM2INT(rb_select_name_or_enum);
+      break;
+    default:
+      rb_raise(rb_eArgError,
+               "Expected a String or a Symbol instance, or a capability type constant");
   }
   result = capng_have_capabilities(select);
 
   return INT2NUM(result);
 }
 
+/*
+ * Check whether capabilities on specified target or not.
+ *
+ * @param rb_capability_name_or_type [Symbol or String or Fixnum] types are EFFECTIVE,
+ *   INHERITABLE, PERMITTED, and AMBIENT for supported platform.
+ * @param rb_capability_or_name [Symbol or String or Fixnum]
+ *   Capability name or constants.
+ *
+ * @see: [CapNG::Capability]
+ *
+ * @return [Boolean]
+ *
+ */
 static VALUE
-rb_capng_have_capability_p(VALUE self, VALUE rb_capability_name_or_type, VALUE rb_capability_or_name)
+rb_capng_have_capability_p(VALUE self, VALUE rb_capability_name_or_type,
+                           VALUE rb_capability_or_name)
 {
   int result = 0;
   unsigned int capability = 0;
   capng_type_t capability_type = 0;
 
   switch (TYPE(rb_capability_name_or_type)) {
-  case T_SYMBOL:
-    capability_type = capability_type_name_to_capability_type(RSTRING_PTR(rb_sym2str(rb_capability_name_or_type)));
-    break;
-  case T_STRING:
-    capability_type = capability_type_name_to_capability_type(StringValuePtr(rb_capability_name_or_type));
-    break;
-  case T_FIXNUM:
-    capability_type = NUM2INT(rb_capability_name_or_type);
-    break;
-  default:
-    rb_raise(rb_eArgError, "Expected a String or a Symbol instance, or a capability type constant");
+    case T_SYMBOL:
+      capability_type = capability_type_name_to_capability_type(
+        RSTRING_PTR(rb_sym2str(rb_capability_name_or_type)));
+      break;
+    case T_STRING:
+      capability_type = capability_type_name_to_capability_type(
+        StringValuePtr(rb_capability_name_or_type));
+      break;
+    case T_FIXNUM:
+      capability_type = NUM2INT(rb_capability_name_or_type);
+      break;
+    default:
+      rb_raise(rb_eArgError,
+               "Expected a String or a Symbol instance, or a capability type constant");
   }
 
   switch (TYPE(rb_capability_or_name)) {
-  case T_SYMBOL:
-    capability = capng_name_to_capability(RSTRING_PTR(rb_sym2str(rb_capability_or_name)));
-    break;
-  case T_STRING:
-    capability = capng_name_to_capability(StringValuePtr(rb_capability_or_name));
-    break;
-  case T_FIXNUM:
-    capability = NUM2INT(rb_capability_or_name);
-    break;
-  default:
-    rb_raise(rb_eArgError, "Expected a String or a Symbol instance, or a capability constant");
+    case T_SYMBOL:
+      capability =
+        capng_name_to_capability(RSTRING_PTR(rb_sym2str(rb_capability_or_name)));
+      break;
+    case T_STRING:
+      capability = capng_name_to_capability(StringValuePtr(rb_capability_or_name));
+      break;
+    case T_FIXNUM:
+      capability = NUM2INT(rb_capability_or_name);
+      break;
+    default:
+      rb_raise(rb_eArgError,
+               "Expected a String or a Symbol instance, or a capability constant");
   }
 
   result = capng_have_capability(capability_type, capability);
@@ -352,11 +508,19 @@ rb_capng_have_capability_p(VALUE self, VALUE rb_capability_name_or_type, VALUE r
     return Qfalse;
 }
 
+/*
+ * Retrieve capabilities from file.
+ *
+ * @param rb_file [File] target file object
+ *
+ * @return [Boolean]
+ *
+ */
 static VALUE
 rb_capng_get_caps_file(VALUE self, VALUE rb_file)
 {
   int result = 0, fd = 0;
-  rb_io_t *fptr = NULL;
+  rb_io_t* fptr = NULL;
 
   Check_Type(rb_file, T_FILE);
 
@@ -373,11 +537,19 @@ rb_capng_get_caps_file(VALUE self, VALUE rb_file)
     return Qfalse;
 }
 
+/*
+ * Apply capabilities on specified target (file specific version).
+ *
+ * @param rb_file [File] target file object
+ *
+ * @return [Boolean]
+ *
+ */
 static VALUE
 rb_capng_apply_caps_file(VALUE self, VALUE rb_file)
 {
   int result = 0, fd = 0;
-  rb_io_t *fptr = NULL;
+  rb_io_t* fptr = NULL;
 
   Check_Type(rb_file, T_FILE);
 
@@ -395,7 +567,6 @@ rb_capng_apply_caps_file(VALUE self, VALUE rb_file)
     return Qfalse;
 }
 
-
 void
 Init_capng(void)
 {