cgroup

package module
v0.0.0-...-d3db5c0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 17, 2017 License: BSD-3-Clause Imports: 5 Imported by: 1

README

go-cgroup

Bindings to the libcgroup library

Notice

these bindings are incomplete

Installing

go get github.com/vbatts/go-cgroup

on debian, you'll need packages: golang, libcgroup-dev on fedora, you'll need packages: golang, libcgroup-devel

Sample

package main

import "github.com/vbatts/go-cgroup"
import "fmt"

func main() {
  cgroup.Init()

  fmt.Println(cgroup.GetSubSysMountPoint("cpu"))

  ctls, err := cgroup.GetAllControllers()
  if err != nil {
    fmt.Println(err)
    return
  }
  for i := range ctls {
    fmt.Println(ctls[i])
  }

}

Contributing

Fork and Pull Request please!

Documentation

Index

Constants

View Source 
const (
	// NoPerms is uninitialized file/directory permissions used for task/control files.
	NoPerms = C.NO_PERMS

	// NoUIDGID is uninitialized UID/GID used for task/control files.
	NoUIDGID = C.NO_UID_GID
)
View Source 
const (
	// DeleteIgnoreMigration ignore errors caused by migration of tasks to parent group.
	DeleteIgnoreMigration = DeleteFlag(C.CGFLAG_DELETE_IGNORE_MIGRATION)

	// DeleteRecursive recursively delete all child groups.
	DeleteRecursive = DeleteFlag(C.CGFLAG_DELETE_RECURSIVE)

	// DeleteEmptyOnly deletes the cgroup only if it is empty, i.e. it has no
	// subgroups and no processes inside. This flag cannot be used with
	// DeleteRecursive
	DeleteEmptyOnly = DeleteFlag(C.CGFLAG_DELETE_EMPTY_ONLY)
)
View Source 
const (
	FileTypeFile  = FileType(C.CGROUP_FILE_TYPE_FILE)
	FileTypeDir   = FileType(C.CGROUP_FILE_TYPE_DIR)
	FileTypeOther = FileType(C.CGROUP_FILE_TYPE_OTHER)
)

Variables

View Source 
var (
	ErrEOF                = errors.New(C.GoString(C.cgroup_strerror(C.ECGEOF)))
	ErrOTHER              = errors.New(C.GoString(C.cgroup_strerror(C.ECGOTHER)))
	ErrGroupNotEqual      = errors.New(C.GoString(C.cgroup_strerror(C.ECGROUPNOTEQUAL)))
	ErrControllerNotEqual = errors.New(C.GoString(C.cgroup_strerror(C.ECGCONTROLLERNOTEQUAL)))
)

Various errors

Functions

func CompareCgroup 

func CompareCgroup(a, b Cgroup) error

CompareCgroup compares names, owners, controllers, parameters and values of two groups.

Return value of:

  • nil - a and b are equal
  • ErrGroupNotEqual - groups are not equal
  • ErrControllerNotEqual - controllers are not equal

func CompareControllers 

func CompareControllers(a, b Controller) error

CompareControllers compares names, parameters and values of two controllers.

Return value of:

  • nil - a and b are equal
  • ErrControllerNotEqual - controllers are not equal

func CopyCgroup 

func CopyCgroup(src, dest Cgroup) error

CopyCgroup copies all controllers, parameters and their values. All existing controllers in the source group are discarded.

func GetSubSysMountPoint 

func GetSubSysMountPoint(controller string) (string, error)

func Init 

func Init() error

