.\" 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)