Update the SupportDefs documentation for several changes and document the atomic_* functions.

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@35148 a95241bf-73f2-0310-859d-f6bbb57e9c96

docs/user/support/SupportDefs.dox

@@ -5,7 +5,7 @@
  * Documentation by:
  *  Niels Sascha Reedijk <[email protected]>
  * Corresponds to:
- * /trunk/headers/os/support/SupportDefs.h rev 19972
+ * /trunk/headers/os/support/SupportDefs.h rev 35018
  */
 
 /*!
@@ -15,103 +15,89 @@
 */
 
 /*!
-  \name Short byte long Type Formats
+  \name Fixed-Size Integer Types
 */
 
 //! @{
 
 /*!
-  \typedef typedef	signed char				int8
+  \typedef	typedef __haiku_int8			int8
 */
 
 /*!
-  \typedef typedef unsigned char			uint8
+	\typedef typedef __haiku_uint8			uint8
 */
 
 /*!
-  \typedef typedef volatile signed char   	vint8
+	\typedef	typedef __haiku_int16			int16
 */
 
 /*!
-  \typedef typedef volatile unsigned char	vuint8
+	\typedef typedef __haiku_uint16			uint16
+*/
+
+/*!
+	\typedef	typedef __haiku_int32			int32
+*/
+
+/*!
+	\typedef typedef __haiku_uint32			uint32
+*/
+
+/*!
+	\typedef	typedef __haiku_int64			int64
+*/
+
+/*!
+	\typedef typedef __haiku_uint64			uint64
 */
 
 //! @}
 
+
 /*!
-  \name Short 2-byte long Type Formats
+	\name Fixed-size Volatile Types
 */
 
 //! @{
 	
 /*!
-  \typedef typedef	short					int16
+	\typedef typedef volatile int8   		vint8
 */
 
 /*!
-  \typedef typedef unsigned short			uint16
+	\typedef typedef volatile uint8			vuint8
 */
 
 /*!
-  \typedef typedef volatile short			vint16
+	\typedef typedef volatile int16			vint16
 */
 
 /*!
-  \typedef typedef volatile unsigned short	vuint16
+	\typedef typedef volatile uint16			vuint16
+*/
+
+/*!
+	\typedef typedef volatile int32			vint32
+*/
+
+/*!
+	\typedef typedef volatile uint32			vuint32
+*/
+
+/*!
+	\typedef typedef volatile int64			vint64
+*/
+
+/*!
+	\typedef typedef volatile uint64			vuint64
 */
 
 //! @}
 
-/*!
-  \name Short 4-byte long Type Formats
-*/
-
-//! @{
 
 /*!
-  \typedef typedef	long					int32
+	\name Short-hand Volatile Type Names
-*/
-
-/*!
-  \typedef typedef unsigned long			uint32
-*/
-
-/*!
-  \typedef typedef volatile long			vint32
-*/
-
-/*!
-  \typedef typedef volatile unsigned long	vuint32
-*/
-
-//! @}
-
-/*!
-  \name Short 8-byte long Type Formats
-*/
-
-//! @{
-
-/*!
-  \typedef typedef	long long				int64
-*/
-
-/*!
-  \typedef typedef unsigned long long		uint64
-*/
-
-/*!
-  \typedef typedef volatile long long		vint64
-*/
-
-/*!
-  \typedef typedef volatile unsigned long long	vuint64
-*/
-
-//! @}
-
-/*!
-  \name Short volatile Type Formats
 */
 
 //! @{
@@ -150,6 +136,7 @@
 
 //! @}
 
+
 /*!
   \name Character Type Formats
 */
@@ -182,6 +169,11 @@
   \brief Represents time. The unit depends on the context of the function.
 */
 
