From 09cd8160d97770533d3290aeafc466b5c6fe8939 Mon Sep 17 00:00:00 2001 From: Eamon Walsh Date: Wed, 2 Sep 2009 20:23:08 -0400 Subject: [PATCH] Documentation updates for the removal of recounted SID's. Signed-off-by: Eamon Walsh --- libselinux/man/man3/avc_compute_create.3 | 9 ++--- libselinux/man/man3/avc_context_to_sid.3 | 45 +++++------------------- libselinux/man/man3/avc_open.3 | 2 +- 3 files changed, 12 insertions(+), 44 deletions(-) diff --git a/libselinux/man/man3/avc_compute_create.3 b/libselinux/man/man3/avc_compute_create.3 index f102cc9b..52d09b54 100644 --- a/libselinux/man/man3/avc_compute_create.3 +++ b/libselinux/man/man3/avc_compute_create.3 @@ -31,8 +31,7 @@ but does not require converting from userspace SID's to contexts and back again. These functions return a SID for the computed context in the memory referenced by -.IR sid , -incrementing its reference count by 1. +.IR sid . .SH "RETURN VALUE" On success, zero is returned. On error, \-1 is returned and @@ -48,11 +47,7 @@ and/or the security contexts referenced by .I ssid and .I tsid -are not recognized by the currently loaded policy, or -.I tsid -or -.I ssid -has a zero reference count and is invalid. +are not recognized by the currently loaded policy. .TP .B ENOMEM diff --git a/libselinux/man/man3/avc_context_to_sid.3 b/libselinux/man/man3/avc_context_to_sid.3 index 41a486d8..1caf5ec5 100644 --- a/libselinux/man/man3/avc_context_to_sid.3 +++ b/libselinux/man/man3/avc_context_to_sid.3 @@ -3,7 +3,7 @@ .\" Author: Eamon Walsh (ewalsh@tycho.nsa.gov) 2004 .TH "avc_context_to_sid" "3" "27 May 2004" "" "SELinux API documentation" .SH "NAME" -avc_context_to_sid, avc_sid_to_context, sidput, sidget, avc_get_initial_sid \- obtain and manipulate SELinux security ID's. +avc_context_to_sid, avc_sid_to_context, avc_get_initial_sid \- obtain and manipulate SELinux security ID's. .SH "SYNOPSIS" .B #include @@ -13,21 +13,16 @@ avc_context_to_sid, avc_sid_to_context, sidput, sidget, avc_get_initial_sid \- o .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 ");" -.sp .BI "int avc_get_initial_sid(const char *" name ", security_id_t *" sid ");" .sp .SH "DESCRIPTION" -Security ID's (SID's) are reference-counted, opaque representations of security contexts. +Security ID's (SID's) are opaque representations of security contexts, managed by the userspace AVC. .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. +.IR sid . .B avc_sid_to_context returns a copy of the context represented by @@ -37,28 +32,11 @@ in the memory referenced by 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. - .B avc_get_initial_sid returns a SID for the kernel initial security identifier specified by -.I name +.IR name . .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 @@ -68,22 +46,17 @@ 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, +As of libselinux version 2.0.86, SID's are no longer reference counted. A SID will be valid from the time it is first obtained until the next call to +.BR avc_destroy (3). +The .B sidget -will be called on a SID when its object is duplicated, and +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. +functions, formerly used to adjust the reference count, are no-ops and are deprecated. .SH "AUTHOR" Eamon Walsh diff --git a/libselinux/man/man3/avc_open.3 b/libselinux/man/man3/avc_open.3 index 90190853..d1dab8fe 100644 --- a/libselinux/man/man3/avc_open.3 +++ b/libselinux/man/man3/avc_open.3 @@ -31,7 +31,7 @@ flushes the userspace AVC, causing it to forget any cached access decisions. Th below. .B avc_cleanup -forces the userspace AVC to search for and free all unused SID's and any access decision entries that refer to them. Normally, the userspace AVC lazily reclaims unused SID's. +attempts to free unused memory within the userspace AVC, but does not flush any cached access decisions. Under normal operation, calling this function should not be necessary. .SH "OPTIONS" The userspace AVC obeys callbacks set via