From: Ivan Gyurdiev <ivg2@cornell.edu>
To: SELinux List <SELinux@tycho.nsa.gov>
Cc: Stephen Smalley <sds@tycho.nsa.gov>
Subject: [SEMANAGE] Improve dbase spec/documentaiton
Date: Tue, 03 Jan 2006 07:05:37 -0500 [thread overview]
Message-ID: <43BA6891.8090303@cornell.edu> (raw)
[-- Attachment #1: Type: text/plain, Size: 184 bytes --]
... in order to prevent bugs like the one I just fixed in the previous
patch.
Not sure whether there are also ways to enforce this via gcc.. const
specifiers and things like that.
[-- Attachment #2: libsemanage16.database_doc.diff --]
[-- Type: text/x-patch, Size: 3966 bytes --]
diff -Naurp --exclude-from excludes old/libsemanage/src/database.h new/libsemanage/src/database.h
--- old/libsemanage/src/database.h 2005-12-23 01:51:54.000000000 -0500
+++ new/libsemanage/src/database.h 2006-01-03 06:59:35.000000000 -0500
@@ -61,9 +61,15 @@ typedef struct dbase_table {
/* --------------- Database Functionality ----------- */
+ /* Note: In all the functions below, the key is property
+ * of the caller, and will not be modified by the database. */
+
/* Add the specified record to
* the database if it is not present,
- * or fail if it already exists */
+ * or fail if it already exists
+ *
+ * Note: the <data> record becomes property of the
+ * database, and may not be further modified */
int (*add) (
struct semanage_handle* handle,
dbase_t* dbase,
@@ -72,7 +78,10 @@ typedef struct dbase_table {
/* Add the specified record to the
* database if it not present.
- * If it's present, replace it */
+ * If it's present, replace it
+ *
+ * Note: The <data> record becomes property of the
+ * database, and may not be further modified */
int (*modify) (
struct semanage_handle* handle,
dbase_t* dbase,
@@ -80,7 +89,10 @@ typedef struct dbase_table {
record_t* data);
/* Modify the specified record in the database
- * if it is present. Fail if it does not yet exist */
+ * if it is present. Fail if it does not yet exist
+ *
+ * Note: The <data> record becomes property of the
+ * database, and may not be further modified*/
int (*set) (
struct semanage_handle* handle,
dbase_t* dbase,
@@ -93,7 +105,12 @@ typedef struct dbase_table {
dbase_t* dbase,
record_key_t* key);
- /* Retrieve a record */
+ /* Retrieve a record
+ *
+ * Note: the resultant record
+ * becomes property of the caller, and
+ * must be freed accordingly */
+
int (*query) (
struct semanage_handle* handle,
dbase_t* dbase,
@@ -117,7 +134,18 @@ typedef struct dbase_table {
* the records of this database. The handler
* can signal a successful exit by returning 1,
* an error exit by returning -1, and continue by
- * returning 0 */
+ * returning 0
+ *
+ * Note: The record passed into the iterate handler
+ * may or may not persist after the handler invocation,
+ * and writing to it has unspecified behavior. It *must*
+ * be cloned if modified, or preserved.
+ *
+ * Note: The iterate handler may not invoke any other
+ * semanage read functions outside a transaction. It is only
+ * reentrant while in transaction. The iterate handler may
+ * not modify the underlying database.
+ */
int (*iterate) (
struct semanage_handle* handle,
dbase_t* dbase,
@@ -126,7 +154,11 @@ typedef struct dbase_table {
void* varg),
void* fn_arg);
- /* Construct a list of all records in this database */
+ /* Construct a list of all records in this database
+ *
+ * Note: The list returned becomes property of the caller,
+ * and must be freed accordingly.
+ */
int (*list) (
struct semanage_handle* handle,
dbase_t* dbase,
@@ -136,9 +168,8 @@ typedef struct dbase_table {
/* ---------- Cache/Transaction Management ---------- */
/* Cache the database (if supported).
- * Invoke this function before looking at
- * any data, since the database may require
- * cached content */
+ * This function must be invoked before using
+ * any of the database functions above */
int (*cache) (
struct semanage_handle* handle,
dbase_t* dbase);
@@ -148,7 +179,7 @@ typedef struct dbase_table {
void (*drop_cache) (
dbase_t* dbase);
- /* Checks if there are pending changes */
+ /* Checks if there are any changes not written to the backend */
int (*is_modified) (
dbase_t* dbase);
@@ -159,7 +190,6 @@ typedef struct dbase_table {
/* ------------- Polymorphism ----------------------- */
-
/* Retrieves the record table for this database,
* which specifies how to perform basic operations
* on each record. */
reply other threads:[~2006-01-03 12:05 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=43BA6891.8090303@cornell.edu \
--to=ivg2@cornell.edu \
--cc=SELinux@tycho.nsa.gov \
--cc=sds@tycho.nsa.gov \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.