+/*!
+	\typedef typedef int64					nanotime_t
+	\brief Represents time in nanoseconds.
+*/
+
 /*!
   \typedef typedef uint32					type_code
   \brief Represents a certain type of data. See TypeConstants.h for possible
@@ -196,6 +188,290 @@
   
 //! @}
  
+
+/*!
+	\name Format strings for printf()/scanf()
+*/
+
+//! @{
+
+/*!
+	\def B_PRId8
+*/
+
+/*!
+	\def B_PRIi8
+*/
+
+/*!
+	\def B_PRId16
+*/
+
+/*!
+	\def B_PRIi16
+*/
+
+/*!
+	\def B_PRId32
+*/
+
+/*!
+	\def B_PRIi32
+*/
+
+/*!
+	\def B_PRId64
+*/
+
+/*!
+	\def B_PRIi64
+*/
+
+/*!
+	\def B_PRIu8
+*/
+
+/*!
+	\def B_PRIo8
+*/
+
+/*!
+	\def B_PRIx8
+*/
+
+/*!
+	\def B_PRIX8
+*/
+
+/*!
+	\def B_PRIu16
+*/
+
+/*!
+	\def B_PRIo16
+*/
+
+/*!
+	\def B_PRIx16
+*/
+
+/*!
+	\def B_PRIX16
+*/
+
+/*!
+	\def B_PRIu32
+*/
+
+/*!
+	\def B_PRIo32
+*/
+
+/*!
+	\def B_PRIx32
+*/
+
+/*!
+	\def B_PRIX32
+*/
+
+/*!
+	\def B_PRIu64
+*/
+
+/*!
+	\def B_PRIo64
+*/
+
+/*!
+	\def B_PRIx64
+*/
+
+/*!
+	\def B_PRIX64
+*/
+
+/*!
+	\def B_SCNd8
+*/
+
+/*!
+	\def B_SCNi8
+*/
+
+/*!
+	\def B_SCNd16
+*/
+
+/*!
+	\def B_SCNi16
+*/
+
+/*!
+	\def B_SCNd32
+*/
+
+/*!
+	\def B_SCNi32
+*/
+
+/*!
+	\def B_SCNd64
+*/
+
+/*!
+	\def B_SCNi64
+*/
+
+/*!
+	\def B_SCNu8
+*/
+
+/*!
+	\def B_SCNo8
+*/
+
+/*!
+	\def B_SCNx8
+*/
+
+/*!
+	\def B_SCNu16
+*/
+
+/*!
+	\def B_SCNo16
+*/
+
+/*!
+	\def B_SCNx16
+*/
+
+/*!
+	\def B_SCNu32
+*/
+
+/*!
+	\def B_SCNo32
+*/
+
+/*!
+	\def B_SCNx32
+*/
+
+/*!
+	\def B_SCNu64
+*/
+
+/*!
+	\def B_SCNo64
+*/
+
+/*!
+	\def B_SCNx64
+*/
+
+//! @}
+
+
+/*!
+	\name  Format strings for several standard types
+*/
+
+//! @{
+
+/*!
+	\def B_PRIuSIZE
+	\brief size_t
+*/
+
+/*!
+	\def B_PRIoSIZE
+	\brief size_t
+*/
+
+/*!
+	\def B_PRIxSIZE
+	\brief size_t
+*/
+
+/*!
+	\def B_PRIXSIZE
+	\brief size_t
+*/
+
+/*!
+	\def B_PRIdSSIZE
+	\brief ssize_t
+*/
+
+/*!
+	\def B_PRIiSSIZE
+	\brief ssize_t
+*/
+
+/*!
+	\def B_PRIuADDR
+	\brief addr_t
+*/
+
+/*!
+	\def B_PRIoADDR
+	\brief addr_t
+*/
+
+/*!
+	\def B_PRIxADDR
+	\brief addr_t
+*/
+
+/*!
+	\def B_PRIXADDR
+	\brief addr_t
+*/
+
+/*!
+	\def B_PRIdOFF
+	\brief off_t
+*/
+
+/*!
+	\def B_PRIiOFF
+	\brief off_t
+*/
+
+/*! 
+	\def B_PRIdDEV
+	\brief dev_t
+*/
+
+/*!
+	\def B_PRIiDEV
+	\brief dev_t
+*/
+
+/*!
+	\def B_PRIdINO
+	\brief ino_t
+*/
+
+/*!
+	\def B_PRIiINO
+	\brief ino_t
+*/
+
+/*! 
+	\def B_PRIdTIME
+	\brief time_t
+*/
+
+/*!
+	\def B_PRIiTIME
+	\brief time_t
+*/
+
+//! @}
+
 //////////////// Odds and ends
   
 /*!
@@ -232,7 +508,15 @@
 
 /*!
   \fn int32	atomic_set(vint32 *value, int32 newValue)
-  \brief Undocumented.
+  \brief Atomically set the variable \a value to \a newvalue.
+  
+	This is a thread-safe way of performing the \c *value \c = \c newValue
+	operation. You should use these function when two or more threads might
+	access the variable simultaneously. You don't have to use a semaphore or a
+	mutex in this case. 
+	
+	\return The original value of \c value.	
+	
 	\sa atomic_set64() for a version that works on \c long \c long
   \sa atomic_test_and_set(), atomic_add(), atomic_and(),
     atomic_or(), atomic_get()
@@ -240,7 +524,15 @@
 
 /*!
   \fn int32	atomic_test_and_set(vint32 *value, int32 newValue, int32 testAgainst)
-  \brief Undocumented.
+  \brief Atomically set the variable \a value to \a newValue if the current
+         value is \a testAgainst.
+  
+	This is a thread-safe way of conditionally performing the \c *value \c += 
+	\c newValue operation. You should use these function when two or more threads
+	might access the variable simultaneously. You don't have to use a semaphore
+	or a mutex in this case. 
+	
+	\return The original value of \c value.
   \sa atomic_test_and_set64() for a version that works on \c long \c long
   \sa atomic_set(), atomic_add(), atomic_and(),
     atomic_or(), atomic_get()
@@ -248,7 +540,14 @@
 
 /*!
   \fn int32	atomic_add(vint32 *value, int32 addValue)
-  \brief Undocumented.
+  \brief Atomically add the value of \a addValue to \a value.
+  
+	This is a thread-safe way of performing the \c *value \c += \c addValue
+	operation. You should use these function when two or more threads might
+	access the variable simultaneously. You don't have to use a semaphore or a
+	mutex in this case. 
+	
+	\return The original value of \c value.
   \sa atomic_add64() for a version that works on \c long \c long
   \sa atomic_set(), atomic_test_and_set(), atomic_and(),
     atomic_or(), atomic_get()
@@ -256,7 +555,15 @@
 
 /*!
   \fn int32	atomic_and(vint32 *value, int32 andValue)
-  \brief Undocumented.
+  \brief Atomically perform a bitwise AND operation of \a andValue to the 
+         variable \a andValue.
+
+	This is a thread-safe way of performing the \c *value \c &amp;= \c andValue
+	operation. You should use these function when two or more threads might
+	access the variable simultaneously. You don't have to use a semaphore or a
+	mutex in this case. 
+
+	\return The original value of \c value.
   \sa atomic_and64() for a version that works on \c long \c long
   \sa atomic_set(), atomic_test_and_set(), atomic_add(),
     atomic_or(), atomic_get()
@@ -265,7 +572,15 @@
 
 /*!
   \fn int32	atomic_or(vint32 *value, int32 orValue)
-  \brief Undocumented.
+  \brief Atomically perform a bitwise OR operation of \a orValue to the 
+         variable \a andValue.
+
+	This is a thread-safe way of performing the \c *value \c |= \c orValue
+	operation. You should use these function when two or more threads might
+	access the variable simultaneously. You don't have to use a semaphore or a
+	mutex in this case. 
+
+	\return The original value of \c value.
   \sa atomic_or64() for a version that works on \c long \c long
   \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
     atomic_get()
@@ -273,7 +588,14 @@
 
 /*!
   \fn int32	atomic_get(vint32 *value)
-  \brief Undocumented.
+  \brief Atomically return the value of \c value.
+
+	This is a thread-safe way of reading the contents of the \c value
+	operation. You should use these function when two or more threads might
+	access the variable simultaneously. You don't have to use a semaphore or a
+	mutex in this case. 
+
+	\return The original value of \c value.
   \sa atomic_get64() for a version that works on \c long \c long
   \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
     atomic_or()
@@ -281,7 +603,15 @@
 
 /*!
   \fn int64	atomic_set64(vint64 *value, int64 newValue)
-  \brief Undocumented.
+  \brief Atomically set the variable \a value to \a newvalue.
+
+	This is a thread-safe way of performing the \c *value \c = \c newValue
+	operation. You should use these function when two or more threads might
+	access the variable simultaneously. You don't have to use a semaphore or a
+	mutex in this case. 
+
+	\return The original value of \c value.
+
   \sa atomic_set() for a version that works on an \c int32
   \sa atomic_test_and_set64(), atomic_add64(), atomic_and64(),
     atomic_or64(), atomic_get64()
@@ -289,7 +619,15 @@
 
 /*!
   \fn int64	atomic_test_and_set64(vint64 *value, int64 newValue, int64 testAgainst)
-  \brief Undocumented.
+  \brief Atomically set the variable \a value to \a newValue if the current
+         value is \a testAgainst.
+  
+	This is a thread-safe way of conditionally performing the \c *value \c += 
+	\c newValue operation. You should use these function when two or more threads
+	might access the variable simultaneously. You don't have to use a semaphore
+	or a mutex in this case. 
+	
+	\return The original value of \c value.
   \sa atomic_test_and_set() for a version that works on an \c int32
   \sa atomic_set64(), atomic_add64(), atomic_and64(),
     atomic_or64(), atomic_get64()
@@ -297,7 +635,14 @@
 
 /*!
   \fn int64	atomic_add64(vint64 *value, int64 addValue)
-  \brief Undocumented.
+  \brief Atomically add the value of \a addValue to \a value.
+  
+	This is a thread-safe way of performing the \c *value \c += \c addValue
+	operation. You should use these function when two or more threads might
+	access the variable simultaneously. You don't have to use a semaphore or a
+	mutex in this case. 
+	
+	\return The original value of \c value.
   \sa atomic_add() for a version that works on an \c int32
   \sa atomic_set64(), atomic_test_and_set64(), atomic_and64(),
     atomic_or64(), atomic_get64()
@@ -305,7 +650,15 @@
 
 /*!
   \fn int64	atomic_and64(vint64 *value, int64 andValue)
-  \brief Undocumented.
+  \brief Atomically perform a bitwise AND operation of \a andValue to the 
+         variable \a andValue.
+
+	This is a thread-safe way of performing the \c *value \c &amp;= \c andValue
+	operation. You should use these function when two or more threads might
+	access the variable simultaneously. You don't have to use a semaphore or a
+	mutex in this case. 
+
+	\return The original value of \c value.
   \sa atomic_and() for a version that works on an \c int32
   \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(),
     atomic_or64(), atomic_get64()
@@ -313,7 +666,15 @@
 
 /*!
   \fn int64	atomic_or64(vint64 *value, int64 orValue)
-  \brief Undocumented.
+  \brief Atomically perform a bitwise OR operation of \a orValue to the 
+         variable \a andValue.
+
+	This is a thread-safe way of performing the \c *value \c |= \c orValue
+	operation. You should use these function when two or more threads might
+	access the variable simultaneously. You don't have to use a semaphore or a
+	mutex in this case. 
+
+	\return The original value of \c value.
   \sa atomic_or() for a version that works on an \c int32
   \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(),
     atomic_get64()
@@ -321,7 +682,14 @@
 
 /*!
   \fn int64	atomic_get64(vint64 *value)
-  \brief Undocumented.
+  \brief Atomically return the value of \c value.
+
+	This is a thread-safe way of reading the contents of the \c value
+	operation. You should use these function when two or more threads might
+	access the variable simultaneously. You don't have to use a semaphore or a
+	mutex in this case. 
+
+	\return The original value of \c value.
   \sa atomic_get() for a version that works on an \c int32
   \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(),
     atomic_or64()
@@ -331,10 +699,14 @@
 
 /*!
   \fn void*	get_stack_frame(void)
-  \brief This is internal, I guess. Else this needs to be documented.
+  \brief Internal function.
   \internal
 */
 
+/*!
+	\name Deprecated defines
+*/
+
 //! @{
 
 /*!