ipc

Documentation

Overview

Package ipc defines functionality and utilities common to sysvipc mechanisms.

Lock ordering: shm/semaphore/msgqueue.Registry.mu -> Mechanism

Index

• Constants
• type ID
• type Key
• type Mechanism
• type Object
  • func NewObject(un *auth.UserNamespace, key Key, creator, owner fs.FileOwner, ...) *Object
  • func (o *Object) CheckOwnership(creds *auth.Credentials) bool
  • func (o *Object) CheckPermissions(creds *auth.Credentials, req fs.PermMask) bool
  • func (o *Object) Set(ctx context.Context, perm *linux.IPCPerm) error
• type Registry
  • func NewRegistry(userNS *auth.UserNamespace) *Registry
  • func (r *Registry) DissociateID(id ID)
  • func (r *Registry) DissociateKey(key Key)
  • func (r *Registry) Find(ctx context.Context, key Key, mode linux.FileMode, create, exclusive bool) (Mechanism, error)
  • func (r *Registry) FindByID(id ID) Mechanism
  • func (r *Registry) ForAllObjects(f func(o Mechanism))
  • func (r *Registry) LastIDUsed() ID
  • func (r *Registry) ObjectCount() int
  • func (r *Registry) Register(m Mechanism) error
  • func (r *Registry) Remove(id ID, creds *auth.Credentials) error

Constants

const CtxIPCNamespace contextID = iota

CtxIPCNamespace is the context.Value key used to retreive an IPC namespace. We define it here because it's needed in several packages, and is not possible to use otherwise without causing a circular depenedency.

Types

type ID

type ID int32

ID is a kernel identifier for IPC objects.

type Key

type Key int32

Key is a user-provided identifier for IPC objects.

type Mechanism

type Mechanism interface {
	// Lock behaves the same as Mutex.Lock on the mechanism.
	Lock()

	// Unlock behaves the same as Mutex.Unlock on the mechanism.
	Unlock()

	// Object returns a pointer to the mechanism's ipc.Object. Mechanism.Lock,
	// and Mechanism.Unlock should be used when the object is used.
	Object() *Object

	// Destroy destroys the mechanism.
	Destroy()
}

Mechanism represents a SysV mechanism that holds an IPC object. It can also be looked at as a container for an ipc.Object, which is by definition a fully functional SysV object.

type Object

type Object struct {
	// User namespace which owns the IPC namespace which owns the IPC object.
	// Immutable.
	UserNS *auth.UserNamespace

	// ID is a kernel identifier for the IPC object. Immutable.
	ID ID

	// Key is a user-provided identifier for the IPC object. Immutable.
	Key Key

	// Creator is the user who created the IPC object. Immutable.
	Creator fs.FileOwner

	// Owner is the current owner of the IPC object.
	Owner fs.FileOwner

	// Perms is the access permissions the IPC object.
	Perms fs.FilePermissions
}

Object represents an abstract IPC object with fields common to all IPC mechanisms.

+stateify savable

func NewObject

func NewObject(un *auth.UserNamespace, key Key, creator, owner fs.FileOwner, perms fs.FilePermissions) *Object

NewObject returns a new, initialized ipc.Object. The newly returned object doesn't have a valid ID. When the object is registered, the registry assigns it a new unique ID.

func (*Object) CheckOwnership

func (o *Object) CheckOwnership(creds *auth.Credentials) bool

CheckOwnership verifies whether an IPC object may be accessed using creds as an owner. See ipc/util.c:ipcctl_obtain_check() in Linux.

func (*Object) CheckPermissions

func (o *Object) CheckPermissions(creds *auth.Credentials, req fs.PermMask) bool

CheckPermissions verifies whether an IPC object is accessible using creds for access described by req. See ipc/util.c:ipcperms() in Linux.

func (*Object) Set

func (o *Object) Set(ctx context.Context, perm *linux.IPCPerm) error

Set modifies attributes for an IPC object. See *ctl(IPC_SET).

Precondition: Mechanism.mu must be held.

type Registry

type Registry struct {
	// UserNS owning the IPC namespace this registry belongs to. Immutable.
	UserNS *auth.UserNamespace
	// contains filtered or unexported fields
}

Registry is similar to Object, but for registries. It represent an abstract SysV IPC registry with fields common to all SysV registries. Registry is not thread-safe, and should be protected using a mutex.

+stateify savable

func NewRegistry

func NewRegistry(userNS *auth.UserNamespace) *Registry

NewRegistry return a new, initialized ipc.Registry.

func (*Registry) DissociateID

func (r *Registry) DissociateID(id ID)

DissociateID removes the association between a mechanism and its ID (deletes it from r.objects). An ID can't be removed unless the associated key is removed already, this is done to prevent the users from acquiring nil a Mechanism.

Precondition: must be preceded by a call to r.DissociateKey.

func (*Registry) DissociateKey

func (r *Registry) DissociateKey(key Key)

DissociateKey removes the association between a mechanism and its key (deletes it from r.keysToIDs), preventing it from being discovered by any new process, but not necessarily destroying it. If the given key doesn't exist, nothing is changed.

func (*Registry) Find

func (r *Registry) Find(ctx context.Context, key Key, mode linux.FileMode, create, exclusive bool) (Mechanism, error)

Find uses key to search for and return a SysV mechanism. Find returns an error if an object is found by shouldn't be, or if the user doesn't have permission to use the object. If no object is found, Find checks create flag, and returns an error only if it's false.

func (*Registry) FindByID

func (r *Registry) FindByID(id ID) Mechanism

FindByID returns the mechanism with the given ID, nil if non exists.

func (*Registry) ForAllObjects

func (r *Registry) ForAllObjects(f func(o Mechanism))

ForAllObjects executes a given function for all given objects.

func (*Registry) LastIDUsed

func (r *Registry) LastIDUsed() ID

LastIDUsed returns the last used ID.

func (*Registry) ObjectCount

func (r *Registry) ObjectCount() int

ObjectCount returns the number of registered objects.

func (*Registry) Register

func (r *Registry) Register(m Mechanism) error

Register adds the given object into Registry.Objects, and assigns it a new ID. It returns an error if all IDs are exhausted.

func (*Registry) Remove

func (r *Registry) Remove(id ID, creds *auth.Credentials) error

Remove removes the mechanism with the given id from the registry, and calls mechanism.Destroy to perform mechanism-specific removal.