.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Author: Eamon Walsh (ewalsh@epoch.ncsc.mil) 2004
.TH "avc_context_to_sid" "3" "27 May 2004" "" "SE Linux API documentation"
.SH "NAME"
avc_context_to_sid, avc_sid_to_context, sidput, sidget \- obtain and manipulate security ID's.
.SH "SYNOPSIS"
.B #include <selinux/selinux.h>
.br
.B #include <selinux/avc.h>
.sp
.BI "int avc_context_to_sid(security_context_t " ctx ", security_id_t *" sid ");"
.sp
.BI "int avc_sid_to_context(security_id_t " sid ", security_context_t *" ctx ");"
.sp
.BI "int sidget(security_id_t " sid ");"
.sp
.BI "int sidput(security_id_t " sid ");"
.SH "DESCRIPTION"
Security ID's (SID's) are reference-counted, opaque representations of security contexts.  

.B avc_context_to_sid
returns a SID for the given
.I context
in the memory referenced by
.IR sid ,
incrementing its reference count by 1.

.B avc_sid_to_context
returns a copy of the context represented by
.I sid
in the memory referenced by
.IR ctx .
The user must free the copy with
.BR freecon (3).

.B sidget
increments the reference count of
.I sid 
by 1.

.B sidput
decrements the reference count of
.I sid
by 1.  If the count ever reaches zero, the SID becomes
invalid and must not be used any further.

.SH "RETURN VALUE"
.B sidget
and
.B sidput
return the new reference count.  A return value of zero indicates
an invalid SID.

.B avc_context_to_sid
and
.B avc_sid_to_context
return zero on success.  On error, \-1 is returned and
.I errno
is set appropriately.

.SH "ERRORS"
.TP
.B EINVAL
The provided
.I sid
has a zero reference count and is invalid.
.TP
.B ENOMEM
An attempt to allocate memory failed.

.SH "NOTES"
The expected usage pattern for these functions is that
.B avc_context_to_sid
will be called once to obtain a SID for a newly created object,
.B sidget
will be called on a SID when its object is duplicated, and
.B sidput
will be called on a SID when its object is destroyed.  Proper reference counting is necessary to ensure that SID's and associated cache entries are reclaimed from memory when no longer needed.

.SH "AUTHOR"
Eamon Walsh <ewalsh@epoch.ncsc.mil>

.SH "SEE ALSO"
.BR avc_init (3),
.BR avc_has_perm (3),
.BR avc_cache_stats (3),
.BR avc_add_callback (3),
.BR getcon (3),
.BR freecon (3)