include/libcgroup/groups.h File Reference

#include <features.h>
#include <sys/types.h>
#include <stdbool.h>

Enumerations
enum	cgroup_delete_flag { CGFLAG_DELETE_IGNORE_MIGRATION = 1, CGFLAG_DELETE_RECURSIVE = 2 }
	Flags for cgroup_delete_cgroup_ext(). More...
Basic infrastructure
struct cgroup* is the heart of libcgroup API. The structure is opaque to applications, all access to the structure is through appropriate functions. The most important information is that one struct cgroup* can represent zero, one or more real control groups in kernel. The struct cgroup* is identified by name of the group, which must be set by cgroup_new_cgroup(). Multiple controllers (aka subsystems) can be attached to one struct cgroup* using cgroup_add_controller(). These controllers can belong to different hierarchies. This approach is different to the one in the Linux kernel - a control group must be part of exactly one hierarchy there. In libcgroup, a group can be part of multiple hierarchies, as long as the group name is the same. Example: Let there be following control groups: cpu,cpuacct:/ cpu,cpuacct:/foo cpu,cpuacct:/bar freezer:/ freezer:/foo I.e. there is cpu and cpuacct controller mounted together in one hierarchy, with foo and bar groups. In addition, freezer is mounted as separate hierarchy, with only one foo group. Following code creates struct cgroup* structure, which represents one group cpu,cpuacct:/foo: struct cgroup *foo = cgroup_new_cgroup("foo"); cgroup_add_controller(foo, "cpu"); Now, you can call e.g. cgroup_delete_cgroup() and the group is deleted from the hierarchy. You can note that it's enough to add only one controller to the group to fully identify a group in cpu,cpuacct hierarchy. Following code creates struct cgroup* structure, which represents two groups, cpu,cpuacct:/foo and freezer:/foo: struct cgroup *foo = cgroup_new_cgroup("foo"); cgroup_add_controller(foo, "cpu"); cgroup_add_controller(foo, "freezer"); Now, if you call e.g. cgroup_delete_cgroup(), the group gets deleted from both hierarchies. Todo: add some propaganda what's so great on this approach... I personally think it is broken and confusing (see TODOs below). Following functions are provided to create/destroy various libcgroup structures. Please note that none of these functions actually create or delete a cgroup in kernel!
struct cgroup *	cgroup_new_cgroup (const char *name)
	Allocate new cgroup structure.
struct cgroup_controller *	cgroup_add_controller (struct cgroup *cgroup, const char *name)
	Attach new controller to cgroup.
struct cgroup_controller *	cgroup_get_controller (struct cgroup *cgroup, const char *name)
	Return appropriate controller from given group.
void	cgroup_free (struct cgroup **cgroup)
	Free internal cgroup structure.
void	cgroup_free_controllers (struct cgroup *cgroup)
	Free internal list of controllers from the group.
Group manipulation API
Using following functions you can create and remove control groups and change their parameters. Note: All access to kernel is through previously mounted cgroup filesystems. libcgroup does not mount/unmount anything for you.
int	cgroup_create_cgroup (struct cgroup *cgroup, int ignore_ownership)
	Physically create a control group in kernel.
int	cgroup_create_cgroup_from_parent (struct cgroup *cgroup, int ignore_ownership)
	Physically create new control group in kernel, with all parameters and values copied from its parent group.
int	cgroup_modify_cgroup (struct cgroup *cgroup)
	Physically modify a control group in kernel.
int	cgroup_delete_cgroup (struct cgroup *cgroup, int ignore_migration)
	Physically remove a control group from kernel.
int	cgroup_delete_cgroup_ext (struct cgroup *cgroup, int flags)
	Physically remove a control group from kernel.
Other functions
Helper functions to manipulate with control groups.
int	cgroup_get_cgroup (struct cgroup *cgroup)
	Read all information regarding the group from kernel.
int	cgroup_copy_cgroup (struct cgroup *dst, struct cgroup *src)
	Copy all controllers, parameters and their values.
int	cgroup_compare_cgroup (struct cgroup *cgroup_a, struct cgroup *cgroup_b)
	Compare names, owners, controllers, parameters and values of two groups.
int	cgroup_compare_controllers (struct cgroup_controller *cgca, struct cgroup_controller *cgcb)
	Compare names, parameters and values of two controllers.
int	cgroup_set_uid_gid (struct cgroup *cgroup, uid_t tasks_uid, gid_t tasks_gid, uid_t control_uid, gid_t control_gid)
	Set owner of the group control files and the tasks file.
int	cgroup_get_uid_gid (struct cgroup *cgroup, uid_t *tasks_uid, gid_t *tasks_gid, uid_t *control_uid, gid_t *control_gid)
	Return owners of the group's tasks file and control files.
Group parameters
These are functions can read or modify parameter of a group. Note: All these functions read/write parameters to libcgorup internal structures. Use cgroup_get_cgroup() to load parameters from kernel to these internal structures and cgroup_modify_cgroup() or cgroup_create_cgroup() to write changes to kernel.
int	cgroup_add_value_string (struct cgroup_controller *controller, const char *name, const char *value)
	Add parameter and its value to internal libcgroup structures.
int	cgroup_add_value_int64 (struct cgroup_controller *controller, const char *name, int64_t value)
	Add parameter and its value to internal libcgroup structures.
int	cgroup_add_value_uint64 (struct cgroup_controller *controller, const char *name, u_int64_t value)
	Add parameter and its value to internal libcgroup structures.
int	cgroup_add_value_bool (struct cgroup_controller *controller, const char *name, bool value)
	Add parameter and its value to internal libcgroup structures.
int	cgroup_get_value_string (struct cgroup_controller *controller, const char *name, char **value)
	Read a parameter value from libcgroup internal structures.
int	cgroup_get_value_int64 (struct cgroup_controller *controller, const char *name, int64_t *value)
	Read a parameter value from libcgroup internal structures.
int	cgroup_get_value_uint64 (struct cgroup_controller *controller, const char *name, u_int64_t *value)
	Read a parameter value from libcgroup internal structures.
int	cgroup_get_value_bool (struct cgroup_controller *controller, const char *name, bool *value)
	Read a parameter value from libcgroup internal structures.
int	cgroup_set_value_string (struct cgroup_controller *controller, const char *name, const char *value)
	Set a parameter value in libcgroup internal structures.
int	cgroup_set_value_int64 (struct cgroup_controller *controller, const char *name, int64_t value)
	Set a parameter value in libcgroup internal structures.
int	cgroup_set_value_uint64 (struct cgroup_controller *controller, const char *name, u_int64_t value)
	Set a parameter value in libcgroup internal structures.
int	cgroup_set_value_bool (struct cgroup_controller *controller, const char *name, bool value)
	Set a parameter value in libcgroup internal structures.
int	cgroup_get_value_name_count (struct cgroup_controller *controller)
	Return the number of variables for the specified controller in libcgroup internal structures.
char *	cgroup_get_value_name (struct cgroup_controller *controller, int index)
	Return the name of parameter of controller at given index.

---

Enumeration Type Documentation

enum cgroup_delete_flag

Flags for cgroup_delete_cgroup_ext().

Enumerator:

CGFLAG_DELETE_IGNORE_MIGRATION	Ignore errors caused by migration of tasks to parent group.
CGFLAG_DELETE_RECURSIVE	Recursively delete all child groups.