vfs: check userland buffers before reading them.

[haiku.git] / docs / user / support / SupportDefs.dox

/*
 * Copyright 2007-2014 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *              Niels Sascha Reedijk, niels.reedijk@gmail.com
 *              John Scipione, jscipione@gmail.com
 *
 * Corresponds to:
 *              headers/os/support/SupportDefs.h        rev 35018
 */


/*!
        \file SupportDefs.h
        \ingroup support
        \ingroup libbe
        \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 Errors.h.

        \since BeOS R3
*/


/*!
        \typedef typedef int64 bigtime_t
        \brief Represents time. The unit depends on the context of the function.

        \since BeOS R3
*/


/*!
        \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.

        \since Haiku R1
*/


/*!
        \typedef typedef uint32 perform_code
        \brief Defined to support 'hidden' commands or extensions to classes.

        The Haiku API has none of these.

        \since Haiku R1
*/


//! @}


/*!
        \name Format strings for printf() and 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 string "".

        \since BeOS R3
*/


/*!
        \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).

        \since Haiku R1
*/


/*!
        \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).

        \since Haiku R1
*/


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

        \since BeOS R3
*/


/*!
        \addtogroup support_globals
*/


//! @{


/*!
        \fn void atomic_set(int32* 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. The variable must be naturally aligned.

        \sa atomic_set64() for a version that works on \c long \c long.
        \sa atomic_test_and_set()
        \sa atomic_add()
        \sa atomic_and()
        \sa atomic_or(),
        \sa atomic_get()

        \since Haiku R1
*/


/*!     \fn int32 atomic_get_and_set(int32* value, int32 newValue)
        \brief Atomically set the variable \a value to \a newvalue and return the
               old value.

        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_get_and_set64() for a version that works on \c long \c long.
        \sa atomic_set()
        \sa atomic_test_and_set()
        \sa atomic_add()
        \sa atomic_and()
        \sa atomic_or(),
        \sa atomic_get()

        \since Haiku R1
*/


/*!     \fn int32 atomic_test_and_set(int32* 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_get_and_set()
        \sa atomic_set()
        \sa atomic_add()
        \sa atomic_and()
        \sa atomic_or()
        \sa atomic_get()

        \since Haiku R1
*/


/*!
        \fn int32 atomic_add(int32* 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_get_and_set()
        \sa atomic_set()
        \sa atomic_test_and_set()
        \sa atomic_and()
        \sa atomic_or()
        \sa atomic_get()

        \since BeOS R3
*/


/*!     \fn int32 atomic_and(int32* 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 &= \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_get_and_set()
        \sa atomic_set()
        \sa atomic_test_and_set()
        \sa atomic_add()
        \sa atomic_or()
        \sa atomic_get()

        \since BeOS R3
*/


/*!
        \fn int32 atomic_or(int32* 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_get_and_set()
        \sa atomic_set()
        \sa atomic_test_and_set()
        \sa atomic_add()
        \sa atomic_and()
        \sa atomic_get()

        \since BeOS R3
*/


/*!
        \fn int32 atomic_get(int32* 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. The variable must be naturally aligned.

        \return The original value of \c value.

        \sa atomic_get64() for a version that works on \c long \c long.
        \sa atomic_get_and_set()
        \sa atomic_set()
        \sa atomic_test_and_set()
        \sa atomic_add()
        \sa atomic_and()
        \sa atomic_or()

        \since Haiku R1
*/


/*!
        \fn void atomic_set64(int64* 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. The variable must be naturally aligned.

        \sa atomic_set() for a version that works on an \c int32.
        \sa atomic_get_and_set64()
        \sa atomic_test_and_set64()
        \sa atomic_add64()
        \sa atomic_and64()
        \sa atomic_or64()
        \sa atomic_get64()

        \since Haiku R1
*/


/*!
        \fn int64 atomic_get_and_set64(int64* value, int64 newValue)
        \brief Atomically set the variable \a value to \a newvalue and return
               the old value.

        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_get_and_set() for a version that works on an \c int32.
        \sa atomic_set64()
        \sa atomic_test_and_set64()
        \sa atomic_add64()
        \sa atomic_and64()
        \sa atomic_or64()
        \sa atomic_get64()

        \since Haiku R1
*/


/*!
        \fn int64 atomic_test_and_set64(int64* 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_get_and_set64()
        \sa atomic_set64()
        \sa atomic_add64()
        \sa atomic_and64()
        \sa atomic_or64()
        \sa atomic_get64()

        \since Haiku R1
*/


/*!
        \fn int64 atomic_add64(int64* 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_get_and_set64()
        \sa atomic_set64()
        \sa atomic_test_and_set64()
        \sa atomic_and64()
        \sa atomic_or64()
        \sa atomic_get64()

        \since Haiku R1
*/


/*!
        \fn int64 atomic_and64(int64* 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 &= \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_get_and_set64()
        \sa atomic_set64()
        \sa atomic_test_and_set64()
        \sa atomic_add64()
        \sa atomic_or64()
        \sa atomic_get64()

        \since Haiku R1
*/


/*!
        \fn int64 atomic_or64(int64* 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_get_and_set64()
        \sa atomic_set64()
        \sa atomic_test_and_set64()
        \sa atomic_add64()
        \sa atomic_and64()
        \sa atomic_get64()

        \since Haiku R1
*/


/*!
        \fn int64 atomic_get64(int64* 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. The variable must be naturally aligned.

        \return The original value of \c value.

        \sa atomic_get() for a version that works on an \c int32.
        \sa atomic_get_and_set64()
        \sa atomic_set64()
        \sa atomic_test_and_set64()
        \sa atomic_add64()
        \sa atomic_and64()
        \sa atomic_or64()

        \since Haiku R1
*/


//! @}


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


/*!
        \name Deprecated defines
*/


//! @{


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

        \since BeOS R3
*/


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

        \since BeOS R3
*/


//! @}