From 6e39efe7d783a9e5cdf366e6affbfe6e87af25f0 Mon Sep 17 00:00:00 2001
From: Olaf Barthel <obarthel@gmx.net>
Date: Mon, 4 Apr 2005 11:56:26 +0000
Subject: [PATCH] - Added a hopefully enlightening comment on the subtleties of
 semaphore   locking in the stdio_fflush.c file.

git-svn-id: file:///Users/olsen/Code/migration-svn-zu-git/logical-line-staging/clib2/trunk@14915 87f5fb63-7c3d-0410-a384-fd976d0f7a62
---
 library/include/complex.h |  4 ++--
 library/stdio_fflush.c    | 13 ++++++++++++-
 library/stdlib_main.c     |  4 ++--
 3 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/library/include/complex.h b/library/include/complex.h
index 3fa08a9..f623319 100644
--- a/library/include/complex.h
+++ b/library/include/complex.h
@@ -1,5 +1,5 @@
 /*
- * $Id: complex.h,v 1.1 2005-04-03 10:22:48 obarthel Exp $
+ * $Id: complex.h,v 1.2 2005-04-04 11:56:26 obarthel Exp $
  *
  * :ts=4
  *
@@ -65,7 +65,7 @@ extern "C" {
 
 /****************************************************************************/
 
-/* Basic types. */
+/* Basic types; imaginary is assumed not to be implemented yet. */
 #define complex _Complex
 
 /****************************************************************************/
diff --git a/library/stdio_fflush.c b/library/stdio_fflush.c
index 00276e2..635af40 100644
--- a/library/stdio_fflush.c
+++ b/library/stdio_fflush.c
@@ -1,5 +1,5 @@
 /*
- * $Id: stdio_fflush.c,v 1.6 2005-02-27 21:58:21 obarthel Exp $
+ * $Id: stdio_fflush.c,v 1.7 2005-04-04 11:56:22 obarthel Exp $
  *
  * :ts=4
  *
@@ -55,6 +55,17 @@ fflush(FILE *stream)
 	if(__check_abort_enabled)
 		__check_abort();
 
+	/* Subtlety alert: the thread-safe library needs to obtain locks for
+	   stdio, buffered files and file descriptors in a very particular
+	   order in order to steer clear of deadlocks. The order is as given
+	   above: stdio, buffered files, file descriptor table entries. Which
+	   normally means that if code has any business locking stdio or the
+	   file descriptor table entries, it should lock stdio first. This
+	   function, at least in the UNIX_PATH_SEMANTICS variant, does not do
+	   this. Here's why: if the 'stream' variable is NULL to start with,
+	   no per-stream locking is performed anyway, and the stdio lock can
+	   be obtained without running the risk of having obtain semaphores
+	   in the wrong order. */
 	flockfile(stream);
 
 	#if defined(UNIX_PATH_SEMANTICS)
diff --git a/library/stdlib_main.c b/library/stdlib_main.c
index 448a219..9a34dbb 100644
--- a/library/stdlib_main.c
+++ b/library/stdlib_main.c
@@ -1,5 +1,5 @@
 /*
- * $Id: stdlib_main.c,v 1.22 2005-04-01 18:46:37 obarthel Exp $
+ * $Id: stdlib_main.c,v 1.23 2005-04-04 11:56:22 obarthel Exp $
  *
  * :ts=4
  *
@@ -354,7 +354,7 @@ _main(void)
 			__stack_size = size;
 	}
 
-	/* How much stack size was provided? */
+	/* How much stack space was provided? */
 	current_stack_size = get_stack_size();
 
 	/* If this is a resident program, don't allow for the detach