Init initializes libcgroup. Information about mounted hierarchies are examined and cached internally (just what's mounted where, not the groups themselves).

func LastError 

func LastError() error

LastError returns last errno, which caused ErrOTHER error.

func LoadConfig 

func LoadConfig(filename string) error

LoadConfig file and mount and create control groups described there. See cgconfig.conf(5) man page for format of the file.

func SetDefault 

func SetDefault(cg Cgroup) error

SetDefault permissions of groups created by subsequent cgroup_config_load_config() calls. If a config file contains a 'default {}' section, the default permissions from the config file is then used.

Use cgroup_new_cgroup() to create a dummy group and cgroup_set_uid_gid() and cgroup_set_permissions() to set its permissions. Use NoUIDGID instead of GID/UID and NoPerms instead of file/directory permissions to let kernel decide the default permissions where you don't want specific user and/or permissions. Kernel then uses current user/group and permissions from umask then.

New default permissions from this group are copied to libcgroup internal structures.

func Unload 

func Unload() error

Unload deletes all control groups and unmount all hierarchies.

func UnloadFromConfig 

func UnloadFromConfig(filename string, flags DeleteFlag) error

UnloadFromConfig deletes all cgroups and unmount all mount points defined in specified config file.

The groups are either removed recursively or only the empty ones, based on given flags. Mount point are always umounted only if they are empty, regardless of any flags.

The groups are sorted before they are removed, so the removal of empty ones actually works (i.e. subgroups are removed first).

Types

type Cgroup 

type Cgroup struct {
	// contains filtered or unexported fields
}

Cgroup is the structure describing one or more control groups. The structure is opaque to applications.

func NewCgroup 

func NewCgroup(name string) Cgroup

NewCgroup allocates a new cgroup structure. This function itself does not create new control group in kernel, only new <tt>struct cgroup</tt> inside libcgroup! The caller would still need to Create() or similar to create this group in the kernel.

@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.

func (*Cgroup) AddController 

func (cg *Cgroup) AddController(name string) *Controller

AddController attaches a new controller to cgroup. This function just modifies internal libcgroup structure, not the kernel control group.

func (Cgroup) Create 

func (cg Cgroup) Create() error

Create a control group in kernel. The group is created in all hierarchies, which cover controllers added by Cgroup.AddController().

TODO correct docs for golang implementation

All parameters set by cgroup_add_value_* functions are written. The created groups has owner which was set by cgroup_set_uid_gid() and permissions set by cgroup_set_permissions. 

foo = cgroup.NewCgroup("foo)
foo.Create()

func (Cgroup) CreateFromParent 

func (cg Cgroup) CreateFromParent() error

CreateFromParent creates 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. 

foo = cgroup.NewCgroup("foo)
foo.CreateFromParent()

func (Cgroup) CreateFromParentIgnoreOwnership 

func (cg Cgroup) CreateFromParentIgnoreOwnership() error

CreateFromParentIgnoreOwnership is the same as CreateFromParent(), but all errors are ignored when setting owner of the group and/or its tasks file.

func (Cgroup) CreateIgnoreOwnership 

func (cg Cgroup) CreateIgnoreOwnership() error

CreateIgnoreOwnership is the same as Create(), but all errors are ignored when setting owner of the group and/or its tasks file.

func (Cgroup) Delete 

func (cg Cgroup) Delete() error

Delete removes a control group from kernel. The group is removed from all hierarchies, which cover controllers added by Cgroup.AddController() or GetCgroup(). 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.

TODO correct docs for golang implementation

func (Cgroup) DeleteExt 

func (cg Cgroup) DeleteExt(flags DeleteFlag) error

DeleteExt removes a control group from kernel.

All tasks are automatically moved to parent group. If DeleteIgnoreMigration flag is used, the errors that occurred during the task movement are ignored.

DeleteRecursive 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.

func (Cgroup) DeleteIgnoreMigration 

func (cg Cgroup) DeleteIgnoreMigration() error

DeleteIgnoreMigration is the same as Delete(), but ignores errors when migrating.

func (Cgroup) Get 

func (cg Cgroup) Get() error

Get reads 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. 

root := cgroup.NewCgroup("/")
err := root.Get()
...

func (Cgroup) GetController 

func (cg Cgroup) GetController(name string) *Controller

GetController returns appropriate controller from given group. The controller must be added before using AddController() or loaded from kernel using GetCgroup().

func (Cgroup) GetUIDGID 

func (cg Cgroup) GetUIDGID() (tasksUID UID, tasksGID GID, controlUID UID, controlGID GID, err error)

GetUIDGID returns owners of the group's @c tasks file and control files. The data is read from libcgroup internal cgroup structure, use Cgroup.SetUIDGID() or Cgroup.Get() to fill it.

func (Cgroup) Modify 

func (cg Cgroup) Modify() error

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.

TODO correct docs for golang implementation

func (Cgroup) SetPermissions 

func (cg Cgroup) SetPermissions(controlDirPerm, controlFilePerm, taskFilePerm Mode)

SetPermissions stores given file permissions of the group's control and tasks files into the cgroup data structure. Use NoPerms if permissions shouldn't be changed or a value which applicable to chmod(2). Please note that the given permissions are masked with the file owner's permissions. For example if a control file has permissions 640 and controlFilePerm is 471 the result will be 460.

controlDirPerm Directory permission for the group. controlFilePerm File permission for the control files. taskFilePerm File permissions for task file. 

g := cgroup.NewCgroup("foo")
g.SetPermissions(cgroup.Mode(0777), cgroup.Mode(0777), cgroup.Mode(0777))

func (Cgroup) SetUIDGID 

func (cg Cgroup) SetUIDGID(tasksUID UID, tasksGID GID,
	controlUID UID, controlGID GID) error

SetUIDGID sets owner of the group control files and the @c tasks file. This function modifies only libcgroup internal cgroup structure, use Cgroup.Create() afterwards to create the group with given owners.

@param cgroup @param tasksUID UID of the owner of group's @c tasks file. @param tasksGID GID of the owner of group's @c tasks file. @param controlUID UID of the owner of group's control files (i.e. parameters). @param controlGID GID of the owner of group's control files (i.e. parameters).

type Controller 

type Controller struct {
	// contains filtered or unexported fields
}

Controller is the structure describing a controller attached to one struct @c cgroup, including parameters of the group and their values. The structure is opaque to applications.

func (Controller) AddValueBool 

func (c Controller) AddValueBool(name string, value bool) error

func (Controller) AddValueInt64 

func (c Controller) AddValueInt64(name string, value int64) error

func (Controller) AddValueString 

func (c Controller) AddValueString(name, value string) error

AddValueString adds parameter and its value to internal libcgroup structures. Use Cgroup.Modify() or Cgroup.Create() to write it to kernel.

Name of the parameter and its value

func (Controller) GetValueBool 

func (c Controller) GetValueBool(name string) (value bool, err error)

func (Controller) GetValueInt64 

func (c Controller) GetValueInt64(name string) (value int64, err error)

func (Controller) GetValueString 

func (c Controller) GetValueString(name string) (value string, err error)

GetValueString fetches the values from the controller. Use Cgroup.Get() to get the names available to fetch values from the kernel.

func (Controller) SetValueBool 

func (c Controller) SetValueBool(name string, value bool) error

func (Controller) SetValueInt64 

func (c Controller) SetValueInt64(name string, value int64) error

func (Controller) SetValueString 

func (c Controller) SetValueString(name, value string) error

SetValueString sets a parameter value in @c libcgroup internal structures. Use Cgroup.Modify() or Cgroup.Create() to write it to kernel.

func (Controller) SetValueUint64 

func (c Controller) SetValueUint64(name string, value uint64) error

type ControllerData 

type ControllerData struct {
	// contains filtered or unexported fields
}

ControllerData is the information model for controllers available

func GetAllControllers 

func GetAllControllers() (controllers []ControllerData, err error)

func (ControllerData) Enabled 

func (cd ControllerData) Enabled() int

Enabled indicates whether or not this controller is enabled

func (ControllerData) Hierarchy 

func (cd ControllerData) Hierarchy() int

Hierarchy is the identification of the controller. Controllers with the same hierarchy ID are mounted together as one hierarchy. Controllers with ID 0 are not currently mounted anywhere.

func (ControllerData) Name 

func (cd ControllerData) Name() string

Name of the this controller

func (ControllerData) NumCgroups 

func (cd ControllerData) NumCgroups() int

NumCgroups is the number of cgroups

type DeleteFlag 

type DeleteFlag int

type FileInfo 

type FileInfo struct {
	// contains filtered or unexported fields
}

FileInfo is the Information about found cgroup directory (= a control group).

func (FileInfo) Depth 

func (fi FileInfo) Depth() int8

Depth of this cgroup

func (FileInfo) FileType 

func (fi FileInfo) FileType() FileType

FileType of this cgroup's

func (FileInfo) FullPath 

func (fi FileInfo) FullPath() string

FullPath to this cgroup

func (FileInfo) Parent 

func (fi FileInfo) Parent() string

Parent of this cgroup

func (FileInfo) Path 

func (fi FileInfo) Path() string

Path to this cgroup

type FileType 

type FileType int

type GID 

type GID C.gid_t

GID is the group ID type. 

cgroup.GID(0)

type Mode 

type Mode C.mode_t

Mode is the file permissions. Like used in SetPermissions()

type UID 

type UID C.uid_t

UID is the user ID type. 

cgroup.UID(0)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.