haiku/docs/user/support/SupportDefs.dox

/*
 * Copyright 2007, Haiku, Inc. All Rights Reserved.
 * Distributed under the terms of the MIT License.
 *
 * Documentation by:
 *  Niels Sascha Reedijk <niels.reedijk@gmail.com>
 * Corresponds to:
 * /trunk/headers/os/support/SupportDefs.h rev 35018
 */

/*!
  \file SupportDefs.h
  \ingroup support
  \brief Defines basic types and definitions for the Haiku API.
*/

/*!
  \name Fixed-Size Integer Types
*/

//! @{

/*!
  \typedef	typedef __haiku_int8			int8
*/

/*!
	\typedef typedef __haiku_uint8			uint8
*/

/*!
	\typedef	typedef __haiku_int16			int16
*/

/*!
	\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 Fixed-size Volatile Types
*/

//! @{
	
/*!
	\typedef typedef volatile int8   		vint8
*/

/*!
	\typedef typedef volatile uint8			vuint8
*/

/*!
	\typedef typedef volatile int16			vint16
*/

/*!
	\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-hand Volatile Type Names
*/

//! @{

/*!
	\typedef typedef volatile long			vlong
*/

/*!
	\typedef typedef volatile int			vint
*/

/*!
	\typedef typedef volatile short			vshort
*/

/*!
	\typedef typedef volatile char			vchar
*/

/*!
	\typedef typedef volatile unsigned long	vulong
*/

/*!
	\typedef typedef volatile unsigned int	vuint
*/

/*!
	\typedef typedef volatile unsigned short	vushort
*/

/*!
	\typedef typedef volatile unsigned char	vuchar
*/

//! @}


/*!
  \name Character Type Formats
*/

//! @{

/*!
  \typedef typedef unsigned char			uchar
*/

/*!
  \typedef typedef unsigned short          unichar
*/

//! @}

/*!
  \name Descriptive Type Formats
*/

//! @{

/*!
  \typedef typedef int32					status_t
  \brief Represents one of the status codes defined in Error.h
*/

/*!
  \typedef typedef int64					bigtime_t
  \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
    values.
*/

/*!
  \typedef typedef uint32					perform_code
  \brief Unused. Defined by Be to support 'hidden' commands or
    extensions to classes. The Haiku API has none of these.
*/
  
//! @}
 

/*!
	\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
  
/*!
  \var const char *B_EMPTY_STRING
  \brief Defines an empty string. Currently defined as the C-string "".
*/

/*!
  \def min_c(a,b)
  \brief Returns the minimum of the values a and b.

  \note When including this header in a C file, use the C equivalent called 
    \c min(a,b).
*/

/*!
  \def max_c(a,b)
  \brief Returns the maximum of values a and b.

  \note When including this header in a C file, use the C equivalent called 
    \c max(a,b).
*/

/*!
  \def NULL
  \brief Defines the constant \c NULL if it hasn't been defined anywhere before. 
*/

/*!
  \addtogroup support_globals
*/

//! @{

/*!
  \fn int32	atomic_set(vint32 *value, int32 newValue)
  \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()
*/

/*!
  \fn int32	atomic_test_and_set(vint32 *value, int32 newValue, int32 testAgainst)
  \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()
*/

/*!
  \fn int32	atomic_add(vint32 *value, int32 addValue)
  \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()
*/

/*!
  \fn int32	atomic_and(vint32 *value, int32 andValue)
  \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()
*/


/*!
  \fn int32	atomic_or(vint32 *value, int32 orValue)
  \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()
*/

/*!
  \fn int32	atomic_get(vint32 *value)
  \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()
*/

/*!
  \fn int64	atomic_set64(vint64 *value, int64 newValue)
  \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()
*/

/*!
  \fn int64	atomic_test_and_set64(vint64 *value, int64 newValue, int64 testAgainst)
  \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()
*/

/*!
  \fn int64	atomic_add64(vint64 *value, int64 addValue)
  \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()
*/

/*!
  \fn int64	atomic_and64(vint64 *value, int64 andValue)
  \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()
*/

/*!
  \fn int64	atomic_or64(vint64 *value, int64 orValue)
  \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()
*/

/*!
  \fn int64	atomic_get64(vint64 *value)
  \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()
*/

//! @}

/*!
  \fn void*	get_stack_frame(void)
  \brief Internal function.
  \internal
*/

/*!
	\name Deprecated defines
*/

//! @{

/*!
  \def FALSE
  \brief Obsolete. Use \c false.
*/

/*!
  \def TRUE
  \brief Obsolete. Use \c true.
*/

//! @}