Differential D14196 Diff 38880 lib/libcasper/libcasper/libcasper.3

Changeset View

Standalone View

lib/libcasper/libcasper/libcasper.3

	Show All 21 Lines
	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)			.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd January 3, 2018			.Dd February 5, 2018
	.Dt LIBCASPER 3			.Dt LIBCASPER 3
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm cap_init ,			.Nm cap_init ,
	.Nm cap_wrap ,			.Nm cap_wrap ,
	.Nm cap_unwrap ,			.Nm cap_unwrap ,
	.Nm cap_sock ,			.Nm cap_sock ,
	.Nm cap_clone ,			.Nm cap_clone ,
	.Nm cap_close ,			.Nm cap_close ,
	.Nm cap_limit_get ,			.Nm cap_limit_get ,
	.Nm cap_limit_set ,			.Nm cap_limit_set ,
	.Nm cap_send_nvlist ,			.Nm cap_send_nvlist ,
	.Nm cap_recv_nvlist ,			.Nm cap_recv_nvlist ,
	.Nm cap_xfer_nvlist ,			.Nm cap_xfer_nvlist ,
	.Nm cap_service_open			.Nm cap_service_open
	.Nd "library for handling application capabilities"			.Nd "library for handling application capabilities"
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libcasper			.Lb libcasper
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In sys/nv.h			.In sys/nv.h
	.In libcasper.h			.In libcasper.h
	.Ft "cap_channel_t *"			.Ft "cap_channel_t *"
	.Fn cap_init "void"			.Fn cap_init "void"
	.Ft "cap_channel_t *"			.Ft "cap_channel_t *"
	.Fn cap_wrap "int sock"			.Fn cap_wrap "int sock" "int flags"
	.Ft "int"			.Ft "int"
	.Fn cap_unwrap "cap_channel_t *chan"			.Fn cap_unwrap "cap_channel_t chan" "int flags"
	.Ft "int"			.Ft "int"
	.Fn cap_sock "const cap_channel_t *chan"			.Fn cap_sock "const cap_channel_t *chan"
	.Ft "cap_channel_t *"			.Ft "cap_channel_t *"
	.Fn cap_clone "const cap_channel_t *chan"			.Fn cap_clone "const cap_channel_t *chan"
	.Ft "void"			.Ft "void"
	.Fn cap_close "cap_channel_t *chan"			.Fn cap_close "cap_channel_t *chan"
	.Ft "int"			.Ft "int"
	.Fn cap_limit_get "const cap_channel_t chan" "nvlist_t *limitsp"			.Fn cap_limit_get "const cap_channel_t chan" "nvlist_t *limitsp"
	.Ft "int"			.Ft "int"
	.Fn cap_limit_set "const cap_channel_t chan" "nvlist_t limits"			.Fn cap_limit_set "const cap_channel_t chan" "nvlist_t limits"
	.Ft "int"			.Ft "int"
	.Fn cap_send_nvlist "const cap_channel_t chan" "const nvlist_t nvl"			.Fn cap_send_nvlist "const cap_channel_t chan" "const nvlist_t nvl"
	.Ft "nvlist_t *"			.Ft "nvlist_t *"
	.Fn cap_recv_nvlist "const cap_channel_t *chan" "int flags"			.Fn cap_recv_nvlist "const cap_channel_t *chan"
	.Ft "nvlist_t *"			.Ft "nvlist_t *"
	.Fn cap_xfer_nvlist "const cap_channel_t chan" "nvlist_t nvl" "int flags"			.Fn cap_xfer_nvlist "const cap_channel_t chan" "nvlist_t nvl"
	.Ft "cap_channel_t *"			.Ft "cap_channel_t *"
	.Fn cap_service_open "const cap_channel_t chan" "const char name"			.Fn cap_service_open "const cap_channel_t chan" "const char name"
	.Sh DESCRIPTION			.Sh DESCRIPTION
	The			The
	.Nm libcasper			.Nm libcasper
	library allows to manage application capabilities through the casper process.			library allows to manage application capabilities through the casper process.
	.Pp			.Pp
	The application capability (represented by the			The application capability (represented by the
	Show All 17 Lines
	based on the given socket.			based on the given socket.
	The function is used when capability is inherited through			The function is used when capability is inherited through
	.Xr execve 2			.Xr execve 2
	or send over			or send over
	.Xr unix 4			.Xr unix 4
	domain socket as a regular file descriptor and has to be represented as			domain socket as a regular file descriptor and has to be represented as
	.Vt cap_channel_t			.Vt cap_channel_t
	again.			again.
				The
				.Fa flags
				argument defines the channel behavior.
				The supported flags are:
				.Bl -ohang -offset indent
				.It CASPER_NO_UNIQ
				The communication between process and casper use no unique version of nvlist.
				bcrUnsubmitted Done Inline Actions s/betwen/between/ bcr: s/betwen/between/
				bcrUnsubmitted Done Inline Actions s/uniq/unique/ bcr: s/uniq/unique/
				bruefferUnsubmitted Done Inline Actions use -> uses brueffer: use -> uses
				bruefferUnsubmitted Not Done Inline Actions Also, ".Xr nvlist 9" ? brueffer: Also, ".Xr nvlist 9" ?
				oshogboAuthorUnsubmitted Not Done Inline Actions We already are using the nvlist in this man doc and there is no reference to nvlist 9, do you thing we should do it here or in all places? oshogbo: We already are using the nvlist in this man doc and there is no reference to nvlist 9, do you…
				bruefferUnsubmitted Not Done Inline Actions I usually go for all places. brueffer: I usually go for all places.
				jillesUnsubmitted Not Done Inline Actions Does this correspond to `NV_FLAG_NO_UNIQUE` (names in nvlist need not be unique)? jilles: Does this correspond to `NV_FLAG_NO_UNIQUE` (names in nvlist need not be unique)?
				oshogboAuthorUnsubmitted Not Done Inline Actions Yes it is. oshogbo: Yes it is.
				.El
	.Pp			.Pp
	The			The
	.Fn cap_unwrap			.Fn cap_unwrap
	function is the opposite of the			function is the opposite of the
	.Fn cap_wrap			.Fn cap_wrap
	function.			function.
	It frees the			It frees the
	.Vt cap_channel_t			.Vt cap_channel_t
	▲ Show 20 Lines • Show All 43 Lines • ▼ Show 20 Lines
	.Fn cap_send_nvlist			.Fn cap_send_nvlist
	function sends the given nvlist over the given capability.			function sends the given nvlist over the given capability.
	This is low level interface to communicate with casper services.			This is low level interface to communicate with casper services.
	Most services should provide higher level API.			Most services should provide higher level API.
	.Pp			.Pp
	The			The
	.Fn cap_recv_nvlist			.Fn cap_recv_nvlist
	function receives the given nvlist over the given capability.			function receives the given nvlist over the given capability.
	The
	.Fa flags
	argument defines what type the top nvlist is expected to be.
	If the nvlist flags do not match the flags passed to
	.Fn cap_recv_nvlist ,
	the nvlist will not be returned.
	.Pp			.Pp
	The			The
	.Fn cap_xfer_nvlist			.Fn cap_xfer_nvlist
	function sends the given nvlist, destroys it and receives new nvlist in			function sends the given nvlist, destroys it and receives new nvlist in
	response over the given capability.			response over the given capability.
	The
	.Fa flags
	argument defines what type the top nvlist is expected to be.
	If the nvlist flags do not match the flags passed to
	.Fn cap_xfer_nvlist ,
	the nvlist will not be returned.
	It does not matter if the function succeeds or fails, the nvlist given			It does not matter if the function succeeds or fails, the nvlist given
	for sending will always be destroyed once the function returns.			for sending will always be destroyed once the function returns.
	.Pp			.Pp
	The			The
	.Fn cap_service_open			.Fn cap_service_open
	function opens casper service of the given name through casper capability			function opens casper service of the given name through casper capability
	obtained via the			obtained via the
	.Fn cap_init			.Fn cap_init
	▲ Show 20 Lines • Show All 129 Lines • Show Last 20 Lines