From 6c1d98eac06df7f033d8a69bb5be985067f96c9b Mon Sep 17 00:00:00 2001
From: Jeremy Allison <jra@samba.org>
Date: Thu, 12 Jan 2012 14:46:45 -0800
Subject: [PATCH] Add comments to all functions (to help me understand it
 better).

Autobuild-User: Jeremy Allison <jra@samba.org>
Autobuild-Date: Fri Jan 13 01:35:03 CET 2012 on sn-devel-104
---
 source3/locking/locking.c         |  5 +++++
 source3/locking/share_mode_lock.c | 27 +++++++++++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/source3/locking/locking.c b/source3/locking/locking.c
index 9199591d9e8..7063b54d9ca 100644
--- a/source3/locking/locking.c
+++ b/source3/locking/locking.c
@@ -448,6 +448,11 @@ char *share_mode_str(TALLOC_CTX *ctx, int num, const struct share_mode_entry *e)
 		 (unsigned int)e->name_hash);
 }
 
+/*******************************************************************
+ Fetch a share mode where we know one MUST exist. This call reference
+ counts it internally to allow for nested lock fetches.
+********************************************************************/
+
 struct share_mode_lock *get_share_mode_lock(TALLOC_CTX *mem_ctx,
 					    const struct file_id id)
 {
diff --git a/source3/locking/share_mode_lock.c b/source3/locking/share_mode_lock.c
index 51f09ae2af9..3b353d6793f 100644
--- a/source3/locking/share_mode_lock.c
+++ b/source3/locking/share_mode_lock.c
@@ -190,6 +190,10 @@ fail:
 	return NULL;
 }
 
+/*******************************************************************
+ Create a storable data blob from a modified share_mode_data struct.
+********************************************************************/
+
 static TDB_DATA unparse_share_modes(struct share_mode_data *d)
 {
 	DATA_BLOB blob;
@@ -214,6 +218,10 @@ static TDB_DATA unparse_share_modes(struct share_mode_data *d)
 	return make_tdb_data(blob.data, blob.length);
 }
 
+/*******************************************************************
+ If modified, store the share_mode_data back into the database.
+********************************************************************/
+
 static int share_mode_data_destructor(struct share_mode_data *d)
 {
 	NTSTATUS status;
@@ -266,6 +274,11 @@ static int share_mode_data_destructor(struct share_mode_data *d)
 	return 0;
 }
 
+/*******************************************************************
+ Allocate a new share_mode_data struct, mark it unmodified.
+ fresh is set to note that currently there is no database entry.
+********************************************************************/
+
 static struct share_mode_data *fresh_share_mode_lock(
 	TALLOC_CTX *mem_ctx, const char *servicepath,
 	const struct smb_filename *smb_fname,
@@ -306,6 +319,11 @@ fail:
 	return NULL;
 }
 
+/*******************************************************************
+ Either fetch a share mode from the database, or allocate a fresh
+ one if the record doesn't exist.
+********************************************************************/
+
 static struct share_mode_lock *get_share_mode_lock_internal(
 	TALLOC_CTX *mem_ctx, const struct file_id id,
 	const char *servicepath, const struct smb_filename *smb_fname,
@@ -365,6 +383,10 @@ static int the_lock_destructor(struct share_mode_lock *l)
 	return 0;
 }
 
+/*******************************************************************
+ Get a share_mode_lock, Reference counted to allow nexted calls.
+********************************************************************/
+
 struct share_mode_lock *get_share_mode_lock_fresh(
 	TALLOC_CTX *mem_ctx,
 	const struct file_id id,
@@ -405,6 +427,11 @@ fail:
 	return NULL;
 }
 
+/*******************************************************************
+ Get a share_mode_lock without locking the database or reference
+ counting. Used by smbstatus to display existing share modes.
+********************************************************************/
+
 struct share_mode_lock *fetch_share_mode_unlocked(TALLOC_CTX *mem_ctx,
 						  const struct file_id id)
 {
-- 
2.11.4.GIT