added comments about reentrancy and exception safeness

git-svn-id: svn://bind10.isc.org/svn/bind10/branches/trac268@2667 e5f2f494-b856-4b98-b285-d166d9295462

src/bin/auth/change_user.h

@@ -19,7 +19,17 @@
 
 /// \brief Change the run time user.
 ///
-/// This function changes the user of the authoritative server process.
+/// This function changes the user and its group of the authoritative server
+/// process.
+///
+/// On success the user ID of the process is changed to the specified user,
+/// and the group is changed to that of the new user.
+///
+/// This is considered a short term workaround until we develop clearer
+/// privilege separation, where the server won't even have to open privileged
+/// ports and can be started by a non privileged user from the beginning.
+/// This function therefore ignores some corner case problems (see below)
+/// which we would address otherwise.
 ///
 /// \c username can be either a textual user name or its numeric ID.
 /// If the specified user name (or ID) doesn't specify a local user ID
@@ -27,6 +37,18 @@
 /// of changing the user to \c username, this function throws an exception
 /// of class \c FatalError.
 ///
+/// This function internally uses system libraries that do not guarantee
+/// reentrancy.  In fact, it doesn't even expect to be called more than once.
+/// The behavior is undefined if this function is called from multiple threads
+/// simultaneously or more generally called multiple times.
+///
+/// This function only offers the basic exception guarantee, that is, if
+/// an exception is thrown from this function, it's possible that an exception
+/// is thrown after changing the group ID.  This function doesn't recover
+/// from that situation.  In practice, the process is expected to consider
+/// this event a fatal error and will immediately exit, and shouldn't cause
+/// a real trouble.
+///
 /// \param username User name or ID of the new effective user.
 void changeUser(const char* const username);