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
- type 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 retrieve 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 dependency.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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. After
// initialization, access to its mutable fields requires the mechanism's lock.
Object() *Object
// Destroy destroys the mechanism.
//
// Preconditions: The mechanism's mutex must be held.
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.
checklocks cannot name the concrete mechanism's mutex through this interface. Concrete Lock/Unlock effects and Destroy preconditions do not propagate through interface calls.
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 assigned during registration, then immutable.
ID ID
// Key is a user-provided identifier for the IPC object. For shared-memory
// segments, IPC_RMID changes it to IPC_PRIVATE.
Key Key
// CreatorUID is the UID of user who created the IPC object. Immutable.
CreatorUID auth.KUID
// CreatorGID is the GID of user who created the IPC object. Immutable.
CreatorGID auth.KGID
// OwnerUID is the UID of the current owner of the IPC object.
OwnerUID auth.KUID
// OwnerGID is the GID of the current owner of the IPC object.
OwnerGID auth.KGID
// Mode is the access permissions of the IPC object.
Mode linux.FileMode
}
Object represents an abstract IPC object with fields common to all IPC mechanisms.
After initialization, mutable fields are protected by the containing msgqueue.Queue.mu, semaphore.Set.mu, or shm.Shm.mu. Object has no pointer to that mechanism, so checklocks cannot resolve its mutex for accesses through an escaped *Object.
+stateify savable
func NewObject ¶
func NewObject(un *auth.UserNamespace, key Key, creator, owner *auth.Credentials, mode linux.FileMode) *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.
Preconditions: The containing mechanism's mutex must be held.
func (*Object) CheckPermissions ¶
func (o *Object) CheckPermissions(creds *auth.Credentials, req vfs.AccessTypes) bool
CheckPermissions verifies whether an IPC object is accessible using creds for access described by req. See ipc/util.c:ipcperms() in Linux.
Preconditions: The containing mechanism's mutex 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 contains fields common to all SysV IPC registries.
The containing msgqueue.Registry.mu, semaphore.Registry.mu, or shm.Registry.mu protects mutable fields after initialization. Registry has no pointer to its containing registry, so checklocks cannot resolve that mutex for accesses through an escaped *Registry.
+stateify savable
func NewRegistry ¶
func NewRegistry(userNS *auth.UserNamespace) *Registry
NewRegistry return a new, initialized ipc.Registry.
func (*Registry) DissociateID ¶
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 ¶
DissociateKey removes the association between a mechanism and its key from r.keysToIDs. Lookup by ID is unaffected, and the mechanism is not destroyed. 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) ForAllObjects ¶
ForAllObjects calls f synchronously for each registered mechanism while the caller holds the containing registry's mutex. No reference is transferred. The registry mutex does not protect mutable mechanism state; f must acquire the mechanism's mutex before accessing that state.
f must preserve the registry lock and not reenter operations that acquire it. checklocks cannot express this external-owner callback contract. Retaining a mechanism requires a separate lifetime guarantee.
func (*Registry) LastIDUsed ¶
LastIDUsed returns the last used ID.
func (*Registry) ObjectCount ¶
ObjectCount returns the number of registered objects.
Source Files