2. Group manipulation API

Data Structures
struct	cgroup
	Structure describing one or more control groups. More...
struct	cgroup_controller
	Structure describing a controller attached to one struct `cgroup`, including parameters of the group and their values. 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.

Function Documentation

struct cgroup_controller* cgroup_add_controller	(	struct cgroup *	cgroup,
		const char *	name
	)			`[read]`

Attach new controller to cgroup.

This function just modifies internal libcgroup structure, not the kernel control group.

Parameters:

	cgroup
	name	Name of the controller, e.g. "freezer".

Returns:: Created controller or NULL on error.

int cgroup_add_value_bool	(	struct cgroup_controller *	controller,
		const char *	name,
		bool	value
	)

Add parameter and its value to internal libcgroup structures.

Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.

Parameters:

	controller
	name	Name of the parameter.
	value

int cgroup_add_value_int64	(	struct cgroup_controller *	controller,
		const char *	name,
		int64_t	value
	)

Add parameter and its value to internal libcgroup structures.

Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel. Content of the value is copied to internal structures and is not needed after return from the function.

Parameters:

	controller
	name	Name of the parameter.
	value

int cgroup_add_value_string	(	struct cgroup_controller *	controller,
		const char *	name,
		const char *	value
	)

Add parameter and its value to internal libcgroup structures.

Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.

Parameters:

	controller
	name	Name of the parameter.
	value

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.

Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.

Parameters:

	controller
	name	Name of the parameter.
	value

int cgroup_compare_cgroup	(	struct cgroup *	cgroup_a,
		struct cgroup *	cgroup_b
	)

Compare names, owners, controllers, parameters and values of two groups.

Parameters:

	cgroup_a
	cgroup_b

Return values:

	0	if the groups are the same.
	ECGROUPNOTEQUAL	if the groups are not the same.
	ECGCONTROLLERNOTEQUAL	if the only difference are controllers, parameters or their values.

int cgroup_compare_controllers	(	struct cgroup_controller *	cgca,
		struct cgroup_controller *	cgcb
	)

Compare names, parameters and values of two controllers.

Parameters:

	cgca
	cgcb

Return values:

	0	if the controllers are the same.
	ECGCONTROLLERNOTEQUAL	if the controllers are not equal.

int cgroup_copy_cgroup	(	struct cgroup *	dst,
		struct cgroup *	src
	)

Copy all controllers, parameters and their values.

All existing controllers in the source group are discarded.

Parameters:

	dst	Destination group.
	src	Source group.

int cgroup_create_cgroup	(	struct cgroup *	cgroup,
		int	ignore_ownership
	)

Physically create a control group in kernel.

The group is created in all hierarchies, which cover controllers added by cgroup_add_controller(). All parameters set by cgroup_add_value_* functions are written. The created groups has owner which was set by cgroup_set_uid_gid().

Parameters:

	cgroup
	ignore_ownership	When nozero, all errors are ignored when setting owner of the group and/or its tasks file.

Todo:: what is ignore_ownership good for?

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.

The group is created in all hierarchies, where the parent group exists. I.e. following code creates subgroup in all hierarchies, because all of them have root (=parent) group.

 struct cgroup *foo = cgroup_new_cgroup("foo");
 cgroup_create_cgroup_from_parent(foo, 0);

Todo:: what is this good for? Why the list of controllers added by cgroup_add_controller() is not used, like in cgroup_create_cgroup()? I can't crate subgroup of root group in just one hierarchy with this function!

Parameters:

	cgroup	The cgroup to create. Only it's name is used, everything else is discarded.
	ignore_ownership	When nozero, all errors are ignored when setting owner of the group and/or its tasks file.

Todo:: what is ignore_ownership good for?

int cgroup_delete_cgroup	(	struct cgroup *	cgroup,
		int	ignore_migration
	)

Physically remove a control group from kernel.

The group is removed from all hierarchies, which cover controllers added by cgroup_add_controller() or cgroup_get_cgroup(). All tasks inside the group are automatically moved to parent group.

The group being removed must be empty, i.e. without subgroups. Use cgroup_delete_cgroup_ext() for recursive delete.

Parameters:

	cgroup
	ignore_migration	When nozero, all errors are ignored when migrating tasks from the group to the parent group.

Todo:: what is ignore_migration good for? rmdir() will fail if tasks were not moved.

int cgroup_delete_cgroup_ext	(	struct cgroup *	cgroup,
		int	flags
	)

Physically remove a control group from kernel.

All tasks are automatically moved to parent group. If CGFLAG_DELETE_IGNORE_MIGRATION flag is used, the errors that occurred during the task movement are ignored. CGFLAG_DELETE_RECURSIVE flag specifies that all subgroups should be removed too. If root group is being removed with this flag specified, all subgroups are removed but the root group itself is left undeleted.

See also:: cgroup_delete_flag.

Parameters:

	cgroup
	flags	Combination of CGFLAG_DELETE_* flags, which indicate what and how to delete.

void cgroup_free ( struct cgroup ** cgroup )

Free internal cgroup structure.

This function frees also all controllers attached to the cgroup, including all parameters and their values.

Parameters:

cgroup

void cgroup_free_controllers ( struct cgroup * cgroup )

Free internal list of controllers from the group.

Todo:: should this function be public???

Parameters:

cgroup

int cgroup_get_cgroup ( struct cgroup * cgroup )

Read all information regarding the group from kernel.

