4. Manipulation with tasks

Simple task assignment
Applications can use following functions to simply put a task into given control group and find a groups where given tasks is.
int	cgroup_attach_task (struct cgroup *cgroup)
	Move current task (=thread) to given control group.
int	cgroup_attach_task_pid (struct cgroup *cgroup, pid_t tid)
	Move given task (=thread) to to given control group.
int	cgroup_change_cgroup_path (const char *path, pid_t pid, const char *const controllers[])
	Changes the cgroup of a task based on the path provided.
int	cgroup_get_current_controller_path (pid_t pid, const char *controller, char **current_path)
	Get the current control group path where the given task is.
Rules
libcgroup can move tasks to control groups using simple rules, loaded from configuration file. See cgrules.conf man page to see format of the file. Following functions can be used to load these rules from a file.
int	cgroup_init_rules_cache (void)
	Initializes the rules cache and load it from /etc/cgrules.conf.
int	cgroup_reload_cached_rules (void)
	Reloads the rules list from /etc/cgrules.conf.
void	cgroup_print_rules_config (FILE *fp)
	Print the cached rules table.
Rule based task assignment
libcgroup can move tasks to control groups using simple rules, loaded from configuration file. See cgrules.conf man page to see format of the file. Applications can move tasks to control groups based on these rules using following functions.
int	cgroup_change_cgroup_flags (uid_t uid, gid_t gid, const char *procname, pid_t pid, int flags)
	Changes the cgroup of a program based on the rules in the config file.
int	cgroup_change_cgroup_uid_gid_flags (uid_t uid, gid_t gid, pid_t pid, int flags)
	Changes the cgroup of a program based on the rules in the config file.
int	cgroup_change_cgroup_uid_gid (uid_t uid, gid_t gid, pid_t pid)
	Provides backwards-compatibility with older versions of the API.
Communication with cgrulesengd daemon
Users can use cgrulesengd daemon to move tasks to groups based on the rules automatically when they change their UID, GID or executable name. The daemon allows tasks to be 'sticky', i.e. all rules are ignored for these tasks and the daemon never moves them.
int	cgroup_register_unchanged_process (pid_t pid, int flags)
	Register the unchanged process to a cgrulesengd daemon.

---

Function Documentation

int cgroup_attach_task

(

struct cgroup *

cgroup

)

Move current task (=thread) to given control group.

Parameters:

cgroup

Destination control group.

int cgroup_attach_task_pid	(	struct cgroup *	cgroup,
		pid_t	tid
	)

Move given task (=thread) to to given control group.

Parameters:

	cgroup	Destination control group.
	tid	The task to move.

int cgroup_change_cgroup_flags	(	uid_t	uid,
		gid_t	gid,
		const char *	procname,
		pid_t	pid,
		int	flags
	)

Changes the cgroup of a program based on the rules in the config file.

If a rule exists for the given UID, GID or PROCESS NAME, then the given PID is placed into the correct group. By default, this function parses the configuration file each time it is called.

The flags can alter the behavior of this function: CGFLAG_USECACHE: Use cached rules instead of parsing the config file

This function may NOT be thread safe.

Parameters:

	uid	The UID to match.
	gid	The GID to match.
	procname	The PROCESS NAME to match.
	pid	The PID of the process to move.
	flags	Bit flags to change the behavior, as defined in enum cgflags.

Todo:

Determine thread-safeness and fix of not safe.

int cgroup_change_cgroup_path	(	const char *	path,
		pid_t	pid,
		const char *const	controllers[]
	)

Changes the cgroup of a task based on the path provided.

In this case, the user must already know into which cgroup the task should be placed and no rules will be parsed.

Parameters:

	path	Name of the destination group.
	pid	The task to move.
	controllers	List of controllers.

Todo:

should this function be really public?

int cgroup_change_cgroup_uid_gid	(	uid_t	uid,
		gid_t	gid,
		pid_t	pid
	)

Provides backwards-compatibility with older versions of the API.

This function is deprecated, and cgroup_change_cgroup_uid_gid_flags() should be used instead. In fact, this function simply calls the newer one with flags set to 0 (none).

Parameters:

	uid	The UID to match.
	gid	The GID to match.
	pid	The PID of the process to move.

int cgroup_change_cgroup_uid_gid_flags	(	uid_t	uid,
		gid_t	gid,
		pid_t	pid,
		int	flags
	)

Changes the cgroup of a program based on the rules in the config file.

If a rule exists for the given UID or GID, then the given PID is placed into the correct group. By default, this function parses the configuration file each time it is called.

This function may NOT be thread safe.

Parameters:

	uid	The UID to match.
	gid	The GID to match.
	pid	The PID of the process to move.
	flags	Bit flags to change the behavior, as defined in enum cgflags.

Todo:

Determine thread-safeness and fix if not safe.

int cgroup_get_current_controller_path	(	pid_t	pid,
		const char *	controller,
		char **	current_path
	)

Get the current control group path where the given task is.

Parameters:

	pid	The task to find.
	controller	The controller (hierarchy), where to find the task.
	current_path	The path to control group, where the task has been found. The patch is relative to the root of the hierarchy. The caller must free this memory.

int cgroup_init_rules_cache

(

void

)

Initializes the rules cache and load it from /etc/cgrules.conf.

Todo:

add parameter with the filename?

void cgroup_print_rules_config

(

FILE *

fp

)

Print the cached rules table.

This function should be called only after first calling cgroup_parse_config(), but it will work with an empty rule list.

Parameters:

fp

Destination file, where the rules will be printed.

int cgroup_register_unchanged_process	(	pid_t	pid,
		int	flags
	)

Register the unchanged process to a cgrulesengd daemon.

This process is never moved to another control group by the daemon. If the daemon does not work, this function returns 0 as success.

Parameters:

	pid	The task id.
	flags	Bit flags to change the behavior, as defined in cgroup_daemon_type

int cgroup_reload_cached_rules

(

void

)

Reloads the rules list from /etc/cgrules.conf.

This function is probably NOT thread safe (calls cgroup_parse_rules_config()).