This file is indexed.

/usr/include/libcgroup/groups.h is in libcgroup-dev 0.37.1-1ubuntu10.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
#ifndef _LIBCGROUP_GROUPS_H
#define _LIBCGROUP_GROUPS_H

#ifndef _LIBCGROUP_H_INSIDE
#error "Only <libcgroup.h> should be included directly."
#endif

#ifndef SWIG
#include <features.h>
#include <sys/types.h>
#include <stdbool.h>
#endif

__BEGIN_DECLS

/**
 * Flags for cgroup_delete_cgroup_ext().
 */
enum cgroup_delete_flag {
	/**
	 * Ignore errors caused by migration of tasks to parent group.
	 */
	CGFLAG_DELETE_IGNORE_MIGRATION = 1,

	/**
	 * Recursively delete all child groups.
	 */
	CGFLAG_DELETE_RECURSIVE	= 2,
};

/**
 * @defgroup group_groups 2. Group manipulation API
 * @{
 *
 * @name Basic infrastructure
 * @{
 * <tt>struct cgroup*</tt> is the heart of @c libcgroup API.
 * The structure is opaque to applications, all access to the structure is
 * through appropriate functions.
 *
 * The most important information is that <b> one <tt>struct cgroup*</tt> can
 * represent zero, one or more real control groups in kernel</b>.
 * The <tt>struct cgroup*</tt> is identified by name of the group, which must be
 * set by cgroup_new_cgroup(). Multiple controllers (aka subsystems) can be
 * attached to one <tt>struct cgroup*</tt> using cgroup_add_controller(). These
 * controllers <b>can belong to different hierarchies</b>.
 *
 * This approach is different to the one in the Linux kernel - a control group
 * must be part of exactly one hierarchy there. In @c libcgroup, a group can be
 * part of multiple hierarchies, as long as the group name is the same.
 *
 * @par Example:
 * Let there be following control groups:
 * @code
 * cpu,cpuacct:/
 * cpu,cpuacct:/foo
 * cpu,cpuacct:/bar
 * freezer:/
 * freezer:/foo
 * @endcode
 * I.e. there is @c cpu and @c cpuacct controller mounted together in one
 * hierarchy, with @c foo and @c bar groups. In addition, @c freezer is
 * mounted as separate hierarchy, with only one @c foo group.
 *
 * @par
 * Following code creates <tt>struct cgroup*</tt> structure, which represents
 * one group <tt>cpu,cpuacct:/foo</tt>:
 * @code
 * struct cgroup *foo = cgroup_new_cgroup("foo");
 * cgroup_add_controller(foo, "cpu");
 * @endcode
 * 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 <tt>cpu,cpuacct</tt> hierarchy.
 *
 * @par
 * Following code creates <tt>struct cgroup*</tt> structure, which represents
 * @b two groups, <tt>cpu,cpuacct:/foo</tt> and <tt>freezer:/foo</tt>:
 * @code
 * struct cgroup *foo = cgroup_new_cgroup("foo");
 * cgroup_add_controller(foo, "cpu");
 * cgroup_add_controller(foo, "freezer");
 * @endcode
 * Now, if you call e.g. cgroup_delete_cgroup(), the group gets deleted from
 * @b 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
 *
 * Structure describing one or more control groups. The structure is opaque to
 * applications.
 */
struct cgroup;

/**
 * @struct cgroup_controller
 * Structure describing a controller attached to one struct @c cgroup, including
 * parameters of the group and their values. The structure is opaque to
 * applications.
 * @see groups
 */
struct cgroup_controller;


/**
 * Allocate new cgroup structure. This function itself does not create new
 * control group in kernel, only new <tt>struct cgroup</tt> inside libcgroup!
 *
 * @param name Path to the group, relative from root group. Use @c "/" or @c "."
 * 	for the root group itself and @c "/foo/bar/baz" or @c "foo/bar/baz" for
 * 	subgroups.
 * 	@todo suggest one preferred way, either "/foo" or "foo".
 * @returns Created group or NULL on error.
 */
struct cgroup *cgroup_new_cgroup(const char *name);

/**
 * Attach new controller to cgroup. This function just modifies internal
 * libcgroup structure, not the kernel control group.
 *
 * @param cgroup
 * @param name Name of the controller, e.g. "freezer".
 * @return Created controller or NULL on error.
 */
struct cgroup_controller *cgroup_add_controller(struct cgroup *cgroup,
						const char *name);

