- 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/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)