mirror of
https://github.com/drasko/codezero.git
synced 2026-01-13 03:13:15 +01:00
122 lines
3.6 KiB
Groff
122 lines
3.6 KiB
Groff
.TH L4_CAPABILITY_CONTROL 7 2009-11-07 "Codezero" "Codezero Programmer's Manual"
|
|
.SH NAME
|
|
.nf
|
|
.BR "l4_capability_control" " - Capability inspection and manipulation"
|
|
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <l4lib/arch/syscalls.h>
|
|
.B #include <l4lib/arch/syslib.h>
|
|
|
|
.BI "int l4_capability_control (unsigned int " "req" ", unsigned int " "flags",
|
|
.BI " l4id_t " "capid" ", l4id_t " "tid" ", void " "*buf" ");"
|
|
.SH DESCRIPTION
|
|
.BR l4_capability_control() " - "
|
|
enables a thread to read and manipulate the list of capabilities that it possesses. Capabilities may be shared, granted to other threads, or they may be replicated, destroyed, reduced in privileges or split into parts, effectively enabling a dynamically configurable resource management architecture. The thread calling this system call must possess relevant capabilities as any operation done by this call are also subject to capability checking.
|
|
.TP
|
|
.fi
|
|
.I req
|
|
denotes the type of request. See below for a full list.
|
|
.TP
|
|
.fi
|
|
.I flags
|
|
denotes additional flags for the given request. See below for a list of flags.
|
|
.TP
|
|
.fi
|
|
|
|
.I buf
|
|
almost always contains a capability structure that describes the request with regard to given
|
|
.IR "req"
|
|
and
|
|
.IR "flags."
|
|
.TP
|
|
.TP
|
|
.I capid
|
|
Currently unused
|
|
.TP
|
|
.I tid
|
|
Unused
|
|
.TP
|
|
|
|
.BR CAP_CONTROL_NCAPS
|
|
Get capability count. This is the sum of thread-private capabilities, address space capabilities and container capabilities.
|
|
.TP
|
|
.BR CAP_CONTROL_READ
|
|
Returns an array of
|
|
.BI "struct " "capability"
|
|
structures in
|
|
.I buf.
|
|
The number of capabilities in the array should be first obtained by the
|
|
.B CAP_CONTROL_NCAPS
|
|
request.
|
|
.TP
|
|
.BR CAP_CONTROL_SHARE
|
|
Shares a single capability or list of capabilities with a collection entity such as an address space or a container. If
|
|
.B CAP_SHARE_SINGLE
|
|
is specified in
|
|
.IR "flag",
|
|
only the given capability is shared with that entity, and if
|
|
.B CAP_SHARE_ALL
|
|
is specified in
|
|
.IR "flag",
|
|
all capabilities in the given list are shared with that entity.
|
|
|
|
The sharing must be made with a collection entity that contains the original entity. For example, a capability possessed by a thread may be shared with the thread's address space, or the thread's container. However it is not possible to share a capability in one container with another container. See
|
|
.B CAP_CONTROL_REPLICATE
|
|
and
|
|
.B CAP_CONTROL_GRANT
|
|
on other methods of transferring a possessed capability to another entity.
|
|
|
|
.TP
|
|
.BR CAP_CONTROL_GRANT
|
|
Grant the capabilities in the buffer
|
|
.IR "buf",
|
|
if
|
|
.I flag
|
|
has
|
|
.BR "CAP_GRANT_SINGLE",
|
|
if
|
|
.B CAP_GRANT_ALL
|
|
is provided with flag all capabilities are granted, if
|
|
.B CAP_GRANT_IMMUTABLE
|
|
is specified in flags then all(or one) capabilities are made immutable.
|
|
.TP
|
|
.BR CAP_CONTROL_REPLICATE
|
|
Replicates an existing capability. This is for expanding capabilities to managed children.
|
|
.TP
|
|
.B CAP_CONTROL_SPLIT
|
|
Capabilities are split by diff'ing resources possessed between capabilities.
|
|
.I flags
|
|
may be one of
|
|
.B CAP_SPLIT_SIZE
|
|
,
|
|
.B CAP_SPLIT_ACCESS
|
|
or
|
|
.B CAP_SPLIT_RANGE.
|
|
|
|
.TP
|
|
.BR CAP_CONTROL_DEDUCE
|
|
Deduction can be by access permissions, start, end, size fields, or the target resource type. Inter-container deduction is not allowed. Target resource deduction denotes reducing the applicable space of the target, e.g. from a container to a space in that container.
|
|
.TP
|
|
.BR CAP_CONTROL_DESTROY
|
|
Destroys a capability specified in
|
|
.IR "flag".
|
|
|
|
|
|
.SH RETURN VALUE
|
|
.IR "l4_capability_control"()
|
|
Returns 0 on success, and negative value on failure. See below for error codes.
|
|
|
|
.SH ERRORS
|
|
.TP
|
|
.B -EINVAL
|
|
when a capability struct is passed in
|
|
.IR "buf"
|
|
but with invalid fields.
|
|
.TP
|
|
.B -ENOCAP
|
|
when capabilities required don't exist or do not have sufficient privileges.
|
|
|
|
.SH SEE ALSO
|
|
.BR "capability"(7)
|