/**
 * Return appropriate controller from given group.
 * The controller must be added before using cgroup_add_controller() or loaded
 * from kernel using cgroup_get_cgroup().
 * @param cgroup
 * @param name Name of the controller, e.g. "freezer".
 */
struct cgroup_controller *cgroup_get_controller(struct cgroup *cgroup,
							const char *name);

/**
 * Free internal @c cgroup structure. This function frees also all controllers
 * attached to the @c cgroup, including all parameters and their values.
 * @param cgroup
 */
void cgroup_free(struct cgroup **cgroup);

/**
 * Free internal list of controllers from the group.
 * @todo should this function be public???
 * @param cgroup
 */
void cgroup_free_controllers(struct cgroup *cgroup);


/**
 * @}
 * @name 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.
 * @c libcgroup does not mount/unmount anything for you.
 * @{
 */

/**
 * 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().
 * @param cgroup
 * @param 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?
 * @retval #ECGROUPNOTEQUAL if not all specified controller parameters
 *      were successfully set.
 */
int cgroup_create_cgroup(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.
 * @code
 * struct cgroup *foo = cgroup_new_cgroup("foo");
 * cgroup_create_cgroup_from_parent(foo, 0);
 * @endcode
 * @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!
 *
 * @param cgroup The cgroup to create. Only it's name is used, everything else
 * 	is discarded.
 * @param 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?
 * @retval #ECGROUPNOTEQUAL if not all inherited controller parameters
 *      were successfully set (this is expected).
 */
int cgroup_create_cgroup_from_parent(struct cgroup *cgroup,
		int ignore_ownership);

/**
 * 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.
 *
 * @param cgroup
 */
int cgroup_modify_cgroup(struct cgroup *cgroup);

/**
 * 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.
 *
 * @param cgroup
 * @param 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(struct cgroup *cgroup, int ignore_migration);

/**
 * 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 cgroup_delete_flag.
 *
 * @param cgroup
 * @param flags Combination of CGFLAG_DELETE_* flags, which indicate what and
 *	how to delete.
 */
int cgroup_delete_cgroup_ext(struct cgroup *cgroup, int flags);


/**
 * @}
 * @name Other functions
 * @{
 * Helper functions to manipulate with control groups.
 */

/**
 * 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 @c root
 * with controllers from all hierarchies, because the root group is available in
 * all of them.
 * @code
 * struct cgroup *root = cgroup_new_cgroup("/");
 * cgroup_get_cgroup(root);
 * @endcode
 *
 * @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?
 *
 * @param cgroup The cgroup to load. Only it's name is used, everything else
 * 	is replaced.
 */
int cgroup_get_cgroup(struct cgroup *cgroup);

/**
 * Copy all controllers, parameters and their values. All existing controllers
 * in the source group are discarded.
 *
 * @param dst Destination group.
 * @param src Source group.
 */
int cgroup_copy_cgroup(struct cgroup *dst, struct cgroup *src);

/**
 * Compare names, owners, controllers, parameters and values of two groups.
 *
 * @param cgroup_a
 * @param cgroup_b
 *
 * @retval 0  if the groups are the same.
 * @retval #ECGROUPNOTEQUAL if the groups are not the same.
 * @retval #ECGCONTROLLERNOTEQUAL if the only difference are controllers,
 * 	parameters or their values.
 */
int cgroup_compare_cgroup(struct cgroup *cgroup_a, struct cgroup *cgroup_b);


/**
 * Compare names, parameters and values of two controllers.
 *
 * @param cgca
 * @param cgcb
 *
 * @retval 0  if the controllers are the same.
 * @retval #ECGCONTROLLERNOTEQUAL if the controllers are not equal.
 */
int cgroup_compare_controllers(struct cgroup_controller *cgca,
					struct cgroup_controller *cgcb);

/**
 * Set owner of the group control files and the @c tasks file. This function
 * modifies only @c libcgroup internal @c cgroup structure, use
 * cgroup_create_cgroup() afterwards to create the group with given owners.
 *
 * @param cgroup
 * @param tasks_uid UID of the owner of group's @c tasks file.
 * @param tasks_gid GID of the owner of group's @c tasks file.
 * @param control_uid UID of the owner of group's control files (i.e.
 * 	parameters).
 * @param control_gid GID of the owner of group's control files (i.e.
 * 	parameters).
 */
int cgroup_set_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 @c tasks file and control files.
 * The data is read from @c libcgroup internal @c cgroup structure, use
 * cgroup_set_uid_gid() or cgroup_get_cgroup() to fill it.
 */
int cgroup_get_uid_gid(struct cgroup *cgroup, uid_t *tasks_uid,
		gid_t *tasks_gid, uid_t *control_uid, gid_t *control_gid);

/**
 * @}
 * @name Group parameters
 * These are functions can read or modify parameter of a group.
 * @note All these functions read/write parameters to @c 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.
 * @{
 */

/**
 * Add parameter and its value to internal @c libcgroup structures.
 * Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 *
 */
int cgroup_add_value_string(struct cgroup_controller *controller,
				const char *name, const char *value);
/**
 * Add parameter and its value to internal @c 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.
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 *
 */
int cgroup_add_value_int64(struct cgroup_controller *controller,
				const char *name, int64_t value);
/**
 * Add parameter and its value to internal @c libcgroup structures.
 * Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 *
 */
int cgroup_add_value_uint64(struct cgroup_controller *controller,
				const char *name, u_int64_t value);
/**
 * Add parameter and its value to internal @c libcgroup structures.
 * Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 *
 */
int cgroup_add_value_bool(struct cgroup_controller *controller,
				const char *name, bool value);

/**
 * Read a parameter value from @c libcgroup internal structures.
 * Use @c 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 @c stats parameter, which can be longer
 * than libcgroup's internal buffers.
 * @todo rephrase, it's too vague... How big is the buffer actually?
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 */
int cgroup_get_value_string(struct cgroup_controller *controller,
					const char *name, char **value);
/**
 * Read a parameter value from @c libcgroup internal structures.
 * Use @c cgroup_get_cgroup() to fill these structures with data from kernel.
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 */
int cgroup_get_value_int64(struct cgroup_controller *controller,
					const char *name, int64_t *value);
/**
 * Read a parameter value from @c libcgroup internal structures.
 * Use @c cgroup_get_cgroup() to fill these structures with data from kernel.
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 */
int cgroup_get_value_uint64(struct cgroup_controller *controller,
					const char *name, u_int64_t *value);
/**
 * Read a parameter value from @c libcgroup internal structures.
 * Use @c cgroup_get_cgroup() to fill these structures with data from kernel.
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 */
int cgroup_get_value_bool(struct cgroup_controller *controller,
						const char *name, bool *value);

/**
 * Set a parameter value in @c libcgroup internal structures.
 * Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 */
int cgroup_set_value_string(struct cgroup_controller *controller,
					const char *name, const char *value);
/**
 * Set a parameter value in @c 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.
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 */
int cgroup_set_value_int64(struct cgroup_controller *controller,
					const char *name, int64_t value);
/**
 * Set a parameter value in @c libcgroup internal structures.
 * Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 */
int cgroup_set_value_uint64(struct cgroup_controller *controller,
					const char *name, u_int64_t value);
/**
 * Set a parameter value in @c libcgroup internal structures.
 * Use cgroup_modify_cgroup() or cgroup_create_cgroup() to write it to kernel.
 *
 * @param controller
 * @param name Name of the parameter.
 * @param value
 */
int cgroup_set_value_bool(struct cgroup_controller *controller,
						const char *name, bool value);
/**
 * Return the number of variables for the specified controller in @c 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.
 *
 * @param controller
 * @return Count of the parameters or -1 on error.
 */
int cgroup_get_value_name_count(struct cgroup_controller *controller);

/**
 * 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 @c libcgroup structure,
 * do not free it.
 *
 * @param controller
 * @param index Index of the parameter.
 * @return Name of the parameter.
 */
char *cgroup_get_value_name(struct cgroup_controller *controller, int index);

/**
 * Get the list of process in a cgroup. This list is guaranteed to
 * be sorted. It is not necessary that it is unique.
 * @param name The name of the cgroup
 * @param controller The name of the controller
 * @param pids The list of pids. Should be uninitialized when passed
 * to the API. Should be freed by the caller using free.
 * @param size The size of the pids array returned by the API.
 */
int cgroup_get_procs(char *name, char *controller, pid_t **pids, int *size);

/**
 * Change permission of files and directories of given group
 * @param cgroup The cgroup which permissions should be changed
 * @param dir_mode The permission mode of group directory
 * @param dirm_change Denotes whether the directory change should be done
 * @param file_mode The permission mode of group files
 * @param filem_change Denotes whether the directory change should be done
 */
int cg_chmod_recursive(struct cgroup *cgroup, mode_t dir_mode,
	int dirm_change, mode_t file_mode, int filem_change);

/**
 * @}
 * @}
 */


__END_DECLS

#endif /* _LIBCGROUP_GROUPS_H */