Based on name of the group, list of controllers and all parameters and their values are read from all hierarchies, where a group with given name exists. All existing controllers are replaced. I.e. following code will fill root with controllers from all hierarchies, because the root group is available in all of them.

 struct cgroup *root = cgroup_new_cgroup("/");
 cgroup_get_cgroup(root);

Todo:: what is this function good for? Why is not considered only the list of controllers attached by cgroup_add_controller()? What owners will return cgroup_get_uid_gid() if the group is in multiple hierarchies, each with different owner of tasks file?

Parameters:

cgroup

The cgroup to load. Only it's name is used, everything else is replaced.

struct cgroup_controller* cgroup_get_controller	(	struct cgroup *	cgroup,
		const char *	name
	)			`[read]`

Return appropriate controller from given group.

The controller must be added before using cgroup_add_controller() or loaded from kernel using cgroup_get_cgroup().

Parameters:

	cgroup
	name	Name of the controller, e.g. "freezer".

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.

The data is read from libcgroup internal cgroup structure, use cgroup_set_uid_gid() or cgroup_get_cgroup() to fill it.

int cgroup_get_value_bool	(	struct cgroup_controller *	controller,
		const char *	name,
		bool *	value
	)

Read a parameter value from libcgroup internal structures.

Use cgroup_get_cgroup() to fill these structures with data from kernel.

Parameters:

	controller
	name	Name of the parameter.
	value

int cgroup_get_value_int64	(	struct cgroup_controller *	controller,
		const char *	name,
		int64_t *	value
	)

Read a parameter value from libcgroup internal structures.

Use cgroup_get_cgroup() to fill these structures with data from kernel.

Parameters:

	controller
	name	Name of the parameter.
	value

char* cgroup_get_value_name	(	struct cgroup_controller *	controller,
		int	index
	)

Return the name of parameter of controller at given index.

The index goes from 0 to cgroup_get_value_name_count()-1. Use this function to list all parameter of the controller.

Note:: The returned value is pointer to internal libcgroup structure, do not free it.

Parameters:

	controller
	index	Index of the parameter.

Returns:: Name of the parameter.

int cgroup_get_value_name_count ( struct cgroup_controller * controller )

Return the number of variables for the specified controller in libcgroup internal structures.

Use cgroup_get_cgroup() to fill these structures with data from kernel. Use this function together with cgroup_get_value_name() to list all parameters of a group.

Parameters:

controller

Returns:: Count of the parameters or -1 on error.

int cgroup_get_value_string	(	struct cgroup_controller *	controller,
		const char *	name,
		char **	value
	)

Read a parameter value from libcgroup internal structures.

Use cgroup_get_cgroup() to fill these structures with data from kernel. It's up to the caller to free returned value.

This function works only for 'short' parameters. Use cgroup_read_stats_begin(), cgroup_read_stats_next() and cgroup_read_stats_end() to read stats parameter, which can be longer than libcgroup's internal buffers.

Todo:: rephrase, it's too vague... How big is the buffer actually?

Parameters:

	controller
	name	Name of the parameter.
	value

int cgroup_get_value_uint64	(	struct cgroup_controller *	controller,
		const char *	name,
		u_int64_t *	value
	)

Read a parameter value from libcgroup internal structures.

Use cgroup_get_cgroup() to fill these structures with data from kernel.

Parameters:

	controller
	name	Name of the parameter.
	value

int cgroup_modify_cgroup ( struct cgroup * cgroup )

Physically modify a control group in kernel.

All parameters added by cgroup_add_value_ or cgroup_set_value_ are written. Currently it's not possible to change and owner of a group.

Parameters:

cgroup

struct cgroup* cgroup_new_cgroup ( const char * name ) [read]

Allocate new cgroup structure.

This function itself does not create new control group in kernel, only new struct cgroup inside libcgroup!

Parameters:

name Path to the group, relative from root group. Use "/" or "." for the root group itself and "/foo/bar/baz" or "foo/bar/baz" for subgroups.

Todo:: suggest one preferred way, either "/foo" or "foo".

Returns:: Created group or NULL on error.

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.

This function modifies only libcgroup internal cgroup structure, use cgroup_create_cgroup() afterwards to create the group with given owners.

Parameters:

	cgroup
	tasks_uid	UID of the owner of group's `tasks` file.
	tasks_gid	GID of the owner of group's `tasks` file.
	control_uid	UID of the owner of group's control files (i.e. parameters).
	control_gid	GID of the owner of group's control files (i.e. parameters).

int cgroup_set_value_bool	(	struct cgroup_controller *	controller,
		const char *	name,
		bool	value
	)

Set a parameter value in libcgroup internal structures.

Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.

Parameters:

	controller
	name	Name of the parameter.
	value

int cgroup_set_value_int64	(	struct cgroup_controller *	controller,
		const char *	name,
		int64_t	value
	)

Set a parameter value in libcgroup internal structures.

Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel. Content of the value is copied to internal structures and is not needed after return from the function.

Parameters:

	controller
	name	Name of the parameter.
	value

int cgroup_set_value_string	(	struct cgroup_controller *	controller,
		const char *	name,
		const char *	value
	)

Set a parameter value in libcgroup internal structures.

Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.

Parameters:

	controller
	name	Name of the parameter.
	value

int cgroup_set_value_uint64	(	struct cgroup_controller *	controller,
		const char *	name,
		u_int64_t	value
	)

Set a parameter value in libcgroup internal structures.

Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.

Parameters:

	controller
	name	Name of the parameter.
	value

2. Group manipulation API

Data Structures

Basic infrastructure

Group manipulation API

Other functions

Group parameters

Function Documentation