builtins(4)builtins(4)NAME
builtins.h - Header file declaring functions that are unconditionally
intrinsic.
SYNOPSIS
#include <builtins.h>
DESCRIPTION
A builtin is a function whose name is specially recognized by the com‐
piler and is similar to declaring the function to be intrinsic.
Intrinsic functions are functions for which the C compiler generates
optimized code in certain situations possibly avoiding a function call.
While intrinsic functions can have their special treatment enabled or
disabled by pragmas, builtin functions are always treated specially and
always have names in the reserved namespace.
Builtin functions allow you to directly access hardware and machine
instructions to perform operations that are cumbersome, slow, or impos‐
sible to implement in the C language. While the user of inline assem‐
bly code can provide similar capabilities, builtin functions provide a
higher-level interface for some common operations that are complex to
implement well in assembly language. See the file for further informa‐
tion on asm in-line assembly language generator functions.
These functions are very efficient because they are built into the DEC
C (-newc) compiler. This means that a call to one of these functions
does not result in a reference to a function in the run-time library
or to a function in your program. Instead, the compiler generates the
machine instructions necessary to carry out the function directly at
the call site.
Be sure to include the <builtins.h> header file in your source program
to access these built-in functions and add a line similar to the fol‐
lowing to the cc command line (the file is not located in the default
header file directory (/usr/include)). -I /usr/includemachine
Note that by convention, the suffixes _LONG and _QUAD designate,
respectively, 32-bit longword and 64-bit quadword operations (as
defined by the Alpha architecture). In particular, the _LONG suffix
designating a 32-bit longword, should not be confused with the C lan‐
guage type long, which is 64-bits on Tru64 UNIX.
The following describes the DEC C (-newc) built-in functions available
on Tru64 UNIX. Note that the return value is always the old value of
the location before the operation is performed. The retry variants
provide successful status through the status pointer. The only excep‐
tions are the __LOCK_LONG_RETRY and __ACQUIRE_SEM_LONG_RETRY functions.
Atomic Add Longword
The __ATOMIC_ADD_LONG function adds the specified expression to
the aligned longword pointed to by the address parameter within
a load-locked/store-conditional code sequence and returns the
value of the longword before the addition was performed.
This function has one of the following formats:
int __ATOMIC_ADD_LONG (
volatile void *__address,
int __expression);
int __ATOMIC_ADD_LONG_RETRY (
volatile void *__address,
int __expression,
int __retry,
int *__status); address
The longword-aligned address ofthe data segment. expression
An integer expression. retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. status
A pointer to an integer that is set to 0 if the operation did
not succeed within the specified number of retries, and set to 1
if the operation succeeded. Atomic Add Quadword
The __ATOMIC_ADD_QUAD function adds the specified expression to
the aligned quadword pointed to by the address parameter within
a load-locked/store-conditional code sequence and returns the
value of the quadword before the operation was performed.
This function has one of the following formats:
long __ATOMIC_ADD_QUAD (
volatile void *__address,
long __expression);
long __ATOMIC_ADD_QUAD_RETRY (
volatile void *__address,
long __expression,
int __retry,
int *__status); address
The quadword-aligned address of the data segment. expression
An expression of type long. retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. status
A pointer to an integer that is set to 0 if the operation did
not succeed with in the specified number of retries, and set to
1 if the operation succeeded. Atomic AND Longword
The __ATOMIC_AND_LONG function performs a logical AND of the
specified expression with the aligned longword pointed to by the
address parameter within a load-locked/store-conditional code
sequence and returns the value of the longword before the addi‐
tion was performed.
This function has one of the following formats:
int __ATOMIC_AND_LONG (
volatile void *__address,
int __expression);
int __ATOMIC_AND_LONG_RETRY (
volatile void *__address,
int __expression,
int __retry,
int *__status); address
The longword-aligned address of the data segment. expression
An integer expression. retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. status
A pointer to an integer that is set to 0 if the operation did
not succeed with in the specified number of retries, and set to
1 if the operation succeeded. Atomic AND Quadword
The __ATOMIC_AND_QUAD function performs a logical AND of the
specified expression with the aligned quadword pointed to by the
address parameter within a load-locked/store-conditional code
sequence and returns the value of the longword before the addi‐
tion was performed.
This function has one of the following formats:
long __ATOMIC_AND_QUAD (
volatile void *__address,
long __expression);
long __ATOMIC_AND_QUAD_RETRY (
volatile void *__address,
long __expression,
int __retry,
int *__status); address
The quadword-aligned address of the data segment. expression
An expression of type long. retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. status
A pointer to an integer that is set to 0 if the operation did
not succeed with in the specified number of retries, and set to
1 if the operation succeeded. Atomic OR Longword
The __ATOMIC_OR_LONG function performs a logical OR of the spec‐
ified expression with the aligned longword pointed to by the
address parameter within a load-locked/store-conditional code
sequence and returns the value of the longword before the addi‐
tion was performed.
This function has one of the following formats:
int __ATOMIC_OR_LONG (
volatile void *__address,
int __expression);
int __ATOMIC_OR_LONG_RETRY (
volatile void *__address,
int __expression,
int __retry,
int *__status); address
The longword-aligned address of the data segment. expression
An integer expression. retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. status
A pointer to an integer that is set to 0 if the operation did
not succeed with in the specified number of retries, and set to
1 if the operation succeeded. Atomic OR Quadword
The __ATOMIC_OR_QUAD function performs a logical OR of the spec‐
ified expression with the aligned quadword pointed to by the
address parameter within a load-locked/store-conditional code
sequence and returns the value of the longword before the addi‐
tion was performed.
This function has one of the following formats:
long __ATOMIC_OR_QUAD (
volatile void *__address,
long __expression);
long __ATOMIC_OR_QUAD_RETRY (
volatile void *__address,
long __expression,
int __retry,
int *__status);
address
The quadword-aligned address of the data segment. expression
An expression of type long. retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. status
A pointer to an integer that is set to 0 if the operation did
not succeed with in the specified number of retries, and set to
1 if the operation succeeded. Atomic Increment Longword
The __ATOMIC_INCREMENT_LONG function increments by 1 the aligned
longword pointed to by the address parameter within a load-
locked/store-conditional code sequence and returns the value of
the longword before the addition was performed.
This function has the following format:
int __ATOMIC_INCREMENT_LONG (
volatile void *__address); address
The longword-aligned address of the data segment. Atomic Incre‐
ment Quadword
The __ATOMIC_INCREMENT_QUAD function increments by 1 the aligned
quadword pointed to by the address parameter within a load-
locked/store-conditional code sequence and returns the value of
the longword before the addition was performed.
This function has the following format:
long __ATOMIC_INCREMENT_QUAD (
volatile void *__address); address
The quadword-aligned address of the data segment. Atomic Decre‐
ment Longword
The __ATOMIC_DECREMENT_LONG function decrements by 1 the aligned
longword pointed to by the address parameter within a load-
locked/store-conditional code sequence and returns the value of
the longword before the addition was performed.
This function has the following format:
int __ATOMIC_DECREMENT_LONG (
volatile void *__address); address
The longword-aligned address of the data segment. Atomic Decre‐
ment Quadword
The __ATOMIC_DECREMENT_QUAD function decrements by 1 the aligned
quadword pointed to by the address parameter within a load-
locked/store-conditional code sequence and returns the value of
the longword before the addition was performed.
This function has the following format:
long __ATOMIC_DECREMENT_QUAD (
volatile void *__address); address
The quadword-aligned address of the data segment. Atomic
Exchange Longword
The __ATOMIC_EXCH_LONG function stores the value of the speci‐
fied expression into the aligned longword specified by the
address parameter within a load-locked/store-conditional code
sequence, and returns the value of the longword before the store
was performed.
This function has one of the following formats:
int __ATOMIC_EXCH_LONG (
volatile void *__address,
int __expression);
int __ATOMIC_EXCH_LONG_RETRY (
volatile void *__address,
int __expression,
int __retry,
int *__status); address
The longword-aligned address of the data segment. expression
An integer expression. retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. status
A pointer to an integer that is set to 0 if the operation did
not succeed with in the specified number of retries, and set to
1 if the operation succeeded. Atomic Exchange Quadword
The __ATOMIC_EXCH_QUAD function stores the value of the speci‐
fied expression into the aligned quadword specified by the
address parameter within a load-locked/store-conditional code
sequence, and returns the value of the quadword before the store
was performed.
This function has one of the following formats:
long __ATOMIC_EXCH_QUAD (
volatile void *__address,
long __expression);
long __ATOMIC_EXCH_QUAD_RETRY (
volatile void *__address,
long __expression,
int __retry,
int *__status); address
The quadword-aligned address of the data segment. expression
An expression of type long. retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. status
A pointer to an integer that is set to 0 if the operation did
not succeed with in the specified number of retries, and set to
1 if the operation succeeded. Test for Bit Clear Then Clear Bit
Interlocked
The __INTERLOCKED_TESTBITCC_QUAD function performs the following
functions in interlocked fashion: Returns the complement of the
specified bit before being cleared Clears the bit
This function has one of the following formats:
int __INTERLOCKED_TESTBITCC_QUAD (
volatile void *__address, int __bit_position);
int __INTERLOCKED_TESTBITCC_QUAD_RETRY (
volatile void *__address,
int __bit_position,
int __retry,
int *__status); address
The quadword-aligned base address of the bit field. position
The position within the field of the bit that you want cleared,
in the range of 0 to 63. retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. status
A pointer to an integer that is set to 0 if the operation did
not succeed with in the specified number of retries, and set to
1 if the operation succeeded. Test for Bit Set Then Set Bit
Interlocked
The __INTERLOCKED_TESTBITSS_QUAD function performs the following
operations in interlocked fashion: Returns the value of the
specified bit before being set Sets the bit
This function has one of the following formats:
int __INTERLOCKED_TESTBITSS_QUAD (
volatile void *__address,
int __bit_position);
int __INTERLOCKED_TESTBITSS_QUAD_RETRY (
volatile void *__address,
int __bit_position,
int __retry,
int *__status); address
The quadword-aligned base address of the bit field. position
The position within the field of the bit that you want set, in
the range of 0 to 63. retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. status
A pointer to an integer that is set to 0 if the operation did
not succeed with in the specified number of retries, and set to
1 if the operation succeeded. Lock and Unlock Longword
The __LOCK_LONG and __UNLOCK_LONG functions provide a binary
spinlock capability based on the low-order bit of a longword.
The __LOCK_LONG function executes in a loop waiting for the bit
to be cleared and then sets it within a load-locked/store-condi‐
tional sequence; it then issues a memory barrier. The
__UNLOCK_LONG function issues a memory barrier and then zeroes
the longword.
The __LOCK_LONG_RETRY function returns 1 if the lock was
acquired within the specified number of returns and 0 if the
lock was not acquired.
This function has one of the following formats:
void __LOCK_LONG (
volatile void *__address);
int __LOCK_LONG_RETRY (
volatile void *__address,
int __retry);
The __UNLOCK_LONG function has the following format:
void __UNLOCK_LONG (
volatile void *__address); address
The quadword-aligned address of the longword used for the lock.
retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. Acquire and
Release Longword Semaphore
The __ACQUIRE_SEM_LONG and__RELEASE_SEM_LONG functions provide a
counted semaphore capability where the positive value of a long‐
word is interpreted as the number of resources are available.
The __ACQUIRE_SEM_LONG function loops until the longword has a
positive value and then decrements it within a load-
locked/store-conditional sequence; it then issues a memory bar‐
rier. The __RELEASE_SEM_LONG function issues a memory barrier
and then does an _ATOMIC_INCREMENT_LONG on the longword. The
__ACQUIRE_SEM_LONG_RETRY function returns 1 if the resource
count was successfully decremented within the specified number
of retries, and 0 otherwise. Acquire Semaphore Longword
The __ACQUIRE_SEM_LONG function has one of the following for‐
mats:
void __ACQUIRE_SEM_LONG (
volatile void *__address);
int __ACQUIRE_SEM_LONG_RETRY (
volatile void *__address,
int __retry); address
The longword-aligned address of the resource count. retry
A count of type int. The retry count indicates the number of
times the operation is attempted (which will be at least once
even if the count argument is 0). If the operation cannot be
performed successfully in the specified number of retries, the
function returns without updating the longword. Release Sema‐
phore Longword
The __RELEASE_SEM_LONG function has the following format:
void __RELEASE_SEM_LONG (
volatile void *__address); address
The longword-aligned address of the resource count. Compare and
Store Longword
The __CMP_STORE_LONG function has the following format:
int __CMP_STORE_LONG (
volatile void *__source,
int __old_value,
int __new_value,
volatile void *__dest);
This function performs a conditional atomic compare and update
operation involving one or two longwords in the same lock
region. The value pointed to by source is compared with the
longword old_value. If they are equal, the longword new_value
is conditionally stored into the longword pointed to by dest.
The store will not complete if the compare yields unequal values
or if there is an intervening store to the lock region involved.
To be in the same lock region, source and dest must point to
aligned longwords in the same naturally aligned 16-byte region.
The function returns 0 if the store does not complete, and
returns 1 if the store does complete. Compare and Store Quad‐
word
The __CMP_STORE_QUAD function has the following format:
int __CMP_STORE_QUAD (
volatile void *__source,
long __old_value,
long __new_value,
volatile void *__dest);
This function performs a conditional atomic compare and update
operation involving one or two quadwords in the same lock
region. The value pointed to by source is compared with the
quadword old_value. If they are equal, the quadword new_value
is conditionally stored into the quadword pointed to by dest.
The store will not complete if the compare yields unequal values
or if there is an intervening store to the lock region involved.
To be in the same lock region, source and dest must point to
aligned quadwords in the same naturally aligned 16-byte region.
The function returns 0 if the store does not complete, and
returns 1 if the store does complete. Add Aligned Word Inter‐
locked
The __ADAWI function adds its source operand to the destination.
This function is interlocked against similar operations by other
processors or devices in the system and is provided to emulate
the VAX instructions of that name. This function returns the
value of bits 0:3 of a VAX Program Status Longword.
The __ADAWI function has the following format:
int __ADAWI (
short __src,
volatile short *__dest); __src
The value to be added to the destination. __dest
A pointer to the destination. The destination must be aligned
on a word boundary.
Because of their prior availability on the OpenVMS Alpha platform,
there are a number of additional builtins that are recognized by DEC C
and declared in the builtins.h file. These builtins should not gener‐
ally be used in new code. These include a number of atomic/interlocked
operations that issue memory barriers before and after the load-
locked/store-conditional sequence, and some single-instruction func‐
tions that are more naturally implemented using the asm facility. The
referenced header files contain more specific information.
FILES
/usr/include/machine/builtins.h
RELATED INFORMATION
Functions: asm, fasm, dasm
cc (1)
Programmer's Guide
Files: /usr/include/c_asm.h delim off
builtins(4)